From 2e9372bfacbdce26bfd532e1cc93023231588d65 Mon Sep 17 00:00:00 2001 From: lzh Date: Mon, 6 Apr 2026 00:22:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E8=80=85=E6=96=87=E6=A1=A3=E9=AA=A8=E6=9E=B6=E5=B9=B6=E5=A2=9E?= =?UTF-8?q?=E5=BC=BA=E5=85=A5=E5=8F=A3=E5=AF=BC=E8=88=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AIOT-文档建设蓝图.md | 98 ++++++++ 开发者文档/00-导航与总览/00-阅读地图.md | 45 ++++ 开发者文档/00-导航与总览/01-项目总览.md | 11 + 开发者文档/00-导航与总览/02-项目当前状态.md | 34 +++ .../00-导航与总览/03-代码仓与协作边界.md | 50 ++++ 开发者文档/00-导航与总览/99-骨架重构说明.md | 18 ++ 开发者文档/01-业务与架构/01-总体架构设计.md | 188 ++++++++++++++ 开发者文档/01-业务与架构/01-架构设计说明.md | 8 + 开发者文档/01-快速开始/01-project-overview.md | 114 --------- 开发者文档/02-Ops领域/00-Ops领域总览.md | 9 + 开发者文档/03-IoT领域/00-IoT领域总览.md | 8 + .../04-前端开发/01-前端工程结构与协作边界.md | 48 ++++ .../05-移动端开发/01-移动端工程结构与页面分域.md | 41 +++ 开发者文档/06-平台支撑/00-支撑平台总览.md | 8 + .../07-API文档/01-接口分域与维护原则.md | 23 ++ .../08-数据库/01-数据域划分与表关系思路.md | 31 +++ .../09-DevOps运维/01-部署运行与排障视角.md | 20 ++ .../09-DevOps运维/02-环境部署指南.md} | 0 .../07-协作规范/01-不同项目的基本规范.md | 50 ++++ .../07-协作规范/01-需求开发与文档回补流程.md | 30 +++ .../07-协作规范/01-项目编码与文档规范.md | 23 ++ .../02-综合开发指南.md} | 0 .../08-附录/13-常见问题/01-开发者常见问题.md | 14 ++ 开发者文档/08-附录/14-术语表/01-核心术语.md | 22 ++ 开发者文档/README.md | 153 ++++-------- 开发者文档/图片/00-资源说明.md | 15 ++ 开发者文档/系统架构.md | 190 -------------- 开发者文档/贡献指南.md | 235 ------------------ 28 files changed, 836 insertions(+), 650 deletions(-) create mode 100644 AIOT-文档建设蓝图.md create mode 100644 开发者文档/00-导航与总览/00-阅读地图.md create mode 100644 开发者文档/00-导航与总览/01-项目总览.md create mode 100644 开发者文档/00-导航与总览/02-项目当前状态.md create mode 100644 开发者文档/00-导航与总览/03-代码仓与协作边界.md create mode 100644 开发者文档/00-导航与总览/99-骨架重构说明.md create mode 100644 开发者文档/01-业务与架构/01-总体架构设计.md create mode 100644 开发者文档/01-业务与架构/01-架构设计说明.md delete mode 100644 开发者文档/01-快速开始/01-project-overview.md create mode 100644 开发者文档/02-Ops领域/00-Ops领域总览.md create mode 100644 开发者文档/03-IoT领域/00-IoT领域总览.md create mode 100644 开发者文档/04-前端开发/01-前端工程结构与协作边界.md create mode 100644 开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md create mode 100644 开发者文档/06-平台支撑/00-支撑平台总览.md create mode 100644 开发者文档/06-平台支撑/07-API文档/01-接口分域与维护原则.md create mode 100644 开发者文档/06-平台支撑/08-数据库/01-数据域划分与表关系思路.md create mode 100644 开发者文档/06-平台支撑/09-DevOps运维/01-部署运行与排障视角.md rename 开发者文档/{部署指南.md => 06-平台支撑/09-DevOps运维/02-环境部署指南.md} (100%) create mode 100644 开发者文档/07-协作规范/01-不同项目的基本规范.md create mode 100644 开发者文档/07-协作规范/01-需求开发与文档回补流程.md create mode 100644 开发者文档/07-协作规范/01-项目编码与文档规范.md rename 开发者文档/{开发指南.md => 07-协作规范/02-综合开发指南.md} (100%) create mode 100644 开发者文档/08-附录/13-常见问题/01-开发者常见问题.md create mode 100644 开发者文档/08-附录/14-术语表/01-核心术语.md create mode 100644 开发者文档/图片/00-资源说明.md delete mode 100644 开发者文档/系统架构.md delete mode 100644 开发者文档/贡献指南.md diff --git a/AIOT-文档建设蓝图.md b/AIOT-文档建设蓝图.md new file mode 100644 index 0000000..690e7ec --- /dev/null +++ b/AIOT-文档建设蓝图.md @@ -0,0 +1,98 @@ +# 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-开发协作规范` 中，减少用户查找的认知负担。 \ No newline at end of file diff --git a/开发者文档/00-导航与总览/00-阅读地图.md b/开发者文档/00-导航与总览/00-阅读地图.md new file mode 100644 index 0000000..9f4d53b --- /dev/null +++ b/开发者文档/00-导航与总览/00-阅读地图.md @@ -0,0 +1,45 @@ +# 00-阅读地图 (Reading Roadmap) + +本文档是 AIoT 项目的 onboarding 核心指南。不要像无头苍蝇一样翻阅所有文档，请对号入座，根据你的角色和当前任务，按照推荐的先后顺序和时间分配进行阅读。 + +--- + +## 🐣 新人 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分钟)：快速扫一眼行业黑话（如果有），防止开会听天书。 + +--- + +## 💻 研发人员路线 (建议耗时：半天) +当你准备 clone 代码开始干活时，请花半天时间吃透相关规范： + +### 后端开发 (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 地址及通用的错误码处理逻辑。 + +--- + +## 🧪 测试与联调路线 (针对 QA & 测试同学) +当你准备介入测试时，你需要关注系统的“流转与可用性”： +1. **02-项目当前状态.md**：明确哪些模块是“已完成可测”的，哪些还在“建设中”，避免提无效 Bug。 +2. **03-代码仓与协作边界.md**：当你发现一个 Bug，需要根据此文档快速判断是前端展示问题、接口报错还是设备端无响应，从而将 Bug 指派给对应仓库的负责人。 +3. **业务方案的“测试用例基准”**：深入阅读 `02-Ops领域` 或 `03-IoT领域` 中的具体设计文档，重点看业务流转图（状态机）和前置条件。 + +--- + +## 🛠️ 运维与排障路线 (针对 DevOps & SRE) +线上部署或处理紧急故障时的速查路径： +1. **06-平台支撑/CI-CD规范.md**（如已补充）：查看发布流水线和环境变量注入规则。 +2. **06-平台支撑/中间件配置.md**：核对消息队列（RabbitMQ/Kafka）、Redis 集群、数据库路由等基础依赖。 +3. **07-协作规范/01-不同项目的基本规范.md**：重点查看后端**日志规范**章节，了解遇到问题时该去哪里抓取 TraceId，如何通过日志定位链路。 +4. **03-代码仓与协作边界.md**：通过异常堆栈中的包名，快速对应到对应的代码仓库。 diff --git a/开发者文档/00-导航与总览/01-项目总览.md b/开发者文档/00-导航与总览/01-项目总览.md new file mode 100644 index 0000000..fb93190 --- /dev/null +++ b/开发者文档/00-导航与总览/01-项目总览.md @@ -0,0 +1,11 @@ +# 01-项目总览 + +## 项目背景 +本项目是一个综合性的 AIoT 平台，旨在结合物联网设备与日常运营（Ops），提供高效、智能的管理方案。 + +## 核心业务板块 +- **Ops 领域**：工单、保洁、安保等日常运营管理（一阶段核心业务）。 +- **IoT 领域**：设备接入、数据采集与控制（后续重点）。 + +## 目标受众 +- 系统架构师、后端研发、前端研发、移动端研发及产品经理。 diff --git a/开发者文档/00-导航与总览/02-项目当前状态.md b/开发者文档/00-导航与总览/02-项目当前状态.md new file mode 100644 index 0000000..137706e --- /dev/null +++ b/开发者文档/00-导航与总览/02-项目当前状态.md @@ -0,0 +1,34 @@ +# 02-项目当前状态 + +本文档实时反映 AIoT 项目的真实进度基线，帮助团队在联调和规划时拉齐认知，避免“以为做完了实际还没开始”的坑。 + +## 1. 核心业务节奏：Ops 与 IoT 的关系 +当前项目处于**「Ops 深化迭代」与「IoT 攻坚破局」的双线交汇期**。 +- **Ops 领域（工单、保洁、安保）**：是第一阶段的核心，目前**基础建设已完成**。它已经具备了闭环能力，当前的节奏是持续的业务逻辑迭代、体验优化和边缘场景覆盖。 +- **IoT 领域（设备接入、物模型）**：是接下来的**核心战场**。前期的重心在 Ops 上，现在研发火力正逐渐向 IoT 倾斜，目标是打通硬件到平台的双向控制链路，让 Ops 能够真正与物理设备联动。 + +## 2. 业务与功能状态矩阵 + +以下是系统核心域的当前成熟度评估，分为三个维度： +- **业务能力状态**：该领域的业务逻辑是否闭环？ +- **功能状态**：代码实现了多少？ +- **可用状态**：能否在线上/测试环境跑通？ + +### [A] Ops 领域（工单/保洁/安保） +- **业务能力状态**：🟢 **基础闭环**。保洁与安保的派单、抢单、执行、验收标准主干流程已确立。 +- **功能状态**：🟡 **持续迭代**。RBAC 权限、工单流转、基础通知等核心功能已落地；复杂状态机流转、排班策略、数据看板仍在开发或迭代中。 +- **可用状态**：🟢 **核心可用**。前后端已能进行主流程联调，可支撑基础的业务演示与测试。 + +### [B] IoT 领域（设备/物模型/通信） +- **业务能力状态**：🟡 **设计与探索中**。物模型标准、设备接入协议（MQTT等）、数据流向规则正在制定。 +- **功能状态**：🔴 **起步阶段**。设备注册、网关对接、指令下发等底层链路处于 Demo 或初期研发阶段。 +- **可用状态**：🔴 **不可用/内部测试**。目前尚无法提供稳定的前后端联动环境，需依赖 Mock 数据。 + +### [C] 平台支撑与基础设施 +- **业务能力状态**：🟢 **标准已定**。开发规范、认证鉴权、字典与系统配置标准已确立。 +- **功能状态**：🟢 **基座稳固**。基于 `aiot-platform-cloud` 和 Vben 的底层脚手架、ORM、缓存、安全过滤已基本建设完毕。 +- **可用状态**：🟢 **高可用**。各端开发者拉取代码即可运行环境，基础 CRUD 无碍。 + +## 3. 研发关注重点提示 +- **如果你在做 Ops**：请关注代码的健壮性、状态机的严谨性，以及历史数据的兼容性。 +- **如果你在做 IoT**：请关注架构的扩展性、协议的通用性，容忍一定程度的推翻重构，快速试错。 diff --git a/开发者文档/00-导航与总览/03-代码仓与协作边界.md b/开发者文档/00-导航与总览/03-代码仓与协作边界.md new file mode 100644 index 0000000..c614f47 --- /dev/null +++ b/开发者文档/00-导航与总览/03-代码仓与协作边界.md @@ -0,0 +1,50 @@ +# 03-代码仓与协作边界 + +项目的成功在于清晰的边界。当跨端联调或出现 Bug 时，必须知道“这是谁的锅，该去哪提 PR”。本项目严格围绕三大主仓进行协作。 + +## 1. 三大主仓职责定义 + +### 📦 后端核心仓：`aiot-platform-cloud` +- **定位**：整个系统的大脑与数据中枢。 +- **职责**： + - 承载 Ops（工单/保洁/安保）的所有业务逻辑。 + - 承载 IoT 设备接入、物模型解析、设备控制指令下发。 + - 提供统一的权限认证（RBAC）、系统基础配置与 Open API。 +- **主要干系人**：后端研发团队。 + +### 📦 Web 管理端仓：`yudao-ui-admin-vben` +- **定位**：运营人员与管理员的控制台。 +- **职责**： + - 平台基础数据管理（用户、角色、字典、菜单）。 + - Ops 业务的管理后台（排班分配、工单审核、数据报表）。 + - IoT 设备的运维台（设备注册、实时状态监控、指令测试）。 +- **主要干系人**：前端研发团队。 + +### 📦 移动端仓：`aiot-uniapp` +- **定位**：一线业务人员（保安、保洁员、维修工）的作业工具。 +- **职责**： + - 承载高频移动端操作：扫码、抢单、工单执行反馈、图片上传。 + - 现场设备状态快速查看与简易控制。 +- **主要干系人**：移动端研发团队。 + +## 2. 跨仓协作关系 + +- **API 契约优先**：所有跨仓交互（前端/移动端对接后端）必须先定 API 文档（Swagger/YApi）。后端未提供契约前，前端/移动端可依赖契约进行 Mock 开发，禁止“边写接口边联调”。 +- **多端一致性**：当一个业务实体（如“工单状态”）发生变更时，**后端发起变更通告**，`yudao-ui-admin-vben` 和 `aiot-uniapp` 需同步评估改动范围，禁止一端暗改。 + +## 3. Bug 定位与认领指南 + +为了避免扯皮，遇到问题请遵循以下优先级在不同仓库定位： + +| 问题现象 | 定位优先级与排查路径 | 对应仓库 | +| :--- | :--- | :--- | +| **界面错位、样式崩塌、按钮点不动** | 纯展现问题。优先检查本地代码/组件状态。 | `yudao` 或 `uniapp` | +| **业务流程卡死、页面报 "Network Error"** | 前端先抓包（F12 / 代理），如果接口没发出去或者参数拼错，前端修。 | 首查 `yudao` / `uniapp` | +| **抓包显示后端返回 HTTP 500 或业务错误提示** | 明确的后端抛错。后端通过 TraceId 去看日志，定位是逻辑 Bug 还是数据脏了。 | `aiot-platform-cloud` | +| **App 上某个功能比 Web 上少字段** | 确认 API 契约是否有该字段。有则查移动端渲染；无则查后端接口适配。 | 跨仓联调确认 | +| **设备上线了但页面没刷新** | 确认链路：设备 -> 后端 (IoT) -> DB/MQ -> 后端接口 -> 前端。先看后端日志有没有收到报文。 | 首查 `cloud` 硬件链路 | + +## 4. 文档与仓库的对应关系 +- 有关 **表结构设计、API 定义、架构流转图** 的文档修改，通常伴随着 `aiot-platform-cloud` 的代码变更。 +- 有关 **组件库规范、页面路由、打包脚本** 的问题，直接对应 `yudao-ui-admin-vben` 或 `aiot-uniapp`。 +- **强行规矩**：无论改了哪个仓的业务主逻辑，都必须回到 `开发者文档` 仓库同步更新对应的 Markdown 文档！ diff --git a/开发者文档/00-导航与总览/99-骨架重构说明.md b/开发者文档/00-导航与总览/99-骨架重构说明.md new file mode 100644 index 0000000..82bb7b5 --- /dev/null +++ b/开发者文档/00-导航与总览/99-骨架重构说明.md @@ -0,0 +1,18 @@ +# 99-骨架重构说明 + +## 重构背景 +原文档结构主要按技术栈和组件划分，缺乏以业务和项目全局视角为主的引导。本次重构旨在建立“先搭骨架，再填正文”的内容体系，突出 Ops 和 IoT 业务主线。 + +## 新旧结构映射 +- `01-快速开始`、`03-后端开发` 等部分高价值内容已迁移至 `01-业务与架构`、`06-平台支撑` 和 `07-协作规范`。 +- 原 `04-前端开发` 和 `05-移动端开发` 的高价值内容保留至新的同名目录。 +- `09-DevOps运维` 归入 `06-平台支撑`。 +- `10-编码规范` 和 `11-开发流程指南` 整合至 `07-协作规范`。 + +## 保留与待重写内容 +- **保留内容**：后端高价值的设计文档、部署文档。 +- **待重写内容**：部分模板味较重、缺乏实际业务背景说明的示例文件。 + +## 后续补全建议 +1. 优先补充 Ops 领域核心业务（工单、保洁、安保）的设计文档。 +2. 完善 `aiot-platform-cloud` 的后端项目基本规范与架构说明。 diff --git a/开发者文档/01-业务与架构/01-总体架构设计.md b/开发者文档/01-业务与架构/01-总体架构设计.md new file mode 100644 index 0000000..01b9f6b --- /dev/null +++ b/开发者文档/01-业务与架构/01-总体架构设计.md @@ -0,0 +1,188 @@ +# AIOT 系统架构 + +本文档描述 AIOT 平台的整体系统架构和模块划分。 + +## 高层架构 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ 客户端 │ +├─────────────┬────────────────────┬───────────────────────────┤ +│ Web 管理后台 │ 移动端（多端） │ IoT 设备 │ +│ Vue 3 │ uni-app │ MQTT / HTTP │ +│ Vben Admin │ 小程序/H5/App │ 传感器/执行器 │ +└──────┬───────┴─────────┬──────────┴──────────┬───────────────┘ + │ HTTPS │ HTTPS │ MQTT / HTTP + │ │ │ +┌──────▼──────────────────▼─────────────────────▼──────────────┐ +│ viewsh-gateway │ +│ Spring Cloud Gateway（API 网关） │ +│ 路由转发 · 鉴权 · 限流 · 负载均衡 │ +└──────────────────────────┬───────────────────────────────────┘ + │ +┌──────────────────────────▼───────────────────────────────────┐ +│ 后端微服务集群 │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ viewsh-server（主服务） │ │ +│ │ 聚合启动各业务模块 │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────┐ │ +│ │ module-system │ │ module-infra │ │ module-iot │ │ +│ │ 用户·角色·权限 │ │ 文件·配置·代码 │ │ 设备·数据·协议 │ │ +│ │ 菜单·部门·岗位 │ │ 生成·日志·监控 │ │ 采集·告警·联动 │ │ +│ └───────────────┘ └───────────────┘ └──────────────────┘ │ +│ │ +│ ┌───────────────┐ ┌──────────────────────────────────────┐ │ +│ │ module-ops │ │ viewsh-framework │ │ +│ │ 工单·巡检 │ │ 公共层：安全、缓存、日志、工具类 │ │ +│ │ 告警·维保 │ │ MyBatis-Plus · MapStruct · Lombok │ │ +│ └───────────────┘ └──────────────────────────────────────┘ │ +└──────────────────────────┬───────────────────────────────────┘ + │ +┌──────────────────────────▼───────────────────────────────────┐ +│ 数据层 │ +│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────┐ │ +│ │ MySQL 8.0 │ │ Redis │ │ Nacos │ │ +│ │ 业务数据 │ │ 缓存·会话 │ │ 注册中心·配置 │ │ +│ └───────────────┘ └───────────────┘ └──────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ + │ +┌──────────────────────────▼───────────────────────────────────┐ +│ 基础设施 │ +│ Docker · Jenkins · Nginx │ +└──────────────────────────────────────────────────────────────┘ +``` + +## 后端模块职责 + +### viewsh-gateway + +API 网关，所有客户端请求的统一入口。 + +- 路由转发：根据路径前缀将请求分发到对应服务 +- 认证鉴权：统一的 Token 校验 +- 限流熔断：保护后端服务 +- 跨域处理：统一 CORS 配置 + +### viewsh-framework + +公共框架层，被所有业务模块依赖。 + +- 安全框架：JWT 认证、权限校验 +- 数据访问：MyBatis-Plus 封装、分页、多租户 +- 缓存封装：Redis 操作工具类 +- 日志切面：操作日志、访问日志 +- 工具类库：Lombok、MapStruct、通用响应体 + +### viewsh-server + +主服务启动模块，聚合加载各业务模块。 + +- 统一启动入口 +- 模块扫描与加载 +- 全局异常处理 +- Swagger/OpenAPI 文档聚合 + +### viewsh-module-system + +系统管理模块，提供基础的管理功能。 + +- 用户管理：增删改查、密码重置 +- 角色管理：角色分配、数据权限 +- 权限管理：菜单权限、按钮权限 +- 部门管理：组织架构树 +- 岗位管理 +- 字典管理 +- 通知公告 + +### viewsh-module-infra + +基础设施模块，提供平台底层能力。 + +- 文件管理：上传、下载、存储 +- 配置管理：系统参数配置 +- 代码生成：根据表结构自动生成 CRUD 代码 +- 数据源管理 +- API 日志：访问日志、错误日志 +- 定时任务 + +### viewsh-module-iot + +IoT 核心模块，AIOT 平台的核心业务。 + +- 设备管理：设备注册、分组、状态监控 +- 数据采集：设备上报数据接收和存储 +- 协议适配：MQTT、HTTP 等协议接入 +- 告警规则：阈值告警、离线告警 +- 设备联动：规则引擎、场景联动 +- 数据可视化：实时数据展示 + +### viewsh-module-ops + +运维管理模块，面向运维人员的管理功能。 + +- 工单管理：创建、分配、流转、关闭 +- 巡检管理：巡检计划、巡检记录 +- 告警处理：告警确认、告警统计 +- 维保管理：设备维保计划和记录 + +## 前端架构 + +``` +yudao-ui-admin-vben/ +├── apps/ # 应用层 +│ └── admin/ # 管理后台主应用 +├── packages/ # 共享包 +│ ├── components/ # 通用业务组件 +│ ├── utils/ # 工具函数 +│ └── types/ # TypeScript 类型定义 +├── internal/ # 内部构建配置 +│ ├── lint-configs/ # ESLint、Prettier 规则 +│ └── vite-config/ # Vite 构建配置 +└── scripts/ # 构建和发布脚本 +``` + +**核心技术选型**：Vue 3 + TypeScript + Vben Admin + Ant Design Vue + Pinia + pnpm monorepo + Turborepo + +## 移动端架构 + +``` +aiot-uniapp/ +├── src/ +│ ├── pages/ # 页面 +│ ├── components/ # 组件 +│ ├── api/ # 后端 API 调用 +│ ├── store/ # Pinia 状态管理 +│ ├── utils/ # 工具函数 +│ └── static/ # 静态资源 +├── env/ # 多环境配置 +└── vite-plugins/ # 自定义 Vite 插件 +``` + +**核心技术选型**：Vue 3 + TypeScript + uni-app + Pinia + UnoCSS + wot-design-uni + +**构建目标**：微信小程序、H5、Android App、iOS App + +## 通信方式 + +| 通信链路 | 协议 | 说明 | +|----------|------|------| +| 前端 ↔ 网关 | HTTPS | REST API 调用 | +| 移动端 ↔ 网关 | HTTPS | REST API 调用 | +| 网关 ↔ 后端服务 | HTTP | 内部服务转发 | +| 设备 ↔ 后端 | MQTT | 设备数据上报、指令下发 | +| 设备 ↔ 后端 | HTTP | 设备注册、固件升级 | +| 服务 ↔ Nacos | HTTP | 服务注册与配置拉取 | + +## 关键设计原则 + +1. **模块化** — 业务按领域拆分为独立模块，各模块职责清晰 +2. **网关统一入口** — 所有外部请求通过 Gateway 进入，统一鉴权和路由 +3. **配置集中管理** — Nacos 管理所有服务配置，支持动态刷新 +4. **前后端分离** — 前端独立部署，通过 API 与后端交互 +5. **多端复用** — 移动端通过 uni-app 一套代码编译多个平台 + +--- + +最后更新时间：2026-03-26 diff --git a/开发者文档/01-业务与架构/01-架构设计说明.md b/开发者文档/01-业务与架构/01-架构设计说明.md new file mode 100644 index 0000000..c7f6f3d --- /dev/null +++ b/开发者文档/01-业务与架构/01-架构设计说明.md @@ -0,0 +1,8 @@ +# 01-架构设计说明 + +## 目标与面向读者 +介绍系统整体的微服务架构、网络边界与技术选型，主要面向系统架构师与后端开发者。 + +## 核心内容占位 +- 待补充：系统物理架构图。 +- 待补充：`aiot-platform-cloud` 的微服务划分说明。 diff --git a/开发者文档/01-快速开始/01-project-overview.md b/开发者文档/01-快速开始/01-project-overview.md deleted file mode 100644 index c7f84cd..0000000 --- a/开发者文档/01-快速开始/01-project-overview.md +++ /dev/null @@ -1,114 +0,0 @@ -# 项目概述 - -欢迎来到 AIOT（人工智能物联网）项目！本文档介绍项目的背景、目标和范围。 - -## 🎯 项目目标 - -AIOT 项目的核心目标是： - -1. **实时设备管理** — 连接和管理各类物联网设备 -2. **数据驱动洞察** — 收集和分析设备数据 -3. **智能决策支持** — 使用 AI 模型提供智能建议 -4. **用户友好体验** — 提供直观的 Web 和移动界面 -5. **高可用和可扩展** — 支持大规模设备接入 - -## 📊 项目范围 - -### 核心功能 - -| 功能 | 说明 | 优先级 | -|-----|------|--------| -| 设备接入 | 支持多种协议的设备连接 | 高 | -| 数据采集 | 实时采集设备数据 | 高 | -| 数据分析 | 数据统计和可视化 | 高 | -| 告警系统 | 异常告警和通知 | 中 | -| 远程控制 | 远程操作设备 | 中 | -| AI 预测 | 基于 ML 的预测 | 中 | -| 用户管理 | 组织和权限管理 | 高 | -| 移动应用 | iOS/Android 原生应用 | 中 | - -### 支持的设备类型 - -- 温湿度传感器 -- 门窗磁传感器 -- 运动传感器 -- 智能灯 -- 智能插座 -- 摄像头 -- 能源监测设备 -- 自定义设备（通过 API） - -## 👥 目标用户 - -1. **企业管理员** — 管理组织内的设备和用户 -2. **运维工程师** — 监控系统健康和性能 -3. **数据分析师** — 分析数据和生成报告 -4. **普通用户** — 通过移动端控制设备 -5. **开发者** — 集成自定义设备和应用 - -## 🏗️ 技术栈概览 - -### 后端 -- **运行时** — Node.js / Python -- **框架** — Express / FastAPI -- **数据库** — PostgreSQL + Redis -- **消息队列** — RabbitMQ / Kafka -- **实时通信** — WebSocket / Socket.io - -### 前端 -- **框架** — React 18+ -- **状态管理** — Redux / Context API -- **UI 库** — Material-UI / Ant Design -- **构建工具** — Webpack / Vite - -### 移动端 -- **框架** — React Native / Flutter -- **原生功能** — 地理定位、推送通知等 -- **离线支持** — SQLite + Redux Persist - -### 基础设施 -- **容器化** — Docker -- **编排** — Kubernetes -- **CI/CD** — GitHub Actions / GitLab CI -- **监控** — Prometheus + Grafana -- **日志** — ELK Stack - -## 📈 项目里程碑 - -| 阶段 | 时间 | 目标 | -|-----|------|------| -| MVP | Q1 2024 | 核心功能实现 | -| Beta | Q2 2024 | 用户测试和反馈 | -| GA | Q3 2024 | 正式发布 | -| 迭代 | Q4 2024+ | 功能完善和优化 | - -## 📚 相关文档 - -- **[技术栈详解](02-tech-stack.md)** — 每个技术的选择原因 -- **[环境配置](03-environment-setup.md)** — 本地开发环境设置 -- **[快速开始](04-quick-start.md)** — 5 分钟快速上手 -- **[系统架构](../02-architecture/01-system-architecture.md)** — 整体架构设计 -- **[ARCHITECTURE.md](../ARCHITECTURE.md)** — 详细架构文档 - -## 🔗 相关链接 - -- GitHub 仓库：`[待填充]` -- 项目管理：`[待填充]` -- 问题追踪：`[待填充]` -- 文档网站：`[待填充]` -- API 文档：`[待填充]` - -## ❓ 常见问题 - -**Q: 这个项目适合我吗？** -A: 如果你对物联网、全栈开发或 AI 应用感兴趣，是的！无论你的背景如何，我们都欢迎。 - -**Q: 需要什么前置知识？** -A: 基本的编程知识即可。具体技术可以在参与过程中学习。 - -**Q: 怎么开始贡献？** -A: 请阅读 [CONTRIBUTING.md](../CONTRIBUTING.md) 和本指南的后续部分。 - ---- - -准备好开始了吗？前往 **[快速开始](04-quick-start.md)** 或选择你感兴趣的领域开始学习！ diff --git a/开发者文档/02-Ops领域/00-Ops领域总览.md b/开发者文档/02-Ops领域/00-Ops领域总览.md new file mode 100644 index 0000000..49d1e35 --- /dev/null +++ b/开发者文档/02-Ops领域/00-Ops领域总览.md @@ -0,0 +1,9 @@ +# Ops领域总览 + +## 目标与面向读者 +Ops 是当前第一阶段的核心业务，包括工单、保洁、安保等日常运营管理。本文档面向相关业务的产品与研发。 + +## 子业务模块 +- **工单管理**：待补充方案。 +- **保洁管理**：待补充方案。 +- **安保管理**：待补充方案。 diff --git a/开发者文档/03-IoT领域/00-IoT领域总览.md b/开发者文档/03-IoT领域/00-IoT领域总览.md new file mode 100644 index 0000000..4b38616 --- /dev/null +++ b/开发者文档/03-IoT领域/00-IoT领域总览.md @@ -0,0 +1,8 @@ +# IoT领域总览 + +## 目标与面向读者 +下一阶段的核心业务，聚焦于物联网设备的接入、控制与数据分析。 + +## 核心模块 +- **设备接入层**：待补充协议（MQTT/HTTP等）说明。 +- **物模型设计**：待补充设备属性、事件、服务定义。 diff --git a/开发者文档/04-前端开发/01-前端工程结构与协作边界.md b/开发者文档/04-前端开发/01-前端工程结构与协作边界.md new file mode 100644 index 0000000..c6b7a26 --- /dev/null +++ b/开发者文档/04-前端开发/01-前端工程结构与协作边界.md @@ -0,0 +1,48 @@ +# 🖥️ 前端工程结构与协作边界 + +前端仓库当前是一个 Vue 3 monorepo。它最重要的不是页面组件细节，而是应用层和共享层的边界。 + +## 1. 当前关键目录 + +- `apps/` +- `packages/` +- `internal/` +- `scripts/` +- `docs/` + +## 2. `apps` 的意义 + +当前可见应用包括： + +- `web-antd` +- `web-ele` +- `web-naive` +- `web-tdesign` + +它们代表可运行应用层，而不是共享层。 + +## 3. `packages` 的意义 + +当前可见共享层包括： + +- `constants` +- `effects` +- `icons` +- `locales` +- `preferences` +- `stores` +- `styles` +- `types` +- `utils` + +这说明前端已具备明确的共享能力抽象。 + +## 4. 与后端的关系 + +前端文档不应只按页面分组，更应围绕后端业务域组织： + +- system +- infra +- iot +- ops + diff --git a/开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md b/开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md new file mode 100644 index 0000000..c1ac5ea --- /dev/null +++ b/开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md @@ -0,0 +1,41 @@ +# 📱 移动端工程结构与页面分域 + +移动端当前不是简单页面合集，而是按业务域拆分的 uni-app 项目。 + +## 1. 当前关键目录 + +- `src/api` +- `src/pages` +- `src/pages-bpm` +- `src/pages-core` +- `src/pages-infra` +- `src/pages-ops` +- `src/pages-system` +- `src/store` +- `src/router` + +## 2. 页面分域说明 + +### `pages-ops` + +直接对应 Ops 现场执行域，当前已可见： + +- `inspection` +- `work-order` + +### `pages-system` + +对应用户、角色、通知、租户等系统能力。 + +### `pages-infra` + +对应配置、日志、任务、文件等基础设施能力。 + +### `pages-bpm` + +对应流程能力。 + +## 3. 为什么移动端文档要强调分域 + +因为它最终消费的是后端领域能力，而不是单纯页面组件。 + diff --git a/开发者文档/06-平台支撑/00-支撑平台总览.md b/开发者文档/06-平台支撑/00-支撑平台总览.md new file mode 100644 index 0000000..5c3a625 --- /dev/null +++ b/开发者文档/06-平台支撑/00-支撑平台总览.md @@ -0,0 +1,8 @@ +# 支撑平台总览 + +## 目标与面向读者 +介绍 DevOps、运维部署及中间件相关的内容。 + +## 后续规划 +- 补充 CI/CD 流程说明。 +- 补充 Redis、RabbitMQ/Kafka 等中间件的使用规范。 diff --git a/开发者文档/06-平台支撑/07-API文档/01-接口分域与维护原则.md b/开发者文档/06-平台支撑/07-API文档/01-接口分域与维护原则.md new file mode 100644 index 0000000..0c3316f --- /dev/null +++ b/开发者文档/06-平台支撑/07-API文档/01-接口分域与维护原则.md @@ -0,0 +1,23 @@ +# 🔗 接口分域与维护原则 + +这部分不替代 Swagger，而是定义接口文档应该怎样围绕业务域维护。 + +## 1. 推荐按域维护 + +- system +- infra +- iot +- ops + +## 2. 为什么不按页面维护 + +因为页面会变，但领域边界更稳定。 + +同一个接口可能同时服务： + +- 后台页面 +- 移动端页面 +- 规则联动 + +所以接口文档优先按域维护更稳。 + diff --git a/开发者文档/06-平台支撑/08-数据库/01-数据域划分与表关系思路.md b/开发者文档/06-平台支撑/08-数据库/01-数据域划分与表关系思路.md new file mode 100644 index 0000000..7b2055a --- /dev/null +++ b/开发者文档/06-平台支撑/08-数据库/01-数据域划分与表关系思路.md @@ -0,0 +1,31 @@ +# 🗄️ 数据域划分与表关系思路 + +当前数据库文档最重要的不是表清单，而是先划分数据域。 + +## 1. 系统主数据 + +- 用户 +- 角色 +- 菜单 +- 部门 +- 租户 + +## 2. IoT 主数据与过程数据 + +- 产品 +- 设备 +- 设备分组 +- 物模型 +- 告警配置 +- 告警记录 +- 设备消息 + +## 3. Ops 主数据与过程数据 + +- 工单主记录 +- 工单业务日志 +- 工单事件 +- 队列记录 +- 执行人状态 +- 统计结果 + diff --git a/开发者文档/06-平台支撑/09-DevOps运维/01-部署运行与排障视角.md b/开发者文档/06-平台支撑/09-DevOps运维/01-部署运行与排障视角.md new file mode 100644 index 0000000..6f8a717 --- /dev/null +++ b/开发者文档/06-平台支撑/09-DevOps运维/01-部署运行与排障视角.md @@ -0,0 +1,20 @@ +# 🚢 部署运行与排障视角 + +运维文档当前最应该做的是建立排障视角，而不是堆命令。 + +## 1. 当前可见运行线索 + +- `docker-compose.core.yml` +- `docker/` +- `Jenkinsfile` +- 网关与主服务独立配置 + +## 2. 排障第一刀 + +先判断问题属于哪一层： + +- 网关入口层 +- 主服务装配层 +- IoT 规则与设备层 +- Ops 状态与执行层 + diff --git a/开发者文档/部署指南.md b/开发者文档/06-平台支撑/09-DevOps运维/02-环境部署指南.md similarity index 100% rename from 开发者文档/部署指南.md rename to 开发者文档/06-平台支撑/09-DevOps运维/02-环境部署指南.md diff --git a/开发者文档/07-协作规范/01-不同项目的基本规范.md b/开发者文档/07-协作规范/01-不同项目的基本规范.md new file mode 100644 index 0000000..1d5093f --- /dev/null +++ b/开发者文档/07-协作规范/01-不同项目的基本规范.md @@ -0,0 +1,50 @@ +# 01-不同项目的基本规范 + +本规范旨在统一定义各端仓库的代码结构与开发底线，降低跨域协作的认知负担。不求死板教条，但求模块清晰、风格统一。 + +## 1. 后端 (`aiot-platform-cloud`) + +### 1.1 分层与目录组织原则 +后端遵循领域驱动（DDD）或经典分层架构，强制模块化： +- **`Controller` 层**：仅做参数校验与路由转发，严禁包含复杂业务逻辑。 +- **`Service` 层**：核心业务逻辑承载地。Ops 与 IoT 逻辑必须隔离在不同的包/模块下，严禁交叉污染。 +- **`Mapper / DAO` 层**：仅负责数据库交互，复杂 SQL 必须有注释说明意图。 +- *（具体包结构与命名约定，后续结合代码脚手架进一步补齐）* + +### 1.2 开发底线规范 +- **日志规约**：关键业务节点（如接单、设备状态变更、支付）必须打 `INFO` 日志，且日志必须携带关键主键（如 `orderId`, `deviceId`）。报错捕获必须打印完整堆栈及上下文参数。 +- **异常处理**：禁止向前端抛出原生 SQL 异常或 NullPointerException。所有异常应转化为统一的 `Result` 格式，附带明确的业务错误码。 + +## 2. 前端 (`yudao-ui-admin-vben`) + +### 2.1 目录与模块组织原则 +- **`views/`**：按业务模块划分（如 `views/ops/cleaning`, `views/iot/device`），严禁把所有页面平铺。 +- **`components/`**：只存放跨业务复用的 Dumb 组件；业务相关的特化组件放在对应的 `views/` 目录下。 +- **`api/`**：接口调用隔离层，按后端 Controller 分类封装，严禁在页面组件中直接写 `axios.get`。 +- *（基于 Vben 的具体状态管理 Pinia 划分，后续结合代码脚手架补齐）* + +### 2.2 开发底线规范 +- **类型安全**：TypeScript 必须严格定义 API 的 Req/Res 接口，尽量减少 `any` 的使用。 +- **权限控制**：页面入口和关键操作按钮必须接入统一的 RBAC 指令（如 `v-hasPermi`）。 + +## 3. 移动端 (`aiot-uniapp`) + +### 3.1 目录与模块组织原则 +- **分包策略**：考虑到小程序体积限制，必须从一开始就规划分包（如主包仅含登录和工作台首页，Ops 和 IoT 业务分别做独立分包）。 +- **`pages/` vs `components/`**：页面级文件放在 `pages`；页面内拆分的 UI 片段放在 `components`。 +- *（样式穿透与跨端兼容性处理规范，后续结合代码实践补齐）* + +### 3.2 开发底线规范 +- **状态同步**：移动端网络环境复杂，核心提交操作（如工单完工）必须做防抖处理与 Loading 状态遮罩。 +- **离线与缓存**：对字典数据和基础用户权限做好本地缓存，减少非必要的网络请求。 + +--- + +## 4. 变更必须同步的文档范围 (非常重要) + +代码不是孤岛。当你修改了核心逻辑，如果只提交代码不改文档，就是在给团队挖坑。触发以下变更时，**必须强制同步修改本仓库的对应文档**： + +1. **新增/修改/废弃接口**：必须同步更新 Swagger 注解或 API 文档平台，确保前端能拿到最新契约。 +2. **核心业务状态机变更**（如工单增加了一个“申诉中”状态）：必须同步更新 `02-Ops领域` 或相关业务目录下的 Markdown 状态图和说明。 +3. **新增外部依赖或中间件**（如引入了 ElasticSearch）：必须同步更新 `06-平台支撑/` 中的环境搭建指南和 `README.md` 的架构依赖说明。 +4. **表结构重大重构**：必须在团队群内通报，并更新相关的实体关系说明文档。 diff --git a/开发者文档/07-协作规范/01-需求开发与文档回补流程.md b/开发者文档/07-协作规范/01-需求开发与文档回补流程.md new file mode 100644 index 0000000..3ae4562 --- /dev/null +++ b/开发者文档/07-协作规范/01-需求开发与文档回补流程.md @@ -0,0 +1,30 @@ +# 🧪 需求开发与文档回补流程 + +这篇文档只定义一个实用流程：需求来了以后，开发和文档怎么同步推进。 + +## 1. 先定位业务域 + +- system +- infra +- iot +- ops + +## 2. 再定位是否影响状态流 + +如果需求涉及： + +- 工单 +- 派单 +- 设备规则 +- 联动触发 + +那就必须先确认状态流和事件流。 + +## 3. 开发后需要回补的文档 + +- 模块变更：后端模块地图 +- 状态流变更：Ops 生命周期文档 +- 调度变更：派单与队列文档 +- 规则变更：IoT 规则文档 +- 联动变更：IoT 与 Ops 联动文档 + diff --git a/开发者文档/07-协作规范/01-项目编码与文档规范.md b/开发者文档/07-协作规范/01-项目编码与文档规范.md new file mode 100644 index 0000000..6d46769 --- /dev/null +++ b/开发者文档/07-协作规范/01-项目编码与文档规范.md @@ -0,0 +1,23 @@ +# ✍️ 项目编码与文档规范 + +这里只记录当前最值得长期保持一致的约定。 + +## 1. 后端 + +- 模块边界优先于临时方便 +- 领域逻辑不直接写进 Controller +- 共性技术能力优先沉淀到 `framework` +- 条线差异优先放对应 `*-biz` + +## 2. 前端与移动端 + +- 页面层与共享层分离 +- 类型与 API 封装同步演进 +- 页面按业务域组织而不是随意堆叠 + +## 3. 文档 + +- 目录级 README 不作为正文 +- 先写边界，再写实现 +- 先写事实，再写建议 + diff --git a/开发者文档/开发指南.md b/开发者文档/07-协作规范/02-综合开发指南.md similarity index 100% rename from 开发者文档/开发指南.md rename to 开发者文档/07-协作规范/02-综合开发指南.md diff --git a/开发者文档/08-附录/13-常见问题/01-开发者常见问题.md b/开发者文档/08-附录/13-常见问题/01-开发者常见问题.md new file mode 100644 index 0000000..b15ca99 --- /dev/null +++ b/开发者文档/08-附录/13-常见问题/01-开发者常见问题.md @@ -0,0 +1,14 @@ +# ❓ 开发者常见问题 + +## 为什么后端文档最详细？ + +因为当前项目复杂度主要集中在后端，尤其是 `Ops + IoT`。 + +## 为什么去掉目录级 README？ + +因为目录级 README 更适合导航，不适合作为正文替代品。正文应直接落成正式章节。 + +## 为什么文档仓库和代码仓库分离？ + +为了让跨仓库知识能集中沉淀，也避免文档被代码噪音淹没。 + diff --git a/开发者文档/08-附录/14-术语表/01-核心术语.md b/开发者文档/08-附录/14-术语表/01-核心术语.md new file mode 100644 index 0000000..1ebaff4 --- /dev/null +++ b/开发者文档/08-附录/14-术语表/01-核心术语.md @@ -0,0 +1,22 @@ +# 📖 核心术语 + +## AIOT + +当前项目同时覆盖设备域、现场运营域、管理后台和移动执行端。 + +## Ops + +现场运营与任务执行域，核心关注工单、派单、执行人状态、队列和统计。 + +## IoT + +设备域，核心关注设备、物模型、设备消息、规则、告警、OTA 和场景动作。 + +## 工单 + +Ops 中的核心业务对象，表示一项待执行或执行中的现场任务。 + +## 状态机 + +对工单生命周期的统一约束机制。 + diff --git a/开发者文档/README.md b/开发者文档/README.md index 31050ce..61dca82 100644 --- a/开发者文档/README.md +++ b/开发者文档/README.md @@ -1,121 +1,52 @@ -# AIOT 项目文档 +# AIoT 开发者文档中心 (Developer Documentation) -欢迎来到 AIOT 项目的完整文档中心！本文档涵盖了整个项目的架构、开发、部署和运维指南。 +## 📌 文档中心定位 +这是 AIoT 项目的**唯一官方技术知识库**。这里的文档不写长篇大论的废话，只提供能够真正指导研发团队（包含 AI Agent）完成代码编写、系统联调、排障和协作的硬核指南。它是团队的技术契约与协作基线。 -## 📋 项目概述 +## 🚀 当前项目阶段 +**项目当前正处于「Ops 迭代与 IoT 冲刺」交汇期：** +- **一阶段 Ops 为核心**：保洁、安保等工单业务的底层基础建设已完成，目前处于持续迭代和业务深化阶段。 +- **下一阶段重心**：研发重心正全面转向 **IoT（物联网）领域** 的设备接入、物模型管理与控制链路打通。 -AIOT（人工智能物联网）是一个全栈项目，包含： -- **后端服务** — 核心业务逻辑和 API -- **Web 前端** — 管理后台和数据展示 -- **移动应用** — iOS/Android 原生应用 -- **设备接入** — 物联网设备管理和通信 +## 📦 三大主仓 +所有业务开发均围绕以下三个核心 Git 仓库展开： +1. **后端主仓**：`aiot-platform-cloud` +2. **Web前端主仓**：`yudao-ui-admin-vben` +3. **移动端主仓**：`aiot-uniapp` -## 🚀 快速开始 +## 🗺️ 按角色推荐阅读路径 +> 无论你是人类开发者还是 AI Agent，请根据你的角色选择对应的阅读入口。详细的阅读地图请查阅：[00-阅读地图](./00-导航与总览/00-阅读地图.md) -新开发者请从这里开始： +- **新人 (Newbie)**：先看本 README ➔ [02-项目当前状态](./00-导航与总览/02-项目当前状态.md) ➔ [03-代码仓与协作边界](./00-导航与总览/03-代码仓与协作边界.md) ➔ 本地环境搭建 +- **后端 (Backend)**：[03-代码仓边界](./00-导航与总览/03-代码仓与协作边界.md) ➔ [后端协作规范](./07-协作规范/01-不同项目的基本规范.md) ➔ `02-Ops领域` / `03-IoT领域` 的具体业务方案 +- **前端/移动端 (FE/Mobile)**：[前端/移动端规范](./07-协作规范/01-不同项目的基本规范.md) ➔ API 对接规范 ➔ UI/组件库规范 +- **测试 (QA)**：[02-项目当前状态](./00-导航与总览/02-项目当前状态.md) ➔ 核心业务流程图 (01/02目录) ➔ 部署与联调说明 +- **运维 (Ops)**：[03-代码仓边界](./00-导航与总览/03-代码仓与协作边界.md) ➔ [06-平台支撑](./06-平台支撑/) ➔ CI/CD与中间件配置 +- **产品 (PM)**：业务状态 ➔ [01-业务与架构](./01-业务与架构/) 对应的领域设计 +- **Agent (AI 助手)**：通读 `00-导航与总览` ➔ [不同项目的基本规范](./07-协作规范/01-不同项目的基本规范.md) ➔ 检索相关业务目录下的 `.md` -1. **[项目概述](01-getting-started/01-project-overview.md)** — 了解项目目标和范围 -2. **[技术栈](01-getting-started/02-tech-stack.md)** — 查看使用的技术 -3. **[环境配置](01-getting-started/03-environment-setup.md)** — 配置本地开发环境 -4. **[快速开始](01-getting-started/04-quick-start.md)** — 5分钟快速上手 +## ⭐ 当前优先阅读清单 +针对当前项目阶段，以下文档的优先级最高，请在开发前务必对齐： +1. [00-导航与总览/03-代码仓与协作边界.md](./00-导航与总览/03-代码仓与协作边界.md) - 弄清你的代码该提交到哪、遇到 bug 去哪个仓排查。 +2. [07-协作规范/01-不同项目的基本规范.md](./07-协作规范/01-不同项目的基本规范.md) - 开发红线与基本目录结构。 +3. `02-Ops领域` 或 `03-IoT领域` 中你目前负责的具体模块设计。 -## 📚 文档导航 - -### 🏗️ 架构和设计 -- **[系统架构](02-architecture/01-system-architecture.md)** — 整体系统设计 -- **[数据流设计](02-architecture/02-data-flow.md)** — 数据如何流动 -- **[API 设计](02-architecture/04-api-design.md)** — REST 和 WebSocket API 规范 -- **[数据库设计](02-architecture/05-database-schema.md)** — 数据模型 - -### 🔧 后端开发 -- **[后端环境配置](03-backend/01-setup.md)** -- **[项目结构](03-backend/02-project-structure.md)** -- **[API 文档](07-api-docs/openapi.yaml)** -- **[认证和授权](03-backend/05-authentication.md)** -- **[测试指南](03-backend/09-testing.md)** -- **[部署流程](03-backend/10-deployment.md)** - -### 🎨 前端开发 -- **[前端环境配置](04-frontend/01-setup.md)** -- **[项目结构](04-frontend/02-project-structure.md)** -- **[组件库使用](04-frontend/03-components-guide.md)** -- **[状态管理](04-frontend/04-state-management.md)** -- **[性能优化](04-frontend/08-performance.md)** -- **[UI 设计规范](04-frontend/12-ui-guidelines.md)** - -### 📱 移动端开发 -- **[移动端环境配置](05-mobile/01-setup.md)** -- **[应用架构](05-mobile/03-app-architecture.md)** -- **[屏幕导航](05-mobile/04-screen-guide.md)** -- **[API 集成](05-mobile/06-api-integration.md)** -- **[原生功能](05-mobile/07-native-features.md)** -- **[App 发布](05-mobile/12-build-deploy.md)** - -### 🔌 设备和物联网 -- **[设备类型](06-device/01-device-types.md)** -- **[连接配置](06-device/02-connection-setup.md)** -- **[固件更新](06-device/03-firmware-update.md)** -- **[数据传输协议](06-device/04-data-transmission.md)** - -### 🛠️ DevOps 和运维 -- **[CI/CD 流程](09-devops/01-ci-cd.md)** -- **[Docker 配置](09-devops/02-docker-setup.md)** -- **[监控告警](09-devops/04-monitoring.md)** -- **[灾难恢复](09-devops/07-disaster-recovery.md)** - -### 📖 规范和指南 -- **[代码风格指南](10-standards/01-code-style.md)** -- **[Git 工作流](10-standards/03-git-workflow.md)** -- **[编码规范](10-standards/02-naming-conventions.md)** -- **[常见任务](11-guides/01-common-tasks.md)** -- **[调试指南](11-guides/02-debugging.md)** - -### ❓ FAQ 和支持 -- **[常见问题](13-faq/general.md)** -- **[词汇表](14-glossary/terms.md)** - -## 📖 核心文档 - -- **[ARCHITECTURE.md](ARCHITECTURE.md)** — 系统架构详细说明 -- **[CONTRIBUTING.md](CONTRIBUTING.md)** — 贡献指南 -- **[DEVELOPMENT.md](DEVELOPMENT.md)** — 开发工作流 -- **[DEPLOYMENT.md](DEPLOYMENT.md)** — 部署和上线 - -## 🔍 快速查找 - -按角色查找你需要的文档： - -| 角色 | 推荐阅读 | -|-----|---------| -| 新团队成员 | 快速开始 → 项目概述 → 你的端环境配置 | -| 后端开发 | 后端设置 → API 文档 → 认证指南 | -| 前端开发 | 前端设置 → 组件库 → UI 规范 | -| 移动开发 | 移动设置 → 应用架构 → 发布流程 | -| 设备工程 | 设备类型 → 连接配置 → 数据传输 | -| DevOps | CI/CD → Docker → 监控 → 灾难恢复 | -| 项目经理 | 项目概述 → 系统架构 → 技术栈 | - -## 🔗 相关链接 - -- GitHub 仓库：`待填充` -- Issue 追踪：`待填充` -- CI/CD Dashboard：`待填充` -- API 文档（实时）：`待填充` - -## 📝 最后更新 - -- 最后更新时间：{{ now }} -- 文档版本：1.0.0 -- 项目版本：见 `VERSION` 文件 - -## ❓ 有问题？ - -- 查看 [FAQ](13-faq/general.md) -- 提交 Issue 或 Pull Request -- 联系项目维护者 +## 🛡️ 文档维护原则 (Truth Source) +在信息发生冲突时，请遵循以下可信度倒排原则（前面的优先级最高）： +1. **代码 (Code)**：代码是最终的真相。 +2. **项目负责人确认 (Tech Lead)**：重大歧义直接找 Lead 确认并立即更新文档。 +3. **数据库/配置 (DB/Config)**：线上实际运行的表结构和 Nacos 配置。 +4. **旧文档 (Old Docs)**：未及时更新的文档仅作参考。如果你发现文档已过期，**你就有责任顺手更新它**。 --- -**贡献者请阅读：** [CONTRIBUTING.md](CONTRIBUTING.md) - -**代码审查流程：** [代码审查指南](10-standards/05-code-review.md) +### 🗂️ 全局目录总览 +- `00-导航与总览/`：新手上路、项目状态、协作边界（入口） +- `01-业务与架构/`：全局架构设计 +- `02-Ops领域/`：工单、保洁、安保核心文档 +- `03-IoT领域/`：设备接入、物模型与数据流 +- `04-前端开发/`：Web 管理端开发专项 +- `05-移动端开发/`：小程序/App 开发专项 +- `06-平台支撑/`：中间件与 DevOps 基础设施 +- `07-协作规范/`：开发、测试、发布的流程与规约 +- `08-附录/`：术语表与历史存档 diff --git a/开发者文档/图片/00-资源说明.md b/开发者文档/图片/00-资源说明.md new file mode 100644 index 0000000..d823fa6 --- /dev/null +++ b/开发者文档/图片/00-资源说明.md @@ -0,0 +1,15 @@ +# 🖼️ 资源说明 + +这个目录用于存放： + +- 架构图 +- 流程图 +- 时序图 +- 页面截图 + +建议分别放入： + +- `images/architecture` +- `images/diagrams` +- `images/screenshots` + diff --git a/开发者文档/系统架构.md b/开发者文档/系统架构.md deleted file mode 100644 index 37ed3c8..0000000 --- a/开发者文档/系统架构.md +++ /dev/null @@ -1,190 +0,0 @@ -# AIOT 系统架构 - -本文档描述 AIOT 项目的整体系统架构、组件设计和数据流。 - -## 🏗️ 高层架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 用户端 │ -├──────────────┬──────────────────────┬──────────────────────┤ -│ Web 前端 │ 移动应用（App） │ 设备硬件/固件 │ -│ (React) │ (React Native) │ (IoT Devices) │ -└──────┬───────┴──────────┬───────────┴──────────┬────────────┘ - │ │ │ - │ HTTPS/WSS │ HTTP/MQTT │ - │ │ │ -┌──────▼──────────────────▼──────────────────────▼────────────┐ -│ API 网关 / 负载均衡 │ -└──────┬──────────────────────────────────────────────────────┘ - │ -┌──────▼──────────────────────────────────────────────────────┐ -│ 后端服务（Microservices） │ -├──────────────┬──────────────────┬──────────────────────────┤ -│ 身份验证 │ 用户管理 │ 设备管理 │ -│ (Auth) │ (User Service) │ (Device Service) │ -├──────────────┼──────────────────┼──────────────────────────┤ -│ 数据处理 │ 实时通信 │ 任务调度 │ -│ (Analytics) │ (WebSocket) │ (Job Queue) │ -├──────────────┼──────────────────┼──────────────────────────┤ -│ AI 模型 │ 文件存储 │ 日志系统 │ -│ (ML Models) │ (File Storage) │ (Logging) │ -└──────┬───────┴────────┬─────────┴──────────────┬───────────┘ - │ │ │ -┌──────▼────────────────▼────────────────────────▼───────────┐ -│ 数据层 │ -├──────────────┬──────────────────┬──────────────────────────┤ -│ PostgreSQL │ Redis Cache │ Time Series DB │ -│ (主数据) │ (会话/缓存) │ (时间序列数据) │ -├──────────────┼──────────────────┼──────────────────────────┤ -│ S3/OSS │ Message Queue │ Search Engine │ -│ (文件存储) │ (异步消息) │ (Elasticsearch) │ -└──────────────┴──────────────────┴──────────────────────────┘ - │ │ │ -┌──────▼────────────────▼────────────────────────▼───────────┐ -│ 基础设施 │ -├──────────────┬──────────────────┬──────────────────────────┤ -│ Kubernetes │ 监控/告警 │ CI/CD Pipeline │ -│ (容器编排) │ (Prometheus) │ (GitHub Actions) │ -└──────────────┴──────────────────┴──────────────────────────┘ -``` - -## 📦 组件概览 - -### 前端层 -- **Web 前端 (React)** - - 基于 React + Next.js - - 状态管理：Redux / Context API - - UI 框架：Material-UI 或 Ant Design - - 实时通信：WebSocket - -- **移动应用 (React Native)** - - 跨平台：iOS 和 Android - - 状态管理：Redux 或 Zustand - - 原生功能集成：地理定位、推送通知等 - - 离线支持：SQLite + Redux Persist - -### API 层 -- **HTTP REST API** - - 基于 Node.js/Express 或 Python/FastAPI - - RESTful 设计规范 - - 速率限制和认证 - -- **WebSocket（实时通信）** - - 实时数据推送 - - 设备状态更新 - - 用户通知 - -- **MQTT（设备通信）** - - 轻量级物联网协议 - - 发布-订阅模式 - - QoS 支持 - -### 业务逻辑层 -- **认证服务** - - JWT Token 管理 - - OAuth2 集成（可选） - - 权限控制 - -- **设备管理服务** - - 设备注册和发现 - - 固件更新管理 - - 设备状态监控 - -- **数据处理服务** - - 数据聚合和清理 - - 分析和统计 - - AI 模型推理 - -- **任务调度服务** - - 定时任务执行 - - 异步任务处理 - - 重试机制 - -### 数据层 -- **关系型数据库** - - PostgreSQL（用户、设备、配置等） - - 数据一致性保证 - - ACID 事务支持 - -- **缓存层** - - Redis（会话、缓存） - - 性能优化 - - 实时计数器 - -- **时间序列数据库** - - InfluxDB 或 TimescaleDB - - 设备数据存储 - - 高效查询 - -- **消息队列** - - RabbitMQ 或 Kafka - - 异步处理 - - 解耦服务 - -### 基础设施 -- **容器编排** - - Kubernetes - - Docker 镜像 - - 自动扩展 - -- **监控和告警** - - Prometheus + Grafana - - 日志管理（ELK Stack） - - 性能追踪（Jaeger） - -- **CI/CD** - - GitHub Actions / GitLab CI - - 自动化测试 - - 自动部署 - -## 🔄 数据流 - -详见：[数据流设计](02-architecture/02-data-flow.md) - -## 🔐 安全架构 - -详见：[安全架构](02-architecture/06-security-design.md) - -## 📈 扩展性设计 - -详见：[可扩展性规划](02-architecture/07-scalability-plan.md) - -## 🔌 通信协议 - -### HTTP/REST -- 客户端 ↔ 服务器通信 -- 标准 HTTP 方法（GET, POST, PUT, DELETE） -- JSON 请求/响应 - -### WebSocket -- 实时双向通信 -- 服务器主动推送 -- 心跳机制保活 - -### MQTT -- 设备 ↔ 服务器通信 -- 发布-订阅模式 -- 三个 QoS 等级 - -## 🎯 关键设计原则 - -1. **微服务架构** — 服务独立部署和扩展 -2. **异步处理** — 耗时操作异步化 -3. **缓存优先** — 减少数据库查询 -4. **实时驱动** — WebSocket/消息队列驱动 -5. **可观测性** — 完整的日志、监控和追踪 - -## 📋 版本历史 - -| 版本 | 日期 | 变更 | -|-----|------|------| -| 1.0 | 2024-01-01 | 初始架构设计 | - ---- - -详细的各部分架构说明请查看： -- [系统架构](02-architecture/01-system-architecture.md) -- [数据流设计](02-architecture/02-data-flow.md) -- [设备协议](02-architecture/03-device-protocol.md) -- [API 设计](02-architecture/04-api-design.md) diff --git a/开发者文档/贡献指南.md b/开发者文档/贡献指南.md deleted file mode 100644 index 3118195..0000000 --- a/开发者文档/贡献指南.md +++ /dev/null @@ -1,235 +0,0 @@ -# 贡献指南 - -感谢您对 AIOT 项目的兴趣！本指南将帮助您有效地为项目做出贡献。 - -## 🚀 开始贡献 - -### 第一步：设置开发环境 - -```bash -# 克隆仓库 -git clone https://github.com/your-org/aiot.git -cd aiot - -# 按照你的端的指南配置环境 -# 后端：docs/03-backend/01-setup.md -# 前端：docs/04-frontend/01-setup.md -# 移动：docs/05-mobile/01-setup.md -``` - -### 第二步：阅读编码规范 - -- [代码风格指南](10-standards/01-code-style.md) -- [命名规范](10-standards/02-naming-conventions.md) -- [Git 工作流](10-standards/03-git-workflow.md) -- [Commit 信息规范](10-standards/04-commit-messages.md) - -### 第三步：创建 Feature 分支 - -```bash -git checkout -b feature/your-feature-name -``` - -### 第四步：编写代码和测试 - -- 遵循编码规范 -- 添加单元测试 -- 确保测试通过 - -### 第五步：提交 Pull Request - -详见：[代码审查流程](10-standards/05-code-review.md) - -## 📋 贡献类型 - -### 🐛 Bug 修复 -1. 创建 Issue 描述 Bug -2. Fork 仓库 -3. 创建修复分支：`git checkout -b fix/issue-number` -4. 提交 PR，引用 Issue - -### ✨ 新功能 -1. 讨论功能设计（创建 Discussion 或 Issue） -2. Fork 仓库 -3. 创建功能分支：`git checkout -b feature/feature-name` -4. 提交 PR 描述功能和测试 - -### 📖 文档改进 -1. 编辑相关 Markdown 文件 -2. 提交 PR -3. 使用 Preview 功能检查格式 - -### 🎨 UI/UX 改进 -1. 在 Issue 中提出建议（包括设计稿） -2. 讨论和反馈 -3. 实现并提交 PR - -## 📝 Commit 信息规范 - -遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范： - -``` -(): - - - -