aiot-document/AIOT-文档建设蓝图.md

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

A. 《AIOT 文档建设蓝图》

1. 文档建设目标

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

2. 文档分层设计

结合真实的 AIOT 场景，建议采用四维分层模型：

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

3. 建议目录结构（整合优化版）

针对现有结构过于零散且存在大量“空壳”的问题，建议调整如下：

/开发者文档
├── 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-开发协作规范 中，减少用户查找的认知负担。