# AIOT 文档建设蓝图与执行方案

## A. 《AIOT 文档建设蓝图》

### 1. 文档建设目标
- **终结“代码与文档脱节”**：将文档确立为业务流转、Agent协作、新人入职的核心资产，与代码同等对待。
- **精准映射项目进度**：清晰展现一阶段（保洁/安保/Ops核心）已完成并转入迭代的现状，以及 4 月份向 IoT 业务转移的重心。
- **提供多维立体视角**：通过分层结构，满足产品看业务、前端/移动端看接口联调、后端看底层实现、运维看部署排障的不同诉求。

### 2. 文档分层设计
结合真实的 AIOT 场景，建议采用**四维分层模型**：
- **高维（全局/业务层）**：业务域蓝图、系统总体架构、全端进度状态矩阵（核心关注：进度与可用性）。
- **中维（链路/协作层）**：跨端业务串联（如：IoT 报警 -> Ops 工单生成 -> 移动端抢单的全链路），重在时序与交互。
- **低维（实现/工程层）**：各主仓（后端 Java、前端 Vue、移动端 UniApp）的落地细节、核心包/类索引。
- **基建（规范/字典层）**：术语表、核心表结构、枚举字典字典、前后端规约。

### 3. 建议目录结构（整合优化版）
针对现有结构过于零散且存在大量“空壳”的问题，建议调整如下：
```text
/开发者文档
├── 00-项目总览与进度 (新增，存放核心进度矩阵和阅读向导)
├── 01-业务领域与架构 (合并原 01/02)
├── 02-后端开发 (AIOT-Cloud, 针对 java17 仓)
├── 03-前端开发 (Vben Admin, 针对 vue 仓)
├── 04-移动端开发 (UniApp, 针对 uniapp 仓)
├── 05-IoT生态接入 (应对 4 月重点：硬件对接、场景引擎)
├── 06-API规范与数据字典 (原 07/08 简化合并)
├── 07-DevOps运维保障 (原 09，部署与排障)
└── 08-开发协作规范 (原 10/11/12/13/14 整合，收敛模板味)
```

### 4. 目录撰写准则（写什么 / 不写什么）
- **写什么**：核心接口名、关键表名/状态枚举（带上代码文件路径）、主干流程梳理、复杂链路的源码入口导读。
- **不写什么**：大段易变的业务 CRUD 流水账、未经产品确认的未来脑洞、大篇幅的框架官方文档搬运（给链接即可）。

### 5. 必须图文化的内容
- **复杂状态机流转**：例如 Ops 工单的“创建-派发-接单-执行-核验”生命周期，必须有流程图。
- **核心联动链路**：例如 4 月重点“IoT设备联动Ops引擎”的跨端全链路。
- **系统架构与网络拓扑**：梳理各微服务、网关、端侧的交互边界。

### 6. 项目当前进度的表达机制
建立 `《00-项目能力与进度状态矩阵.md》`，按照模块进行网格化管理：
- 使用标签体系：`[✅生产可用] [🚀迭代中] [🚧开发中] [❌未开始]`。
- 示例：
  - `Ops-保洁业务`：后端 `[✅生产可用]` / 移动端 `[🚀迭代中]`
  - `Ops-安保工单`：后端 `[✅生产可用]` / 移动端 `[✅生产可用]`
  - `IoT-设备直连`：后端 `[🚧开发中]` (4月主线)

### 7. 文档与代码保持同步的机制
- **Single Source of Truth**：诸如工单状态字典、错误码等，以代码枚举为准，文档仅做原理解释和代码索引（指出枚举类所在包）。
- **流程级约束**：涉及核心业务流（如状态机）的修改，PR/Commit 必须包含对应的文档更新。
- **Agent 协作约定**：给协作 Agent 派发任务时，强制附加指令：“如修改核心逻辑，请一并修改 `XXX.md` 中对应的段落”。

### 8. 两天落地优先级计划
- **Day 1：重组框架与沉淀一阶段资产**
  - 调整物理目录，清理空壳文件。
  - 创建《00-AIOT项目能力状态矩阵》，盘点一阶段 Ops、保洁、安保进度。
  - 梳理现有后端的长篇文档，提取状态图和架构图。
- **Day 2：打通端侧与攻坚 IoT 准备**
  - 补充前端（Vben）和移动端（UniApp）的工单对齐文档。
  - 为 4 月 IoT 主线搭建《IoT与Ops联动链路跨端设计》骨架。

---

## B. 《第一批优先文档清单》

| 序号 | 文档名称 | 目标与核心内容 | 目标读者 | 建议深度 | 需配图 |
|---|---|---|---|---|---|
| 1 | `00-AIOT项目能力状态矩阵` | **明确当前项目阶段**：盘点 Ops/保洁/安保 完成度，规划 IoT 阶段。 | 全员 | 业务级 | ❌ 否(表格) |
| 2 | `01-总体架构与系统交互边界` | **理清宏观上下游**：明确 Cloud、UI、UniApp 之间的调用关系与鉴权方案。 | 新人,Agent,各端开发 | 架构级 | ✅ 是 |
| 3 | `02-后端/Ops工单生命周期与状态机` | **一阶段核心收口**：讲透工单怎么流转，包含派单、队列、抢单逻辑。 | 后端,测试,产品 | 核心代码级 | ✅ 是 |
| 4 | `02-后端/IoT与Ops联动链路设计` | **4月核心前置指导**：规则引擎如何触发报警并生成工单下发。 | 后端,IoT侧 | 主体实现级 | ✅ 是 |
| 5 | `03-前端/工单管理与工作台接入指北` | **解决前端文档缺失**：结合 Vben 结构说明如何开发工单后台页面。 | 前端开发 | 核心代码级 | ✅ 是(区域图) |
| 6 | `04-移动端/保洁与安保抢单链路` | **拉通移动端进度**：结合 UniApp 说明接单、上报、核验的 App 侧逻辑。 | 移动端开发 | 核心代码级 | ✅ 是(时序图) |
| 7 | `05-IoT接入协议与硬件映射规范` | **指导硬件联调**：规范物模型、指令上下行协议格式。 | 硬件,后端 | 源码导读级 | ✅ 是 |
| 8 | `08-开发协作与文档更新规约` | **解决同步痛点**：明确代码变动时文档的维护边界和提测流程。 | 研发全员 | 业务级 | ❌ 否 |

---

## C. 当前文档库现状诊断与重构建议

经过对 `/mnt/c/document/AIOT/开发者文档` 目录的扫描与分析：

### 1. “干货”文档（接近真实项目，需保留并优化）：
- **目录 `03-后端开发`** 下的内容具有极高的价值：
  - `04-Ops工单生命周期与状态机.md` (15KB+)
  - `05-Ops派单、队列与执行人状态.md` (13KB+)
  - `06-IoT设备、规则与场景引擎.md` (12KB+)
  - `07-IoT与Ops联动链路.md` (12KB+)
  - **建议**：这些文件详细描述了业务链路，是项目的精华。建议进一步提取其中的状态枚举和核心类名，并在适当位置补充 Mermaid 状态图和时序图。

### 2. “模板味”极重的空壳文件（建议重写/重构）：
- **目录 `04-前端` / `05-移动端` / `06-物联网` / `07-API` / `08-数据库`**：
  - 这些目录下的文件（如 `01-前端工程结构与协作边界.md` 等）大小均不足 1KB，通篇只有骨架和套话，完全脱离了真实的 `yudao-ui-admin-vben` 和 `aiot-uniapp` 仓。
  - **建议**：立刻停止堆砌目录。将前端/移动端文档与现有的代码目录结构深度绑定，写明“工单列表页代码在哪”、“发起API请求的封装类叫什么”，落实到“核心代码级”。
- **零碎的支撑目录 (`10-编码规范` / `12-教程示例` / `13-常见问题` / `14-术语表`)**：
  - 文件细碎且内容空泛。
  - **建议**：将它们统一收敛到合并后的 `08-开发协作规范` 中，减少用户查找的认知负担。