docs(nav): 完成 四篇核心文档（阅读地图、项目总览、项目当前状态、代码仓协作边界

开发者文档/00-导航与总览/00-阅读地图.md

@@ -1,45 +1,281 @@
-# 00-阅读地图 (Reading Roadmap)
+# 00-阅读地图
 
-本文档是 AIoT 项目的 onboarding 核心指南。不要像无头苍蝇一样翻阅所有文档，请对号入座，根据你的角色和当前任务，按照推荐的先后顺序和时间分配进行阅读。
+这不是目录清单，而是 `开发者文档` 的使用说明。
+
+如果你刚接手 AIOT 项目，或者刚准备处理一个具体任务，不要从头到尾乱翻。先确认你现在扮演什么角色、要解决什么问题，再按下面路线走。
+
+当前项目处于 **Ops 持续迭代、IoT 逐步转主线** 的阶段，因此阅读优先级也不是平均分配：
+- 如果你要尽快进入当前交付主线，先看 Ops 相关
+- 如果你要做下一阶段能力建设，重点转到 IoT 相关
+- 如果你要排障、联调、提 PR，先看边界和规范，不要先看业务描述
 
 ---
 
-## 🐣 新人 Onboarding 路线 (建议耗时：30分钟)
-无论你是什么岗位，入职第一天请先花半小时理清全局：
-1. **[必读] README.md** (5分钟)：了解文档中心定位和项目大方向。
-2. **[必读] 02-项目当前状态.md** (10分钟)：了解目前团队重点在打哪场仗（Ops 还是 IoT），系统哪些部分是可用的。
-3. **[必读] 03-代码仓与协作边界.md** (10分钟)：认清三大主仓 (`aiot-platform-cloud` / `yudao-ui-admin-vben` / `aiot-uniapp`) 的边界，知道在哪提 PR，在哪报 Bug。
-4. **[选读] 08-附录/术语表** (5分钟)：快速扫一眼行业黑话（如果有），防止开会听天书。
+## 一、所有人都先看的 4 篇
+
+无论你是谁，第一次进入这个文档仓，先看这 4 篇：
+
+1. `README.md`
+   - 解决“这套文档是干什么的、当前项目重心在哪”
+2. `01-项目总览.md`
+   - 解决“这个项目为什么会同时有 Ops 和 IoT 两条线”
+3. `02-项目当前状态.md`
+   - 解决“现在哪些东西已经成型，哪些还在建设”
+4. `03-代码仓与协作边界.md`
+   - 解决“我该去哪改、去哪查、出了问题谁先接”
+
+如果这 4 篇都没看，就直接进正文写代码，基本等于盲开。
 
 ---
 
-## 💻 研发人员路线 (建议耗时：半天)
-当你准备 clone 代码开始干活时，请花半天时间吃透相关规范：
+## 二、新人 30 分钟路线
 
-### 后端开发 (Backend)
-1. **07-协作规范/01-不同项目的基本规范.md**：重点看**后端规范**，理解分包逻辑、异常处理和日志要求。
-2. **06-平台支撑/**：查阅本地环境配置、Nacos/Redis/MySQL 连接说明。
-3. **01-业务与架构/**：阅读全局架构图，理解服务拆分。
-4. **具体业务模块**：如果你负责 Ops（保洁/安保），去 `02-Ops领域/` 找业务方案；如果负责硬件，去 `03-IoT领域/`。
+适合：
+- 第一次接触项目的人
+- 被临时拉来支援的人
+- 需要快速知道项目基本盘的人
 
-### 前端/移动端开发 (FE/Mobile)
-1. **07-协作规范/01-不同项目的基本规范.md**：重点看**前端/移动端规范**，理解目录划分和状态管理。
-2. **04-前端开发/ 或 05-移动端开发/**：查阅具体框架（Vben / Uniapp）的脚手架运行指南与组件规范。
-3. **接口契约**：查阅前后端联调的 YApi/Swagger 地址及通用的错误码处理逻辑。
+### 第 1 步：先搞清项目在打哪场仗
+看：
+- `README.md`
+- `02-项目当前状态.md`
+
+目标：
+- 知道现在不是“纯 IoT 项目”也不是“纯 Ops 项目”
+- 知道当前交付仍然以 Ops 为基本盘，但研发重心正在向 IoT 倾斜
+
+### 第 2 步：搞清三仓和文档的关系
+看：
+- `03-代码仓与协作边界.md`
+
+目标：
+- 知道 `aiot-platform-cloud`、`yudao-ui-admin-vben`、`aiot-uniapp` 各自负责什么
+- 知道问题先去哪查，不要一上来就群里甩锅
+
+### 第 3 步：按你的角色分流
+- 后端：转去 `01-业务与架构/` + `02-Ops领域/` / `03-IoT领域/`
+- 前端：转去 `04-前端开发/`
+- 移动端：转去 `05-移动端开发/`
+- 测试/运维：转去 `06-平台支撑/` + `07-协作规范/`
+
+30 分钟的目标不是看完全部，而是**建立正确地图**。
 
 ---
 
-## 🧪 测试与联调路线 (针对 QA & 测试同学)
-当你准备介入测试时，你需要关注系统的“流转与可用性”：
-1. **02-项目当前状态.md**：明确哪些模块是“已完成可测”的，哪些还在“建设中”，避免提无效 Bug。
-2. **03-代码仓与协作边界.md**：当你发现一个 Bug，需要根据此文档快速判断是前端展示问题、接口报错还是设备端无响应，从而将 Bug 指派给对应仓库的负责人。
-3. **业务方案的“测试用例基准”**：深入阅读 `02-Ops领域` 或 `03-IoT领域` 中的具体设计文档，重点看业务流转图（状态机）和前置条件。
+## 三、后端阅读路线
+
+适合：
+- 后端开发
+- 接口联调负责人
+- 需要判断模块边界的人
+
+### 如果你要做业务功能
+先看：
+1. `03-代码仓与协作边界.md`
+2. `07-协作规范/01-不同项目的基本规范.md`
+3. `01-业务与架构/01-总体架构设计.md`
+4. 再按业务域进入：
+   - Ops：`02-Ops领域/`
+   - IoT：`03-IoT领域/`
+
+### 如果你要排查线上/联调问题
+先看：
+1. `03-代码仓与协作边界.md`
+2. `06-平台支撑/00-支撑平台总览.md`
+3. `07-协作规范/01-需求开发与文档回补流程.md`
+
+重点不是先读长篇业务说明，而是先确定：
+- 问题在哪条链路上
+- 是接口问题、状态流问题，还是环境问题
 
 ---
 
-## 🛠️ 运维与排障路线 (针对 DevOps & SRE)
-线上部署或处理紧急故障时的速查路径：
-1. **06-平台支撑/CI-CD规范.md**（如已补充）：查看发布流水线和环境变量注入规则。
-2. **06-平台支撑/中间件配置.md**：核对消息队列（RabbitMQ/Kafka）、Redis 集群、数据库路由等基础依赖。
-3. **07-协作规范/01-不同项目的基本规范.md**：重点查看后端**日志规范**章节，了解遇到问题时该去哪里抓取 TraceId，如何通过日志定位链路。
-4. **03-代码仓与协作边界.md**：通过异常堆栈中的包名，快速对应到对应的代码仓库。
+## 四、前端阅读路线
+
+适合：
+- Web 管理端开发
+- 负责表单、列表、看板、后台业务页面的人
+
+### 第一轮必须看
+1. `03-代码仓与协作边界.md`
+2. `04-前端开发/01-前端工程结构与协作边界.md`
+3. `07-协作规范/01-不同项目的基本规范.md`
+
+### 第二轮按任务进入
+- 如果做 Ops 后台：先看 `02-Ops领域/`
+- 如果做 IoT 管理台：先看 `03-IoT领域/`
+- 如果做系统/平台配置页：补看 `06-平台支撑/`
+
+前端最容易踩的坑不是不会写页面，而是：
+- 没搞清字段和状态是谁定义的
+- 没搞清这个页面属于哪个业务域
+- 把共享组件和业务页面混着写
+
+所以前端不要只盯 `views`，要先看协作边界。
+
+---
+
+## 五、移动端阅读路线
+
+适合：
+- `aiot-uniapp` 相关开发
+- 现场作业流、扫码、抢单、执行反馈相关开发
+
+### 第一轮必须看
+1. `03-代码仓与协作边界.md`
+2. `05-移动端开发/01-移动端工程结构与页面分域.md`
+3. `07-协作规范/01-不同项目的基本规范.md`
+
+### 第二轮按业务域进入
+- 工单/巡检/现场执行：先看 `02-Ops领域/`
+- 设备状态、设备交互：补看 `03-IoT领域/`
+
+移动端的重点不是“页面多”，而是“流程闭环要稳”。
+尤其涉及：
+- 接单
+- 执行中
+- 完成回传
+- 图片/定位/状态更新
+
+这些都要回到 Ops 主线文档理解，不然容易把页面做成孤岛。
+
+---
+
+## 六、测试阅读路线
+
+适合：
+- QA
+- 联调测试
+- 需要判断问题归属的人
+
+### 先看
+1. `02-项目当前状态.md`
+2. `03-代码仓与协作边界.md`
+3. `07-协作规范/01-需求开发与文档回补流程.md`
+
+### 再看对应业务域
+- Ops 测试：`02-Ops领域/`
+- IoT 测试：`03-IoT领域/`
+
+测试最重要的不是“把页面点一遍”，而是先知道：
+- 这块功能目前是不是已经进入可测状态
+- 这条链路是完整闭环，还是还在建设中
+- 问题应该先找前端、移动端、后端还是平台支撑
+
+---
+
+## 七、运维 / 平台支撑阅读路线
+
+适合：
+- 运维
+- DevOps
+- 环境、部署、基础设施排障
+
+### 第一轮先看
+1. `03-代码仓与协作边界.md`
+2. `06-平台支撑/00-支撑平台总览.md`
+3. `01-业务与架构/01-总体架构设计.md`
+
+### 第二轮补看
+- `07-协作规范/01-不同项目的基本规范.md`
+- `07-协作规范/01-需求开发与文档回补流程.md`
+
+运维视角下，最先需要明确的是：
+- 哪些服务/模块是核心链路
+- 哪些问题属于部署/环境，哪些属于业务逻辑
+- 改了环境或中间件后，哪些文档必须回补
+
+---
+
+## 八、产品 / 项目负责人阅读路线
+
+适合：
+- 产品
+- 项目负责人
+- 需要把控当前阶段节奏的人
+
+### 先看
+1. `01-项目总览.md`
+2. `02-项目当前状态.md`
+3. `03-代码仓与协作边界.md`
+
+### 再看
+- `02-Ops领域/`：理解当前已成型业务
+- `03-IoT领域/`：理解接下来投入重点
+
+产品和负责人不一定要钻到代码细节，但必须知道：
+- 当前基本盘靠什么撑住
+- 现在哪些地方能承诺，哪些还不能承诺
+- 文档里哪些内容是阶段性结论，不是最终版
+
+---
+
+## 九、AI 助手 / Agent 阅读路线
+
+适合：
+- AI 助手
+- 需要根据文档协助生成、梳理、排查的人
+
+### 最小必读集合
+1. `README.md`
+2. 本文
+3. `02-项目当前状态.md`
+4. `03-代码仓与协作边界.md`
+5. `07-协作规范/01-不同项目的基本规范.md`
+6. `07-协作规范/01-需求开发与文档回补流程.md`
+
+### 工作原则
+- 先判断自己当前处理的是哪个业务域
+- 先判断问题落在哪个仓
+- 先区分“已确认事实”和“合理建议”
+- 不要把模板化通用文档当成项目事实
+
+Agent 最容易犯的错就是：
+- 写出看起来很顺但不够贴项目的文档
+- 没先看边界，就直接补正文
+- 没先看状态，就默认所有模块都成熟
+
+这个目录就是专门用来防这个错的。
+
+---
+
+## 十、当前阶段的推荐阅读优先级
+
+如果你只准备花半天建立有效理解，推荐顺序是：
+
+### 第一优先级
+- `README.md`
+- `00-导航与总览/01-项目总览.md`
+- `00-导航与总览/02-项目当前状态.md`
+- `00-导航与总览/03-代码仓与协作边界.md`
+
+### 第二优先级
+- `01-业务与架构/01-总体架构设计.md`
+- `07-协作规范/01-不同项目的基本规范.md`
+
+### 第三优先级
+- `02-Ops领域/`
+- `03-IoT领域/`
+- `04-前端开发/`
+- `05-移动端开发/`
+- `06-平台支撑/`
+
+理由很简单：
+先建立地图，再进具体领域；先搞清边界，再进实现细节。
+
+---
+
+## 十一、别怎么读
+
+### 不要这样
+- 从某篇业务文档开始一路乱点
+- 只看自己熟悉的技术栈，不看协作边界
+- 直接开始写代码，再回头补认知
+
+### 应该这样
+- 先看导航与总览
+- 再确认自己当前任务属于哪个域
+- 再进入对应目录
+- 过程中发现边界变化，回头更新文档
+
+这才是这份阅读地图存在的意义。

开发者文档/00-导航与总览/01-项目总览.md

@@ -1,11 +1,172 @@
 # 01-项目总览
 
-## 项目背景
-本项目是一个综合性的 AIoT 平台，旨在结合物联网设备与日常运营（Ops），提供高效、智能的管理方案。
+## 项目定位
 
-## 核心业务板块
-- **Ops 领域**：工单、保洁、安保等日常运营管理（一阶段核心业务）。
-- **IoT 领域**：设备接入、数据采集与控制（后续重点）。
+AIOT 是一个面向物联网设备与运营业务整合的综合平台，核心目标是打通「设备感知 → 平台处理 → 人工/自动响应」的完整链路。
+
+当前阶段，平台同时承载两条主线：
+- **Ops 运营线**：工单、保洁、安保等人工业务流程管理
+- **IoT 设备线**：设备接入、数据采集、远程控制、规则联动
+
+这两条线在架构上共享同一套后端、同一套前端/移动端框架，但在业务节奏上处于不同阶段：
+- Ops 是基本盘，已经跑通主流程，当前是持续迭代和深化
+- IoT 是下一阶段重点，正在从设计阶段进入建设阶段
+
+## 为什么把 Ops 和 IoT 放在同一套文档体系
+
+### 1. 技术底座共享
+- 同一套后端微服务架构（`aiot-platform-cloud`）
+- 同一套前端框架（`yudao-ui-admin-vben`）
+- 同一套移动端框架（`aiot-uniapp`）
+- 同一套 DevOps 基础设施
+
+### 2. 业务场景联动
+- Ops 工单最终要联动 IoT 设备（例如：设备告警自动生成工单）
+- IoT 设备状态要反馈到 Ops 作业流（例如：保洁员查看设备状态后再执行）
+- 两者共享用户体系、权限体系、通知体系
+
+### 3. 团队协同需要
+- 同一批后端研发同时支持 Ops 和 IoT
+- 同一批前端/移动端同时对接 Ops 和 IoT 接口
+- 同一套测试和运维流程覆盖两端
+
+如果强行拆成两个独立项目文档，会导致：
+- 边界重复描述
+- 协作规范不一致
+- 跨域联调时认知不统一
+
+因此，文档体系统一，但业务域分开描述。
+
+## 三大主仓与文档的关系
+
+| 仓库 | 定位 | 对应文档目录 |
+|------|------|-------------|
+| `aiot-platform-cloud` | 后端核心业务逻辑 | `02-Ops领域/`、`03-IoT领域/`、`06-平台支撑/` |
+| `yudao-ui-admin-vben` | Web 管理后台 | `04-前端开发/` |
+| `aiot-uniapp` | 移动端作业工具 | `05-移动端开发/` |
+
+### 关键原则
+- **文档不是代码的说明书，而是协作的契约**
+- 代码仓里的实现是最终真相，但文档里的边界和约定是协作前提
+- 当文档和代码冲突时，以代码为准，但必须同步更新文档
+
+## 当前阶段的工作重心
+
+### Ops 线（当前基本盘）
+**状态**：主流程已闭环，进入持续迭代
+
+**当前重点**：
+- 工单状态机的健壮性（异常分支、回滚、并发）
+- 保洁/安保业务场景的覆盖（排班、巡检、验收）
+- 数据看板和报表能力
+- 与 IoT 的初步联动（设备告警 → 工单）
+
+**文档需求**：
+- 业务流程必须文档化（状态机、时序图、边界条件）
+- 接口变更必须同步更新契约
+- 测试用例必须对齐文档描述
+
+### IoT 线（下一阶段重点）
+**状态**：从设计阶段进入建设阶段
+
+**当前重点**：
+- 设备接入协议选型与网关建设
+- 物模型标准定义（属性、事件、服务）
+- 设备注册、认证、生命周期管理
+- 数据采集、存储、可视化
+- 规则引擎（告警、联动）
+
+**文档需求**：
+- 协议和物模型是核心，必须文档先行
+- 设备端、网关、后端三端的边界必须清晰
+- 与 Ops 的联动场景需要提前设计
+
+### 平台支撑（贯穿两端）
+**状态**：基座已稳固，持续优化
+
+**当前重点**：
+- 本地开发环境标准化
+- CI/CD 流程优化
+- 中间件配置和监控
+- 安全、日志、审计
+
+## 文档覆盖范围与不覆盖范围
+
+### 覆盖
+- 业务架构设计（Ops、IoT）
+- 代码仓协作边界
+- 开发规范与流程
+- 本地环境搭建
+- 核心业务流程（状态机、时序图）
+- 接口契约（API 定义、错误码）
+
+### 不覆盖
+- 详细的产品需求文档（PRD）
+- 完整的测试用例库
+- 线上运维手册（监控、告警、应急）
+- 设备端固件开发文档
+- 硬件规格说明书
+
+**原因**：
+- 文档仓的定位是「研发协作基线」，不是「全量知识库」
+- 产品需求、测试用例、运维手册有各自的工具和流程
+- 设备端和硬件有独立的文档体系
 
 ## 目标受众
-- 系统架构师、后端研发、前端研发、移动端研发及产品经理。
+
+### 必须依赖本文档的人群
+- 后端研发（业务实现、接口设计、状态机维护）
+- 前端/移动端研发（页面实现、接口对接、联调排障）
+- 测试（测试策略、边界条件、Bug 归属）
+- 运维（环境搭建、部署流程、中间件配置）
+- AI 助手（代码生成、文档补全、问题排查）
+
+### 可参考但不依赖的人群
+- 产品（业务需求、用户场景）
+- 项目经理（进度、资源、风险）
+- 硬件工程师（设备端开发）
+
+## 当前文档体系的成熟度
+
+| 目录 | 成熟度 | 说明 |
+|------|--------|------|
+| `00-导航与总览/` | 🟡 可用 | 入口文档已成型，持续维护 |
+| `01-业务与架构/` | 🟡 可用 | 架构图已定型，细节待补 |
+| `02-Ops领域/` | 🟡 可用 | 主流程已文档化，边缘场景待补 |
+| `03-IoT领域/` | 🔴 建设中 | 框架已搭，正文待补 |
+| `04-前端开发/` | 🟡 可用 | 工程结构已文档化 |
+| `05-移动端开发/` | 🟡 可用 | 工程结构已文档化 |
+| `06-平台支撑/` | 🔴 建设中 | 框架已搭，正文待补 |
+| `07-协作规范/` | 🟡 可用 | 核心规范已成型 |
+| `08-附录/` | 🟡 可用 | 术语表等辅助内容 |
+
+**成熟度定义**：
+- 🟢 成熟：内容完整，可直接指导开发
+- 🟡 可用：核心内容已覆盖，边缘待补
+- 🔴 建设中：框架已搭，正文待补
+
+## 如何使用本文档
+
+### 如果你是新人
+1. 先看 `README.md`
+2. 再看本文
+3. 再看 `02-项目当前状态.md`
+4. 再看 `03-代码仓与协作边界.md`
+5. 然后按角色进入对应目录
+
+### 如果你要处理具体任务
+1. 先确认任务属于 Ops 还是 IoT
+2. 先看对应业务域的边界文档
+3. 再看具体实现文档
+4. 过程中发现文档缺失或过期，顺手补或提 Issue
+
+### 如果你是 AI 助手
+1. 必须先看 `00-导航与总览/` 全部
+2. 必须先看 `07-协作规范/`
+3. 然后按任务进入对应业务域
+4. 生成内容时必须区分「已确认事实」和「合理建议」
+5. 不要编造代码实现细节，只写文档里已确认的内容
+
+---
+
+**最后更新时间**：2026-04-06

开发者文档/00-导航与总览/02-项目当前状态.md

@@ -1,34 +1,209 @@
 # 02-项目当前状态
 
-本文档实时反映 AIoT 项目的真实进度基线，帮助团队在联调和规划时拉齐认知，避免“以为做完了实际还没开始”的坑。
+本文档是研发团队的认知基线，不是项目汇报材料。
 
-## 1. 核心业务节奏：Ops 与 IoT 的关系
-当前项目处于**「Ops 深化迭代」与「IoT 攻坚破局」的双线交汇期**。
-- **Ops 领域（工单、保洁、安保）**：是第一阶段的核心，目前**基础建设已完成**。它已经具备了闭环能力，当前的节奏是持续的业务逻辑迭代、体验优化和边缘场景覆盖。
-- **IoT 领域（设备接入、物模型）**：是接下来的**核心战场**。前期的重心在 Ops 上，现在研发火力正逐渐向 IoT 倾斜，目标是打通硬件到平台的双向控制链路，让 Ops 能够真正与物理设备联动。
+它的作用是：
+- 让所有人知道现在哪些东西已经可用，哪些还在建设
+- 让联调、测试、排障时有个共同参考
+- 让规划下一阶段工作时基于事实，而不是假设
 
-## 2. 业务与功能状态矩阵
+**更新时间**：2026-04-06
 
-以下是系统核心域的当前成熟度评估，分为三个维度：
-- **业务能力状态**：该领域的业务逻辑是否闭环？
-- **功能状态**：代码实现了多少？
-- **可用状态**：能否在线上/测试环境跑通？
+---
 
-### [A] Ops 领域（工单/保洁/安保）
-- **业务能力状态**：🟢 **基础闭环**。保洁与安保的派单、抢单、执行、验收标准主干流程已确立。
-- **功能状态**：🟡 **持续迭代**。RBAC 权限、工单流转、基础通知等核心功能已落地；复杂状态机流转、排班策略、数据看板仍在开发或迭代中。
-- **可用状态**：🟢 **核心可用**。前后端已能进行主流程联调，可支撑基础的业务演示与测试。
+## 一、整体节奏
 
-### [B] IoT 领域（设备/物模型/通信）
-- **业务能力状态**：🟡 **设计与探索中**。物模型标准、设备接入协议（MQTT等）、数据流向规则正在制定。
-- **功能状态**：🔴 **起步阶段**。设备注册、网关对接、指令下发等底层链路处于 Demo 或初期研发阶段。
-- **可用状态**：🔴 **不可用/内部测试**。目前尚无法提供稳定的前后端联动环境，需依赖 Mock 数据。
+当前项目处于 **Ops 持续迭代、IoT 逐步转主线** 的阶段。
 
-### [C] 平台支撑与基础设施
-- **业务能力状态**：🟢 **标准已定**。开发规范、认证鉴权、字典与系统配置标准已确立。
-- **功能状态**：🟢 **基座稳固**。基于 `aiot-platform-cloud` 和 Vben 的底层脚手架、ORM、缓存、安全过滤已基本建设完毕。
-- **可用状态**：🟢 **高可用**。各端开发者拉取代码即可运行环境，基础 CRUD 无碍。
+具体表现：
+- Ops 主流程已跑通，当前是业务深化和边缘场景覆盖
+- IoT 从设计阶段进入建设阶段，研发重心正在转移
+- 平台支撑基座已稳固，当前是优化和标准化
 
-## 3. 研发关注重点提示
-- **如果你在做 Ops**：请关注代码的健壮性、状态机的严谨性，以及历史数据的兼容性。
-- **如果你在做 IoT**：请关注架构的扩展性、协议的通用性，容忍一定程度的推翻重构，快速试错。
+这不是「Ops 做完了做 IoT」的串行节奏，而是「Ops 保基本盘、IoT 开新战场」的并行节奏。
+
+---
+
+## 二、分域状态
+
+### A. Ops 领域（工单、保洁、安保）
+
+#### 业务现状
+- 工单主流程（创建 → 分配 → 执行 → 完成 → 验收）已闭环
+- 保洁/安保的业务场景已覆盖基础派单、抢单、巡检
+- 复杂状态流转（转派、申诉、超时处理）已设计，部分实现
+- 排班策略、数据看板处于迭代中
+
+#### 功能现状
+- RBAC 权限体系已落地
+- 工单状态机已实现主干流程
+- 基础通知（短信、推送）已接入
+- 复杂状态机、排班算法、数据报表仍在开发
+
+#### 可用现状
+- 核心流程前后端已能联调
+- 测试环境可跑通主流程
+- 生产环境已支撑基础业务演示
+- 边缘场景（弱网、并发、异常分支）仍在打磨
+
+#### 当前短板
+- 状态机异常分支处理不够健壮
+- 历史数据兼容性方案待明确
+- 与 IoT 的联动（设备告警 → 工单）刚起步
+
+#### 当前重点
+- 状态机健壮性（异常处理、回滚、并发控制）
+- 保洁/安保业务深化（排班、巡检、验收标准）
+- 数据看板和报表能力
+- 与 IoT 的初步联动打通
+
+---
+
+### B. IoT 领域（设备、物模型、数据、联动）
+
+#### 业务现状
+- 物模型标准（属性、事件、服务）正在制定
+- 设备接入协议（MQTT/HTTP）已选型，网关建设中
+- 数据流向规则（采集 → 存储 → 可视化）正在设计
+- 规则引擎（告警、联动）框架搭建中
+
+#### 功能现状
+- 设备注册、认证接口已设计
+- 网关对接、指令下发处于 Demo 阶段
+- 数据采集、存储链路处于初期研发
+- 规则引擎、场景联动处于框架搭建
+
+#### 可用现状
+- 尚无法提供稳定的前后端联动环境
+- 设备端与后端的通信链路处于内部测试
+- 前端/移动端展示依赖 Mock 数据
+- 真实设备接入尚未开放
+
+#### 当前短板
+- 协议层细节（MQTT Topic 设计、QoS 策略）待确定
+- 物模型与业务模型的映射关系待明确
+- 设备生命周期管理（注册 → 激活 → 离线 → 注销）待完整实现
+- 与 Ops 的联动场景（告警 → 工单）待打通
+
+#### 当前重点
+- 设备接入网关建设与协议适配
+- 物模型标准定义与文档化
+- 设备生命周期管理实现
+- 数据采集、存储、可视化链路打通
+- 规则引擎（告警、联动）框架落地
+
+---
+
+### C. 平台支撑（基础设施、DevOps、中间件）
+
+#### 业务现状
+- 开发规范、认证鉴权、字典配置标准已确立
+- 本地开发环境搭建流程已标准化
+- CI/CD 流程已建立，持续优化中
+
+#### 功能现状
+- 基于 `aiot-platform-cloud` 的脚手架、ORM、缓存、安全过滤已完备
+- Nacos 注册中心、配置中心已接入
+- Redis 缓存、MySQL 主从已配置
+- Jenkins、Docker、Nginx 等基础设施已就绪
+
+#### 可用现状
+- 各端开发者拉取代码即可运行环境
+- 基础 CRUD 无碍
+- 测试环境、预发环境、生产环境已区分
+- 监控、日志、告警体系已搭建
+
+#### 当前短板
+- 中间件（RabbitMQ/Kafka）的使用规范待完善
+- 生产环境应急手册待补充
+- 性能基线和压测方案待建立
+
+#### 当前重点
+- CI/CD 流程优化（构建速度、回滚能力）
+- 中间件配置和使用规范文档化
+- 监控、日志、告警体系完善
+- 安全审计和合规检查
+
+---
+
+## 三、三仓成熟度
+
+| 仓库 | 当前状态 | 主要风险 |
+|------|----------|----------|
+| `aiot-platform-cloud` | 🟡 可用 | 复杂状态机、并发控制、IoT 新模块稳定性 |
+| `yudao-ui-admin-vben` | 🟡 可用 | 与后端接口契约同步、复杂表单性能 |
+| `aiot-uniapp` | 🟡 可用 | 分包体积控制、离线缓存策略、跨端兼容性 |
+
+**状态定义**：
+- 🟢 成熟：代码稳定，可直接用于生产
+- 🟡 可用：核心功能已覆盖，边缘场景待打磨
+- 🔴 建设中：框架已搭，核心功能待实现
+
+---
+
+## 四、当前阶段的关键判断
+
+### 判断 1：Ops 不是做完了，而是进入深水区
+- 主流程闭环只是开始
+- 复杂状态机、并发控制、历史数据兼容才是真正的难点
+- 与 IoT 的联动是下一步增长点
+
+### 判断 2：IoT 不是从零开始，而是需要加速建设
+- 架构设计已完成
+- 协议选型已确定
+- 现在需要快速实现、快速试错、快速迭代
+
+### 判断 3：平台支撑不是一劳永逸，而是持续优化
+- 基座已稳固，但性能、安全、可观测性需要持续提升
+- 中间件使用规范需要文档化
+- 应急和回滚能力需要演练
+
+### 判断 4：文档不是写完就完，而是需要持续回补
+- 代码实现会超前于文档
+- 文档更新是研发流程的一部分，不是额外负担
+- 发现文档过期，立即更新或提 Issue
+
+---
+
+## 五、给不同角色的当前重点提示
+
+### 后端研发
+- **Ops 方向**：关注状态机健壮性、并发控制、历史数据兼容
+- **IoT 方向**：关注协议细节、物模型映射、设备生命周期
+- **通用**：关注接口契约同步、日志规范、异常处理
+
+### 前端/移动端研发
+- **当前重点**：与后端接口契约对齐、复杂表单性能、分包体积控制
+- **下一步**：IoT 设备状态展示、实时数据可视化
+
+### 测试
+- **当前重点**：Ops 主流程回归、边界条件覆盖、并发场景测试
+- **下一步**：IoT 设备模拟、协议层测试、联动场景测试
+
+### 运维
+- **当前重点**：环境稳定性、监控告警有效性、CI/CD 可靠性
+- **下一步**：中间件性能调优、应急演练、安全合规
+
+### AI 助手
+- **当前重点**：基于文档生成代码时，必须区分「已确认事实」和「合理建议」
+- **下一步**：协助 IoT 文档补全、协议细节文档化
+
+---
+
+## 六、如何更新本文档
+
+当以下情况发生时，必须更新本文档：
+1. 某业务域从「建设中」进入「可用」或「成熟」
+2. 某功能从「不可用」进入「可用」
+3. 发现新的短板或风险
+4. 阶段重心发生转移
+
+更新流程：
+1. 修改本文档
+2. 同步更新 `README.md` 中的项目阶段描述
+3. 在 Git 提交中说明状态变更原因
+4. 在团队内同步
+
+---
+
+**本文档是研发团队的共同认知基线，请保持更新。**

开发者文档/00-导航与总览/03-代码仓与协作边界.md

@@ -1,50 +1,187 @@
 # 03-代码仓与协作边界
 
-项目的成功在于清晰的边界。当跨端联调或出现 Bug 时，必须知道“这是谁的锅，该去哪提 PR”。本项目严格围绕三大主仓进行协作。
+本文档解决一个核心问题：**出了问题该去哪查、该去哪改、该找谁。**
 
-## 1. 三大主仓职责定义
+项目围绕三大主仓展开，但真正的协作成本往往不在「写代码」，而在「找边界」。
+
+---
+
+## 一、三大主仓职责定义
 
 ### 📦 后端核心仓：`aiot-platform-cloud`
-- **定位**：整个系统的大脑与数据中枢。
-- **职责**：
-  - 承载 Ops（工单/保洁/安保）的所有业务逻辑。
-  - 承载 IoT 设备接入、物模型解析、设备控制指令下发。
-  - 提供统一的权限认证（RBAC）、系统基础配置与 Open API。
-- **主要干系人**：后端研发团队。
+
+**定位**：整个系统的大脑与数据中枢
+
+**职责范围**：
+- Ops 业务逻辑：工单、保洁、安保的所有后端逻辑
+- IoT 业务逻辑：设备接入、物模型解析、控制指令下发
+- 基础能力：权限认证（RBAC）、系统配置、Open API
+- 数据层：与 MySQL、Redis、Nacos 的交互
+
+**主要干系人**：后端研发团队
+
+**关键目录**（基于现有文档）：
+- `viewsh-gateway`：API 网关，统一入口
+- `viewsh-framework`：公共框架层
+- `viewsh-server`：主服务启动模块
+- `viewsh-module-system`：系统管理（用户、角色、权限、部门、字典）
+- `viewsh-module-infra`：基础设施（文件、配置、代码生成、定时任务）
+- `viewsh-module-iot`：IoT 核心（设备、数据、协议、告警、联动）
+- `viewsh-module-ops`：运维管理（工单、巡检、告警、维保）
+
+**协作原则**：
+- 所有业务逻辑必须在 Service 层，Controller 只负责路由和参数校验
+- Ops 与 IoT 逻辑必须隔离在不同包/模块，禁止交叉污染
+- 接口变更必须同步更新 Swagger/YApi 契约
+
+---
 
 ### 📦 Web 管理端仓：`yudao-ui-admin-vben`
-- **定位**：运营人员与管理员的控制台。
-- **职责**：
-  - 平台基础数据管理（用户、角色、字典、菜单）。
-  - Ops 业务的管理后台（排班分配、工单审核、数据报表）。
-  - IoT 设备的运维台（设备注册、实时状态监控、指令测试）。
-- **主要干系人**：前端研发团队。
+
+**定位**：运营人员与管理员的控制台
+
+**职责范围**：
+- 平台基础数据管理：用户、角色、字典、菜单
+- Ops 业务管理后台：排班分配、工单审核、数据报表
+- IoT 设备运维台：设备注册、实时状态监控、指令测试
+
+**主要干系人**：前端研发团队
+
+**关键目录**（基于现有文档）：
+- `apps/admin`：管理后台主应用
+- `packages/components`：通用业务组件
+- `packages/utils`：工具函数
+- `packages/types`：TypeScript 类型定义
+
+**协作原则**：
+- 按业务域组织页面（`views/ops/`、`views/iot/`），禁止平铺
+- 组件分层：共享组件放 `packages`，业务组件放对应 `views`
+- API 调用必须封装在 `api/` 目录，禁止页面直接写 `axios.get`
+
+---
 
 ### 📦 移动端仓：`aiot-uniapp`
-- **定位**：一线业务人员（保安、保洁员、维修工）的作业工具。
-- **职责**：
-  - 承载高频移动端操作：扫码、抢单、工单执行反馈、图片上传。
-  - 现场设备状态快速查看与简易控制。
-- **主要干系人**：移动端研发团队。
 
-## 2. 跨仓协作关系
+**定位**：一线业务人员（保安、保洁员、维修工）的作业工具
 
-- **API 契约优先**：所有跨仓交互（前端/移动端对接后端）必须先定 API 文档（Swagger/YApi）。后端未提供契约前，前端/移动端可依赖契约进行 Mock 开发，禁止“边写接口边联调”。
-- **多端一致性**：当一个业务实体（如“工单状态”）发生变更时，**后端发起变更通告**，`yudao-ui-admin-vben` 和 `aiot-uniapp` 需同步评估改动范围，禁止一端暗改。
+**职责范围**：
+- 高频移动端操作：扫码、抢单、工单执行反馈、图片上传
+- 现场设备状态快速查看与简易控制
 
-## 3. Bug 定位与认领指南
+**主要干系人**：移动端研发团队
 
-为了避免扯皮，遇到问题请遵循以下优先级在不同仓库定位：
+**关键目录**（基于现有文档）：
+- `src/pages-ops`：Ops 现场执行（巡检、工单）
+- `src/pages-system`：用户、角色、通知、租户
+- `src/pages-infra`：配置、日志、任务、文件
+- `src/pages-bpm`：流程能力
+- `src/api`：后端 API 调用
+- `src/store`：Pinia 状态管理
+
+**协作原则**：
+- 分包策略：主包仅含登录和工作台首页，Ops 和 IoT 业务分别独立分包
+- 核心提交操作（工单完工等）必须做防抖和 Loading 遮罩
+- 字典数据和基础权限做好本地缓存
+
+---
+
+## 二、跨仓协作关系
+
+### API 契约优先
+- 所有跨仓交互（前端/移动端对接后端）必须先定 API 文档（Swagger/YApi）
+- 后端未提供契约前，前端/移动端可依赖契约进行 Mock 开发
+- **禁止「边写接口边联调」**
+
+### 多端一致性
+- 当一个业务实体（如「工单状态」）发生变更时，**后端发起变更通告**
+- `yudao-ui-admin-vben` 和 `aiot-uniapp` 需同步评估改动范围
+- **禁止一端暗改**
+
+### 文档同步义务
+- 无论改了哪个仓的业务主逻辑，都必须回到 `开发者文档` 仓库同步更新对应的 Markdown 文档
+- 接口变更 → 更新 API 文档
+- 状态机变更 → 更新业务领域文档
+- 新增依赖 → 更新环境搭建文档
+
+---
+
+## 三、Bug 定位与认领指南
+
+遇到问题请遵循以下优先级在不同仓库定位：
 
 | 问题现象 | 定位优先级与排查路径 | 对应仓库 |
-| :--- | :--- | :--- |
+|----------|---------------------|----------|
 | **界面错位、样式崩塌、按钮点不动** | 纯展现问题。优先检查本地代码/组件状态。 | `yudao` 或 `uniapp` |
-| **业务流程卡死、页面报 "Network Error"** | 前端先抓包（F12 / 代理），如果接口没发出去或者参数拼错，前端修。 | 首查 `yudao` / `uniapp` |
-| **抓包显示后端返回 HTTP 500 或业务错误提示** | 明确的后端抛错。后端通过 TraceId 去看日志，定位是逻辑 Bug 还是数据脏了。 | `aiot-platform-cloud` |
+| **业务流程卡死、页面报 "Network Error"** | 前端先抓包（F12 / 代理）。如果接口没发出去或参数拼错，前端修。 | 首查 `yudao` / `uniapp` |
+| **抓包显示后端返回 HTTP 500 或业务错误提示** | 明确的后端抛错。后端通过 TraceId 看日志，定位是逻辑 Bug 还是数据问题。 | `aiot-platform-cloud` |
 | **App 上某个功能比 Web 上少字段** | 确认 API 契约是否有该字段。有则查移动端渲染；无则查后端接口适配。 | 跨仓联调确认 |
-| **设备上线了但页面没刷新** | 确认链路：设备 -> 后端 (IoT) -> DB/MQ -> 后端接口 -> 前端。先看后端日志有没有收到报文。 | 首查 `cloud` 硬件链路 |
+| **设备上线了但页面没刷新** | 确认链路：设备 → 后端 (IoT) → DB/MQ → 后端接口 → 前端。先看后端日志有没有收到报文。 | 首查 `cloud` 硬件链路 |
+| **权限控制不生效（能看到不该看的菜单/按钮）** | 先确认前端权限指令是否正确使用；再确认后端接口是否有权限校验。 | 两端都要查 |
+| **数据展示不一致（Web 和 App 显示同一数据不同）** | 先确认两端调用的是同一接口；再确认接口返回是否一致；最后确认两端渲染逻辑。 | 跨仓联调确认 |
 
-## 4. 文档与仓库的对应关系
-- 有关 **表结构设计、API 定义、架构流转图** 的文档修改，通常伴随着 `aiot-platform-cloud` 的代码变更。
-- 有关 **组件库规范、页面路由、打包脚本** 的问题，直接对应 `yudao-ui-admin-vben` 或 `aiot-uniapp`。
-- **强行规矩**：无论改了哪个仓的业务主逻辑，都必须回到 `开发者文档` 仓库同步更新对应的 Markdown 文档！
+**核心原则**：
+- 先定位链路，再定位仓库
+- 先确认现象，再确认根因
+- 不要凭感觉甩锅，要凭证据认领
+
+---
+
+## 四、文档与仓库的对应关系
+
+| 文档变更类型 | 通常伴随的代码变更 | 必须同步的文档位置 |
+|-------------|-------------------|-------------------|
+| 新增/修改/废弃接口 | `aiot-platform-cloud` 的 Controller/Service | Swagger/YApi + 对应业务域文档 |
+| 核心业务状态机变更 | `aiot-platform-cloud` 的 Service/Enum | `02-Ops领域/` 或 `03-IoT领域/` 的状态图和说明 |
+| 新增外部依赖或中间件 | `aiot-platform-cloud` 的 pom.xml / yml | `06-平台支撑/` + `README.md` 架构依赖 |
+| 表结构重大重构 | `aiot-platform-cloud` 的 Entity/Mapper | 团队群内通报 + 实体关系说明文档 |
+| 前端组件库变更 | `yudao-ui-admin-vben` 的 `packages/` | `04-前端开发/` 组件规范 |
+| 移动端分包策略调整 | `aiot-uniapp` 的 `pages.json` | `05-移动端开发/` 工程结构 |
+
+**强制规矩**：
+- 代码提交和文档更新必须在同一批次完成
+- 如果文档更新滞后，必须在提交信息中标注「文档待补」并创建跟进任务
+- 禁止「只改代码不改文档」
+
+---
+
+## 五、常见协作问题与解法
+
+### 问题 1：接口改了，前端不知道
+**解法**：
+- 后端在改接口前，必须先在 Swagger/YApi 标注「即将变更」
+- 变更后，必须在团队群 @ 前端/移动端负责人
+- 前端/移动端在联调前，必须先确认接口版本
+
+### 问题 2：状态枚举值不一致
+**解法**：
+- 所有状态枚举必须在后端统一定义，前端/移动端禁止硬编码
+- 后端提供 `/dict` 接口或常量文件，供前端/移动端同步
+- 状态变更必须在后端发起，禁止前端/移动端私自改状态
+
+### 问题 3：Bug 归属扯皮
+**解法**：
+- 按本文档第三章的表格先自查
+- 自查后仍不明确，抓包/日志贴出来，团队一起判
+- 判完后，责任人认领，其他人协助
+
+### 问题 4：文档过期没人管
+**解法**：
+- 发现文档过期，立即提 Issue 或顺手更新
+- 代码评审时，评审人必须检查「是否有文档同步」
+- 把文档更新纳入 Definition of Done
+
+---
+
+## 六、给 AI 助手的特别提示
+
+当你协助生成代码或排查问题时：
+
+1. **先确认边界**：这个问题涉及哪个仓？不要默认是后端问题
+2. **先查契约**：接口定义在哪？状态枚举在哪？不要硬编码
+3. **区分事实和建议**：文档里写的是「已实现」还是「待补充」？
+4. **不要编造代码细节**：如果没看过真实代码，不要写「具体实现如下」
+5. **变更必须提醒文档同步**：如果你建议修改了接口或状态机，必须提醒同步更新文档
+
+---
+
+**本文档是协作的契约，不是参考材料。请严格遵守。**