XW-AIOT/aiot-document
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重构开发者文档骨架并增强入口导航

Browse Source
This commit is contained in:
lzh
2026-04-06 00:22:42 +08:00
parent 5ea1a0c70c
commit 2e9372bfac
28 changed files with 836 additions and 650 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
AIOT-文档建设蓝图.md Normal file
View File

@@ -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-开发协作规范` 中，减少用户查找的认知负担。

45
开发者文档/00-导航与总览/00-阅读地图.md Normal file
View File

@@ -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**：通过异常堆栈中的包名，快速对应到对应的代码仓库。

11
开发者文档/00-导航与总览/01-项目总览.md Normal file
View File

@@ -0,0 +1,11 @@
# 01-项目总览
## 项目背景
本项目是一个综合性的 AIoT 平台，旨在结合物联网设备与日常运营（Ops），提供高效、智能的管理方案。
## 核心业务板块
- **Ops 领域**：工单、保洁、安保等日常运营管理（一阶段核心业务）。
- **IoT 领域**：设备接入、数据采集与控制（后续重点）。
## 目标受众
- 系统架构师、后端研发、前端研发、移动端研发及产品经理。

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

@@ -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**：请关注架构的扩展性、协议的通用性，容忍一定程度的推翻重构，快速试错。

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

@@ -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 文档！

18
开发者文档/00-导航与总览/99-骨架重构说明.md Normal file
View File

@@ -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` 的后端项目基本规范与架构说明。

188
开发者文档/01-业务与架构/01-总体架构设计.md Normal file
View File

@@ -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

8
开发者文档/01-业务与架构/01-架构设计说明.md Normal file
View File

@@ -0,0 +1,8 @@
# 01-架构设计说明
## 目标与面向读者
介绍系统整体的微服务架构、网络边界与技术选型，主要面向系统架构师与后端开发者。
## 核心内容占位
- 待补充：系统物理架构图。
- 待补充：`aiot-platform-cloud` 的微服务划分说明。

114
开发者文档/01-快速开始/01-project-overview.md
View File

@@ -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)** 或选择你感兴趣的领域开始学习！

9
开发者文档/02-Ops领域/00-Ops领域总览.md Normal file
View File

@@ -0,0 +1,9 @@
# Ops领域总览
## 目标与面向读者
Ops 是当前第一阶段的核心业务，包括工单、保洁、安保等日常运营管理。本文档面向相关业务的产品与研发。
## 子业务模块
- **工单管理**：待补充方案。
- **保洁管理**：待补充方案。
- **安保管理**：待补充方案。

8
开发者文档/03-IoT领域/00-IoT领域总览.md Normal file
View File

@@ -0,0 +1,8 @@
# IoT领域总览
## 目标与面向读者
下一阶段的核心业务，聚焦于物联网设备的接入、控制与数据分析。
## 核心模块
- **设备接入层**：待补充协议（MQTT/HTTP等）说明。
- **物模型设计**：待补充设备属性、事件、服务定义。

48
开发者文档/04-前端开发/01-前端工程结构与协作边界.md Normal file
View File

@@ -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

41
开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md Normal file
View File

@@ -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. 为什么移动端文档要强调分域
因为它最终消费的是后端领域能力，而不是单纯页面组件。

8
开发者文档/06-平台支撑/00-支撑平台总览.md Normal file
View File

@@ -0,0 +1,8 @@
# 支撑平台总览
## 目标与面向读者
介绍 DevOps、运维部署及中间件相关的内容。
## 后续规划
- 补充 CI/CD 流程说明。
- 补充 Redis、RabbitMQ/Kafka 等中间件的使用规范。

23
开发者文档/06-平台支撑/07-API文档/01-接口分域与维护原则.md Normal file
View File

@@ -0,0 +1,23 @@
# 🔗 接口分域与维护原则
这部分不替代 Swagger，而是定义接口文档应该怎样围绕业务域维护。
## 1. 推荐按域维护
- system
- infra
- iot
- ops
## 2. 为什么不按页面维护
因为页面会变，但领域边界更稳定。
同一个接口可能同时服务：
- 后台页面
- 移动端页面
- 规则联动
所以接口文档优先按域维护更稳。

31
开发者文档/06-平台支撑/08-数据库/01-数据域划分与表关系思路.md Normal file
View File

@@ -0,0 +1,31 @@
# 🗄️ 数据域划分与表关系思路
当前数据库文档最重要的不是表清单，而是先划分数据域。
## 1. 系统主数据
- 用户
- 角色
- 菜单
- 部门
- 租户
## 2. IoT 主数据与过程数据
- 产品
- 设备
- 设备分组
- 物模型
- 告警配置
- 告警记录
- 设备消息
## 3. Ops 主数据与过程数据
- 工单主记录
- 工单业务日志
- 工单事件
- 队列记录
- 执行人状态
- 统计结果

20
开发者文档/06-平台支撑/09-DevOps运维/01-部署运行与排障视角.md Normal file
View File

@@ -0,0 +1,20 @@
# 🚢 部署运行与排障视角
运维文档当前最应该做的是建立排障视角，而不是堆命令。
## 1. 当前可见运行线索
- `docker-compose.core.yml`
- `docker/`
- `Jenkinsfile`
- 网关与主服务独立配置
## 2. 排障第一刀
先判断问题属于哪一层：
- 网关入口层
- 主服务装配层
- IoT 规则与设备层
- Ops 状态与执行层

0
开发者文档/部署指南.md → 开发者文档/06-平台支撑/09-DevOps运维/02-环境部署指南.md
View File

50
开发者文档/07-协作规范/01-不同项目的基本规范.md Normal file
View File

@@ -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<T>` 格式，附带明确的业务错误码。
## 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. **表结构重大重构**：必须在团队群内通报，并更新相关的实体关系说明文档。

30
开发者文档/07-协作规范/01-需求开发与文档回补流程.md Normal file
View File

@@ -0,0 +1,30 @@
# 🧪 需求开发与文档回补流程
这篇文档只定义一个实用流程：需求来了以后，开发和文档怎么同步推进。
## 1. 先定位业务域
- system
- infra
- iot
- ops
## 2. 再定位是否影响状态流
如果需求涉及：
- 工单
- 派单
- 设备规则
- 联动触发
那就必须先确认状态流和事件流。
## 3. 开发后需要回补的文档
- 模块变更：后端模块地图
- 状态流变更：Ops 生命周期文档
- 调度变更：派单与队列文档
- 规则变更：IoT 规则文档
- 联动变更：IoT 与 Ops 联动文档

23
开发者文档/07-协作规范/01-项目编码与文档规范.md Normal file
View File

@@ -0,0 +1,23 @@
# ✍️ 项目编码与文档规范
这里只记录当前最值得长期保持一致的约定。
## 1. 后端
- 模块边界优先于临时方便
- 领域逻辑不直接写进 Controller
- 共性技术能力优先沉淀到 `framework`
- 条线差异优先放对应 `*-biz`
## 2. 前端与移动端
- 页面层与共享层分离
- 类型与 API 封装同步演进
- 页面按业务域组织而不是随意堆叠
## 3. 文档
- 目录级 README 不作为正文
- 先写边界，再写实现
- 先写事实，再写建议

0
开发者文档/开发指南.md → 开发者文档/07-协作规范/02-综合开发指南.md
View File

14
开发者文档/08-附录/13-常见问题/01-开发者常见问题.md Normal file
View File

@@ -0,0 +1,14 @@
# ❓ 开发者常见问题
## 为什么后端文档最详细？
因为当前项目复杂度主要集中在后端，尤其是 `Ops + IoT`。
## 为什么去掉目录级 README？
因为目录级 README 更适合导航，不适合作为正文替代品。正文应直接落成正式章节。
## 为什么文档仓库和代码仓库分离？
为了让跨仓库知识能集中沉淀，也避免文档被代码噪音淹没。

22
开发者文档/08-附录/14-术语表/01-核心术语.md Normal file
View File

@@ -0,0 +1,22 @@
# 📖 核心术语
## AIOT
当前项目同时覆盖设备域、现场运营域、管理后台和移动执行端。
## Ops
现场运营与任务执行域，核心关注工单、派单、执行人状态、队列和统计。
## IoT
设备域，核心关注设备、物模型、设备消息、规则、告警、OTA 和场景动作。
## 工单
Ops 中的核心业务对象，表示一项待执行或执行中的现场任务。
## 状态机
对工单生命周期的统一约束机制。

153
开发者文档/README.md
View File

@@ -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-附录/`：术语表与历史存档

15
开发者文档/图片/00-资源说明.md Normal file
View File

@@ -0,0 +1,15 @@
# 🖼️ 资源说明
这个目录用于存放：
- 架构图
- 流程图
- 时序图
- 页面截图
建议分别放入：
- `images/architecture`
- `images/diagrams`
- `images/screenshots`

190
开发者文档/系统架构.md
View File

@@ -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)

235
开发者文档/贡献指南.md
View File

@@ -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/) 规范：
```
<type>(<scope>): <subject>
<body>
<footer>
```
### 类型（type）
- `feat` — 新功能
- `fix` — 错误修复
- `docs` — 文档改进
- `style` — 代码风格（不影响功能）
- `refactor` — 代码重构
- `perf` — 性能优化
- `test` — 测试相关
- `chore` — 构建、依赖等
### 范围（scope）
- `backend` — 后端
- `frontend` — 前端
- `mobile` — 移动端
- `device` — 设备相关
- `docs` — 文档
- `infra` — 基础设施
### 例子
```
feat(backend): add device real-time status updates via WebSocket
- Implement WebSocket server for real-time device status
- Add subscription management for device changes
- Add reconnection logic with exponential backoff
Fixes #123
```
## ✅ Pull Request 检查清单
在提交 PR 前，请确保：
- [ ] 代码遵循项目编码规范
- [ ] 添加了必要的测试
- [ ] 所有测试通过
- [ ] 更新了相关文档
- [ ] Commit 信息清晰明了
- [ ] 没有 merge 冲突
- [ ] 代码审查无重大问题
## 🔍 代码审查
### 审查标准
- 代码质量和可维护性
- 测试覆盖率
- 性能影响
- 安全考虑
- API 设计一致性
### 审查流程
1. 至少一位维护者审查
2. 全部对话解决
3. 至少一个 Approve
4. CI/CD 通过
5. 合并到主分支
详见：[代码审查指南](10-standards/05-code-review.md)
## 🧪 测试要求
### 单元测试
- 所有新功能必须有单元测试
- 目标覆盖率：80%+
- 测试应该是独立的和快速的
### 集成测试
- 跨服务交互必须有集成测试
- 数据库操作需要测试
### 端到端测试（E2E）
- 关键用户流程必须有 E2E 测试
- 使用 Selenium/Cypress（前端）或 Appium（移动）
### 性能测试
- 关键路径的性能基准
- 监控性能回归
详见各端的测试指南：
- [后端测试](03-backend/09-testing.md)
- [前端测试](04-frontend/10-testing.md)
- [移动测试](05-mobile/11-testing.md)
## 📚 文档要求
### 代码注释
- 复杂逻辑需要注释
- 函数应该有 JSDoc/docstring
- 解释 *为什么*，不是 *什么*
### API 文档
- 新端点需要 OpenAPI/Swagger 文档
- 包括请求/响应示例
### README
- 新功能应该在 README 中提及
- 更新相关文档
### 更新日志
- 在 CHANGELOG.md 中记录重要变更
- 按版本组织
## 🚨 安全考虑
提交包含以下内容的 PR 时，请特别小心：
- [ ] 用户输入验证
- [ ] SQL 注入防护
- [ ] 跨站脚本（XSS）防护
- [ ] 跨站请求伪造（CSRF）防护
- [ ] 认证和授权检查
- [ ] 敏感数据加密
详见：[安全检查清单](11-guides/04-security-checklist.md)
## 💬 沟通和讨论
### GitHub Discussions
- 功能建议
- 架构讨论
- 最佳实践分享
### Issues
- Bug 报告
- 功能请求
- 任务跟踪
### 其他沟通
- 项目 Slack 频道
- 定期团队会议
## 🏆 贡献者荣誉
我们感谢所有贡献者！在以下地方获得认可：
- CONTRIBUTORS.md 文件
- GitHub Contributors 页面
- 项目网站
## ❓ 有问题？
- 查看 [FAQ](../13-faq/general.md)
- 提交 GitHub Issue
- 联系项目维护者
- 加入项目社区
## 📖 更多资源
- [开发指南](DEVELOPMENT.md)
- [Git 工作流详解](10-standards/03-git-workflow.md)
- [架构文档](ARCHITECTURE.md)
- [各端开发指南](01-getting-started/)
---
**感谢您的贡献！** 🎉
我们期待看到您的代码、想法和改进！