From b8fb5ad761fd315ca6ba57e1c86f48f94de80c47 Mon Sep 17 00:00:00 2001 From: lzh Date: Mon, 6 Apr 2026 22:33:57 +0800 Subject: [PATCH] =?UTF-8?q?docs(nav):=20=E5=AE=8C=E6=88=90=20=20=E5=9B=9B?= =?UTF-8?q?=E7=AF=87=E6=A0=B8=E5=BF=83=E6=96=87=E6=A1=A3=EF=BC=88=E9=98=85?= =?UTF-8?q?=E8=AF=BB=E5=9C=B0=E5=9B=BE=E3=80=81=E9=A1=B9=E7=9B=AE=E6=80=BB?= =?UTF-8?q?=E8=A7=88=E3=80=81=E9=A1=B9=E7=9B=AE=E5=BD=93=E5=89=8D=E7=8A=B6?= =?UTF-8?q?=E6=80=81=E3=80=81=E4=BB=A3=E7=A0=81=E4=BB=93=E5=8D=8F=E4=BD=9C?= =?UTF-8?q?=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发者文档/00-导航与总览/00-阅读地图.md | 296 ++++++++++++++++-- 开发者文档/00-导航与总览/01-项目总览.md | 173 +++++++++- 开发者文档/00-导航与总览/02-项目当前状态.md | 225 +++++++++++-- .../00-导航与总览/03-代码仓与协作边界.md | 201 ++++++++++-- 4 files changed, 802 insertions(+), 93 deletions(-) diff --git a/开发者文档/00-导航与总览/00-阅读地图.md b/开发者文档/00-导航与总览/00-阅读地图.md index 9f4d53b..03fab7c 100644 --- a/开发者文档/00-导航与总览/00-阅读地图.md +++ b/开发者文档/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-平台支撑/` + +理由很简单： +先建立地图，再进具体领域；先搞清边界，再进实现细节。 + +--- + +## 十一、别怎么读 + +### 不要这样 +- 从某篇业务文档开始一路乱点 +- 只看自己熟悉的技术栈，不看协作边界 +- 直接开始写代码，再回头补认知 + +### 应该这样 +- 先看导航与总览 +- 再确认自己当前任务属于哪个域 +- 再进入对应目录 +- 过程中发现边界变化，回头更新文档 + +这才是这份阅读地图存在的意义。 \ No newline at end of file diff --git a/开发者文档/00-导航与总览/01-项目总览.md b/开发者文档/00-导航与总览/01-项目总览.md index fb93190..09fb03c 100644 --- a/开发者文档/00-导航与总览/01-项目总览.md +++ b/开发者文档/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 \ No newline at end of file diff --git a/开发者文档/00-导航与总览/02-项目当前状态.md b/开发者文档/00-导航与总览/02-项目当前状态.md index 137706e..57d0b8e 100644 --- a/开发者文档/00-导航与总览/02-项目当前状态.md +++ b/开发者文档/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. 在团队内同步 + +--- + +**本文档是研发团队的共同认知基线，请保持更新。** \ No newline at end of file diff --git a/开发者文档/00-导航与总览/03-代码仓与协作边界.md b/开发者文档/00-导航与总览/03-代码仓与协作边界.md index c614f47..4f8a1e7 100644 --- a/开发者文档/00-导航与总览/03-代码仓与协作边界.md +++ b/开发者文档/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. **变更必须提醒文档同步**：如果你建议修改了接口或状态机，必须提醒同步更新文档 + +--- + +**本文档是协作的契约，不是参考材料。请严格遵守。** \ No newline at end of file