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

docs: 清理重复文件并完善协作规范

Browse Source 
- 删除 06-平台支撑 下重复的短文件目录（已被完整文档替代）
- 新增 07-协作规范 系列文档：
  - 01-代码仓协作边界.md
  - 02-开发工作流与-Git-规约.md
  - 03-文档回补触发清单.md
  - 04-代码评审与提测标准.md
This commit is contained in:
lzh
2026-04-07 13:02:02 +08:00
parent 2d6d1079a4
commit 7fb3aea295
11 changed files with 674 additions and 1546 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,226 +0,0 @@
# 01-接口分域与维护原则
本文档定义 AIOT 系统 API 接口的组织原则、文档维护责任边界，以及接口变更的协作流程。
**核心原则**：接口文档优先按**业务域**维护，而非按页面或客户端维护。因为页面会变、客户端会增，但领域边界相对稳定。
---
## 一、接口分域架构
### 1.1 四大核心域
| 域标识 | 对应微服务 | 职责范围 | 负责人 |
|--------|-----------|---------|--------|
| `system` | `module-system` | 用户、角色、菜单、部门、租户、字典 | 后端架构组 |
| `infra` | `module-infra` | 文件管理、定时任务、代码生成、消息推送 | 后端架构组 |
| `ops` | `module-ops` | 工单、巡检、保洁、安保、排班、考勤 | Ops 业务组 |
| `iot` | `module-iot` | 设备、物模型、规则引擎、告警、MQTT 桥接 | IoT 业务组 |
### 1.2 接口 URL 规范
所有接口必须遵循 RESTful 风格，并按域组织路径：
```
GET /api/system/users # 用户列表
POST /api/system/users # 创建用户
GET /api/system/users/{id} # 用户详情
PUT /api/system/users/{id} # 更新用户
DELETE /api/system/users/{id} # 删除用户
GET /api/ops/tickets # 工单列表
POST /api/ops/tickets/{id}/dispatch # 派单（业务操作）
POST /api/ops/tickets/{id}/confirm # 确认到岗（业务操作）
GET /api/iot/devices # 设备列表
POST /api/iot/devices/{id}/reboot # 重启设备（业务操作）
```
**禁止事项**：
- ❌ `/api/getUserList` - 非 RESTful
- ❌ `/api/ticket/updateStatus` - 动词在 URL 中，应使用 `/api/tickets/{id}/status`
- ❌ `/api/opsAndIot/xxx` - 跨域接口应拆分或通过事件驱动
---
## 二、接口文档维护责任
### 2.1 Swagger 注解是唯一的真理源
**所有接口必须在 Controller 方法上完整标注 Swagger 注解**：
```java
@RestController
@RequestMapping("/ops/tickets")
@Tag(name = "工单管理", description = "工单 CRUD 及状态流转")
public class TicketController {
@PostMapping("/dispatch")
@Operation(summary = "派单", description = "将工单派发给指定保洁员")
@PreAuthorize("@ss.hasPermi('ops:ticket:dispatch')")
public CommonResult<Long> dispatchTicket(@RequestBody @Valid TicketDispatchReqVO reqVO) {
// ...
}
}
```
**必填注解**：
- `@Tag` - 接口分组（对应域）
- `@Operation(summary = ..., description = ...)` - 接口用途
- `@Parameter` / `@Schema` - 参数说明
- `@ApiResponse` - 返回码说明（特别是业务错误码）
### 2.2 接口变更流程
```
开发者修改接口
↓
更新 Swagger 注解
↓
提交 MR → 自动触发 Swagger 文档生成
↓
前端/移动端负责人 Review 文档
↓
确认无破坏性变更后合并
```
**破坏性变更定义**（需提前通知所有调用方）：
- 删除或重命名已有字段
- 修改字段类型（如 `String` → `Integer`）
- 增加必填参数
- 修改接口路径或 HTTP 方法
**非破坏性变更**（可直接发布）：
- 新增可选参数
- 新增接口
- 增加返回字段
---
## 三、为什么不按页面维护接口文档
### 3.1 错误示例
```
❌ 按页面组织：
- 保洁管理页面接口
- 获取保洁员列表
- 创建保洁员
- 编辑保洁员
- 工单列表页面接口
- 获取工单列表
- 工单详情
```
**问题**：
1. 同一个 `/api/ops/cleaners` 接口可能被保洁管理页面、工单派发页面、排班页面同时使用
2. 新增一个移动端页面时，接口文档需要重复维护
3. 页面重构或合并时，接口文档需要大量调整
### 3.2 正确示例
```
✅ 按业务域组织：
- ops 域
- 保洁员管理
- GET /api/ops/cleaners - 保洁员列表
- POST /api/ops/cleaners - 创建保洁员
- PUT /api/ops/cleaners/{id} - 更新保洁员
- 工单管理
- GET /api/ops/tickets - 工单列表
- POST /api/ops/tickets/{id}/dispatch - 派单
```
**优势**：
1. 接口与页面解耦，一个接口服务多个客户端
2. 领域边界清晰，便于微服务拆分
3. 新增客户端（如小程序）时，直接引用已有域文档
---
## 四、接口版本管理
### 4.1 版本号位置
当需要发布不兼容的接口变更时，使用 URL 路径版本号：
```
GET /api/v1/ops/tickets # 旧版本
GET /api/v2/ops/tickets # 新版本（字段结构变化）
```
**禁止使用**：
- ❌ Query 参数版本：`/api/ops/tickets?version=2`
- ❌ Header 版本：`X-API-Version: 2`（不利于缓存和调试）
### 4.2 版本共存策略
- 新版本发布后，旧版本至少保留 **3 个月** 过渡期
- 在网关层监控旧版本接口的调用量，提前通知调用方迁移
- 过渡期结束后，在网关层返回 `410 Gone` 并引导升级
---
## 五、跨域接口处理
### 5.1 禁止跨域直接调用
```java
// ❌ 错误：ops 服务直接调用 iot 服务的 Feign Client
@Autowired
private IotDeviceClient deviceClient;
public void dispatchTicket() {
// 直接调用 IoT 服务
deviceClient.getDeviceStatus(deviceId);
}
```
**问题**：
- 微服务之间产生强耦合
- 无法独立部署和扩展
- 故障传播（IoT 服务宕机拖垮 Ops 服务）
### 5.2 正确做法：事件驱动
```java
// ✅ 正确：通过消息队列解耦
// Ops 服务发布事件
applicationEventPublisher.publishEvent(new TicketDispatchedEvent(ticketId, deviceId));
// IoT 服务监听事件并处理
@EventListener
public void onTicketDispatched(TicketDispatchedEvent event) {
// 处理设备相关逻辑
}
```
---
## 六、接口文档访问
### 6.1 Swagger UI 地址
| 环境 | 地址 |
|------|------|
| 开发环境 | `http://localhost:48080/swagger-ui.html` |
| 测试环境 | `http://test-api.example.com/swagger-ui.html` |
| 生产环境 | **不开放**（通过内部文档平台查看） |
### 6.2 导出 OpenAPI 规范
```bash
# 导出 YAML 格式
curl http://localhost:48080/v3/api-docs -o openapi.yaml
# 导出 JSON 格式
curl http://localhost:48080/v3/api-docs -o openapi.json
```
---
## 七、相关文档
- [00-支撑平台总览.md](../00-支撑平台总览.md)
- [01-统一网关入口规范.md](../01-统一网关入口规范.md)
- [08-数据库/01-数据域划分与表关系思路.md](../08-数据库/01-数据域划分与表关系思路.md)

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

@@ -1,350 +0,0 @@
# 01-部署运行与排障视角
本文档建立 AIOT 系统的排障方法论，帮助开发和运维人员快速定位问题所属层次，而非堆砌命令。
**核心原则**：排障第一刀先判断问题属于哪一层，再逐层深入。禁止一上来就 `kubectl logs` 或 `docker exec` 盲目翻日志。
---
## 一、系统分层架构
```
┌─────────────────────────────────────────────────────────────┐
│ 客户端层 (Client) │
│ Web 管理后台 │ 移动端 App │ 小程序 │ 工牌/信标 │
└─────────────────────────────────────────────────────────────┘
↓ HTTPS / MQTT
┌─────────────────────────────────────────────────────────────┐
│ 网关入口层 (Gateway) │
│ viewsh-gateway (Spring Cloud Gateway + Sentinel) │
│ - 路由分发 - JWT 鉴权 - 限流熔断 - 黑白名单 │
└─────────────────────────────────────────────────────────────┘
↓ 内部 HTTP / Feign
┌─────────────────────────────────────────────────────────────┐
│ 主服务装配层 (Microservices) │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│ │module-system│ module-infra│ module-ops │ module-iot │ │
│ │ 用户角色权限 │ 文件任务消息│ 工单巡检保洁│ 设备物模型 │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
│ Nacos (注册发现/配置中心) │
│ Redis (缓存/分布式锁) │
│ MQ (RabbitMQ/Kafka 消息队列) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ IoT 规则与设备层 (IoT Edge) │
│ MQTT Broker (EMQX) │ 规则引擎 │ 设备影子 │ 边缘网关 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Ops 状态与执行层 (Physical) │
│ 智能工牌 (Badge) │ 蓝牙信标 (Beacon) │ 现场工作人员 │
└─────────────────────────────────────────────────────────────┘
```
---
## 二、排障决策树
### 2.1 第一刀：问题现象归类
```
用户报告问题
↓
┌──────────────────────────────────────────┐
│ 1. 所有用户都访问不了？ │
│ → 网关入口层 / 基础设施层 │
│ → 检查网关健康度、Nacos、数据库连接池 │
└──────────────────────────────────────────┘
↓ 否
┌──────────────────────────────────────────┐
│ 2. 特定功能访问不了？ │
│ → 主服务装配层 │
│ → 检查对应微服务状态、日志、依赖中间件 │
└──────────────────────────────────────────┘
↓ 否
┌──────────────────────────────────────────┐
│ 3. 设备数据不上报/不响应？ │
│ → IoT 规则与设备层 │
│ → 检查 MQTT Broker、设备在线状态、规则引擎│
└──────────────────────────────────────────┘
↓ 否
┌──────────────────────────────────────────┐
│ 4. 工单状态不更新/信标无感应？ │
│ → Ops 状态与执行层 │
│ → 检查工牌电量、信标广播、蓝牙连接日志 │
└──────────────────────────────────────────┘
```
---
## 三、各层排障清单
### 3.1 网关入口层
**典型症状**：
- 所有接口返回 `502 Bad Gateway` 或 `503 Service Unavailable`
- 登录接口正常，业务接口全部 `401 Unauthorized`
- 部分用户访问正常，部分用户报错
**检查步骤**：
```bash
# 1. 检查网关容器状态
docker ps | grep gateway
docker logs viewsh-gateway --tail 100
# 2. 检查网关健康端点
curl http://gateway-host:18080/actuator/health
# 3. 检查 Nacos 服务注册
curl http://nacos-host:8848/nacos/v1/ns/instance/list?serviceName=module-ops
# 4. 检查网关路由配置 (Nacos 配置中心)
# Data ID: viewsh-gateway.yaml
# 检查 route 配置是否指向正确的服务名
# 5. 检查 JWT 密钥配置
# 确认 gateway 和 各微服务使用相同的 jwt.secret
```
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 全部 502 | 下游服务全部未注册 | 检查 Nacos 是否正常，微服务是否启动 |
| 全部 401 | JWT 密钥不一致 | 统一 Nacos 中的 `jwt.secret` 配置 |
| 部分路由 404 | 路由配置遗漏 | 在 Nacos 网关配置中补充 route |
| 限流报错 429 | 触发 Sentinel 限流 | 检查限流阈值，临时调高或扩容 |
---
### 3.2 主服务装配层
**典型症状**：
- 特定功能报错（如工单列表打不开，但用户管理正常）
- 接口响应极慢（>5s）
- 间歇性报错，重试后正常
**检查步骤**：
```bash
# 1. 定位问题服务
# 根据功能确定所属微服务：
# - 工单/保洁/巡检 → module-ops
# - 设备/物模型/告警 → module-iot
# - 用户/角色/权限 → module-system
# 2. 检查服务容器状态
docker ps | grep module-ops
docker stats module-ops # 查看 CPU/内存使用率
# 3. 查看应用日志
docker logs module-ops --tail 200 | grep -E "ERROR|WARN"
# 4. 检查 JVM 状态
docker exec module-ops jstat -gcutil <pid> 1000 5
# 5. 检查数据库连接池
# 登录 MySQL 查看连接数
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Threads_connected';
# 6. 检查 Redis 连接
redis-cli -h redis-host ping
redis-cli -h redis-host KEYS "aiot:ops:*" | head 20
# 7. 检查 MQ 队列积压
# RabbitMQ 管理界面：http://mq-host:15672
# 查看队列消息数，确认是否有消费失败
```
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 接口超时 | 数据库慢查询 | 检查慢查询日志，添加索引 |
| 内存溢出 OOM | 堆内存不足 | 调大 `-Xmx`，检查内存泄漏 |
| 数据库连接耗尽 | 连接池配置过小 | 调大 `maximum-pool-size` |
| Redis 连接失败 | Redis 宕机或密码错误 | 检查 Redis 状态和 Nacos 配置 |
| MQ 消息积压 | 消费者处理慢或宕机 | 检查消费者日志，增加并发数 |
---
### 3.3 IoT 规则与设备层
**典型症状**：
- 设备显示离线，但实际已通电
- 设备上报数据，但系统未收到
- 规则引擎未触发预期动作
**检查步骤**：
```bash
# 1. 检查 MQTT Broker 状态
docker ps | grep emqx
docker logs emqx --tail 100
# 2. 检查设备在线状态
# EMQX 管理界面：http://emqx-host:18083
# 查看设备连接数、订阅主题
# 3. 检查设备认证日志
docker logs emqx | grep "device-xxx"
# 4. 检查规则引擎
# EMQX 规则界面：查看规则执行日志
# 确认规则 SQL 是否正确，动作是否配置
# 5. 检查设备消息日志
# 查询 iot_message_log 表
SELECT * FROM iot_message_log
WHERE device_id = xxx
ORDER BY created_at DESC
LIMIT 10;
# 6. 模拟设备上报测试
# 使用 MQTT.fx 或命令行工具
mosquitto_pub -h emqx-host -t "/sys/xxx/xxx/post" -m '{"temp": 25}'
```
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 设备连不上 | 设备密钥错误或 Broker 宕机 | 检查设备三元组，重启 EMQX |
| 数据不上报 | 网络问题或主题错误 | 检查设备网络，确认发布主题 |
| 规则不触发 | 规则 SQL 语法错误 | 在 EMQX 控制台测试规则 SQL |
| 消息丢失 | QoS 级别过低 | 设备端使用 QoS 1 或 2 |
---
### 3.4 Ops 状态与执行层
**典型症状**：
- 保洁员已到岗，但系统显示未到达
- 工单派发了，但工牌未收到通知
- 信标感应失败，无法自动完工
**检查步骤**：
```bash
# 1. 检查工牌状态
# 查询 ops_cleaner 表
SELECT id, name, badge_no, status, current_ticket_id
FROM ops_cleaner
WHERE id = xxx;
# 2. 检查信标绑定关系
# 查询 iot_device 或 ops_location 表
SELECT beacon_id, location_name
FROM ops_location
WHERE id = xxx;
# 3. 检查工单状态流转日志
SELECT * FROM ops_ticket_log
WHERE ticket_id = xxx
ORDER BY created_at DESC;
# 4. 检查蓝牙信标广播
# 使用手机 App 或 nRF Connect 扫描信标
# 确认信标 UUID、Major、Minor 是否正确广播
# 5. 检查工牌电量
# 工牌管理界面查看电量，或询问现场人员
# 电量低于 20% 可能导致蓝牙断开
# 6. 检查信标感应日志
# 查看 IoT 服务日志中信标事件上报记录
docker logs module-iot | grep "beacon:xxx"
```
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 未自动到岗 | 信标未广播或工牌未感应 | 检查信标电量，重新绑定 |
| 工牌未收到派单 | 工牌离线或 MQTT 断开 | 检查工牌网络，重启工牌 |
| 状态不更新 | 工牌按键损坏或固件 bug | 更换工牌，升级固件 |
| 误感应 | 信标位置过近或信号穿透 | 调整信标位置，降低发射功率 |
---
## 四、常用诊断命令速查
### 4.1 容器诊断
```bash
# 查看所有容器状态
docker ps -a
# 查看容器资源使用
docker stats
# 查看容器日志
docker logs <container> --tail 100 -f
# 进入容器调试
docker exec -it <container> bash
# 重启容器
docker restart <container>
```
### 4.2 数据库诊断
```bash
# 查看当前连接
SHOW PROCESSLIST;
# 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';
# 查看表锁
SHOW OPEN TABLES WHERE In_use > 0;
# 查看连接数
SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';
```
### 4.3 Redis 诊断
```bash
# 连接测试
redis-cli -h <host> ping
# 查看内存使用
redis-cli info memory
# 查看慢查询
redis-cli slowlog get 10
# 查看 Key 数量
redis-cli dbsize
# 查看特定 Key
redis-cli get "aiot:ops:ticket:1001"
```
### 4.4 网络诊断
```bash
# 测试端口连通性
telnet <host> <port>
nc -zv <host> <port>
# DNS 解析
nslookup <domain>
dig <domain>
# 路由追踪
traceroute <host>
mtr <host>
```
---
## 五、相关文档
- [00-支撑平台总览.md](../00-支撑平台总览.md)
- [01-统一网关入口规范.md](../01-统一网关入口规范.md)
- [02-中间件使用规约.md](../02-中间件使用规约.md)
- [02-环境部署指南.md](./02-环境部署指南.md)

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

@@ -1,548 +0,0 @@
# 02-环境部署指南
本文档描述 AIOT 项目从开发环境到生产环境的完整部署流程、配置规范和运维操作。
---
## 一、环境规划
### 1.1 环境清单
| 环境 | 用途 | 域名 | 数据库 | 更新频率 | 负责人 |
|------|------|------|--------|---------|--------|
| **开发 (Dev)** | 本地开发联调 | `dev-api.example.com` | 共享 Dev DB | 随时 | 开发者 |
| **测试 (Test)** | QA 功能测试 | `test-api.example.com` | 独立 Test DB | 每日 | QA |
| **预生产 (Staging)** | 上线前验证 | `staging-api.example.com` | 生产库只读副本 | 每周 | DevOps |
| **生产 (Prod)** | 正式用户 | `api.example.com` | 生产主库 | 计划性 | DevOps+PM |
### 1.2 环境隔离原则
```
┌─────────────────────────────────────────────────────────────┐
│ 开发环境 (Dev) │
│ - 开发者本地 Docker Compose 或 WSL2 运行 │
│ - 连接共享 Dev 数据库（多人共用） │
│ - Nacos 配置：dev Profile │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 测试环境 (Test) │
│ - 独立服务器/容器集群 │
│ - 独立 Test 数据库（每日从生产脱敏同步） │
│ - Nacos 配置：test Profile │
│ - Jenkins 自动部署（test 分支触发） │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 预生产环境 (Staging) │
│ - 独立服务器/容器集群（配置同生产） │
│ - 生产库只读副本（用于验证 SQL） │
│ - Nacos 配置：prod Profile（但指向测试 MQ/Redis） │
│ - 手动触发部署（Release 分支） │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 生产环境 (Prod) │
│ - 高可用集群（多副本 + 负载均衡） │
│ - 生产主数据库（主从复制） │
│ - Nacos 配置：prod Profile │
│ - 严格审批流程（PM+Tech Lead 签字） │
└─────────────────────────────────────────────────────────────┘
```
---
## 二、开发环境部署（本地）
### 2.1 前置条件
```bash
# 必需软件
- Docker 20.10+
- Docker Compose 2.0+
- JDK 11/17
- Maven 3.8+
- Node.js 18+
- pnpm 8+
# 可选工具
- MySQL Workbench / DBeaver
- Redis Desktop Manager
- Postman / Apifox
```
### 2.2 启动基础设施
```bash
# 进入项目根目录
cd /path/to/aiot-platform-cloud
# 启动核心中间件（Nacos + MySQL + Redis + EMQX）
docker-compose -f docker-compose.core.yml up -d
# 检查容器状态
docker-compose -f docker-compose.core.yml ps
# 查看 Nacos 日志（确认启动成功）
docker logs aiot-nacos --tail 50
```
**核心服务端口**：
| 服务 | 端口 | 访问地址 |
|------|------|---------|
| Nacos | 8848 | `http://localhost:8848/nacos` |
| MySQL | 3306 | `localhost:3306` |
| Redis | 6379 | `localhost:6379` |
| EMQX | 1883/18083 | `localhost:18083` |
| RabbitMQ | 5672/15672 | `localhost:15672` |
**默认账号**：
- Nacos: `nacos / nacos`
- MySQL: `root / aiot123456`
- Redis: 无密码
- RabbitMQ: `guest / guest`
- EMQX: `admin / public`
### 2.3 初始化数据库
```bash
# 1. 创建数据库
mysql -h localhost -u root -p << EOF
CREATE DATABASE IF NOT EXISTS aiot_platform
DEFAULT CHARACTER SET utf8mb4
DEFAULT COLLATE utf8mb4_general_ci;
USE aiot_platform;
EOF
# 2. 导入表结构
mysql -h localhost -u root -p aiot_platform < sql/aiot_schema.sql
# 3. 导入初始数据（租户、管理员账号、菜单权限）
mysql -h localhost -u root -p aiot_platform < sql/aiot_data.sql
```
### 2.4 配置 Nacos
1. 访问 `http://localhost:8848/nacos`
2. 登录（`nacos / nacos`）
3. 导入配置（`导入` → 选择 `config/` 目录下的配置文件）
- `viewsh-gateway.yaml`
- `module-system.yaml`
- `module-ops.yaml`
- `module-iot.yaml`
- `application-common.yaml`
**关键配置项检查**：
```yaml
# application-common.yaml
spring:
datasource:
url: jdbc:mysql://host.docker.internal:3306/aiot_platform?useSSL=false
username: root
password: aiot123456
redis:
host: host.docker.internal
port: 6379
# 开发环境特殊配置
aiot:
dev-mode: true
swagger-enable: true
mock-iot-device: true # 启用模拟设备上报
```
> **注意**：Docker 容器内访问宿主机服务需使用 `host.docker.internal` 而非 `localhost`。
### 2.5 启动后端服务
```bash
# 1. 编译网关
cd viewsh-gateway
mvn clean package -DskipTests -P dev
java -jar target/viewsh-gateway.jar --spring.profiles.active=dev
# 2. 编译主服务（module-system / module-ops / module-iot）
cd module-system
mvn clean package -DskipTests -P dev
java -jar target/module-system.jar --spring.profiles.active=dev
# 3. 检查服务注册
# 访问 Nacos 控制台，确认服务状态为「健康」
```
### 2.6 启动前端
```bash
# 1. 安装依赖
cd yudao-ui-admin-vben
pnpm install
# 2. 配置环境变量
# 复制 .env.development 并修改 API 地址
cp .env.development .env.development.local
echo "VITE_API_BASE_URL=http://localhost:18080" >> .env.development.local
# 3. 启动开发服务器
pnpm dev
# 4. 访问管理后台
# http://localhost:5173
# 默认管理员账号：admin / admin123
```
---
## 三、测试环境部署（Jenkins 自动）
### 3.1 部署流程
```
开发者推送代码到 test 分支
↓
GitLab Webhook 触发 Jenkins Job
↓
Jenkins 拉取代码 → Maven 编译 → 运行单元测试
↓
构建 Docker 镜像（Tag: test-{commit_hash}）
↓
推送到私有镜像仓库
↓
SSH 登录测试服务器 → docker pull → docker stop → docker run
↓
健康检查（/actuator/health）
↓
发送通知到飞书/钉钉群
```
### 3.2 Jenkinsfile 示例
```groovy
pipeline {
agent any
environment {
DOCKER_IMAGE = "registry.example.com/aiot/module-ops"
DOCKER_TAG = "test-${env.GIT_COMMIT.take(7)}"
}
stages {
stage('Checkout') {
steps {
git branch: 'test',
url: 'git@gitlab.example.com:aiot/aiot-platform-cloud.git'
}
}
stage('Build') {
steps {
sh 'cd module-ops && mvn clean package -DskipTests -P test'
}
}
stage('Unit Test') {
steps {
sh 'cd module-ops && mvn test'
}
}
stage('Docker Build') {
steps {
sh '''
cd module-ops
docker build -t ${DOCKER_IMAGE}:${DOCKER_TAG} .
docker push ${DOCKER_IMAGE}:${DOCKER_TAG}
'''
}
}
stage('Deploy') {
steps {
sh '''
ssh deploy@test-server "
docker pull ${DOCKER_IMAGE}:${DOCKER_TAG} &&
docker stop module-ops || true &&
docker rm module-ops || true &&
docker run -d --name module-ops \\
-p 18081:18080 \\
-e SPRING_PROFILES_ACTIVE=test \\
${DOCKER_IMAGE}:${DOCKER_TAG}
"
'''
}
}
stage('Health Check') {
steps {
sh '''
for i in {1..30}; do
if curl -s http://test-server:18081/actuator/health | grep -q UP; then
echo "Deploy successful!"
exit 0
fi
sleep 2
done
echo "Health check failed!"
exit 1
'''
}
}
}
post {
success {
// 发送飞书通知
sh '''
curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/xxx \\
-H "Content-Type: application/json" \\
-d '{"msg_type":"text","content":{"text":"✅ module-ops 测试环境部署成功\\n版本：${DOCKER_TAG}"}}'
'''
}
failure {
// 发送失败通知
sh '''
curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/xxx \\
-H "Content-Type: application/json" \\
-d '{"msg_type":"text","content":{"text":"❌ module-ops 测试环境部署失败\\n请检查 Jenkins 日志"}}'
'''
}
}
}
```
---
## 四、生产环境部署（严格审批）
### 4.1 部署前检查清单
**必须全部勾选才能执行部署**：
- [ ] **代码审查**：MR 已获 2 人以上 Approve
- [ ] **测试报告**：QA 已签署测试通过报告
- [ ] **SQL 审查**：涉及数据库变更的 SQL 已获 DBA 审核
- [ ] **回滚方案**：已制定明确回滚步骤并验证
- [ ] **备份确认**：生产数据库已完成全量备份
- [ ] **通知到位**：相关干系人（客服、运营）已收到部署通知
- [ ] **时间窗口**：部署时间在低峰期（凌晨 2:00-4:00）
- [ ] **值班人员**：DevOps 和业务负责人在线待命
### 4.2 部署流程
```bash
# 1. 创建 Release 分支（从 master 最新提交）
git checkout master
git pull
git checkout -b release/v1.2.0
# 2. 更新版本号
# 修改各模块 pom.xml 中的 <version>1.2.0</version>
# 修改 CHANGELOG.md
# 3. 提交并打 Tag
git add .
git commit -m "release: v1.2.0"
git tag -a v1.2.0 -m "Release version 1.2.0"
# 4. 推送 Release 分支和 Tag
git push origin release/v1.2.0
git push origin v1.2.0
# 5. 在 Jenkins 触发生产部署 Job
# 选择 Release 分支，确认版本号，点击「部署到生产」
# 6. 部署过程中实时监控
# - Grafana 仪表盘（CPU、内存、QPS、错误率）
# - 日志平台（ELK）
# - 业务监控（工单处理量、设备在线数）
# 7. 部署完成后验证
# - 冒烟测试（核心功能快速验证）
# - 确认无异常日志
# - 通知干系人部署完成
```
### 4.3 回滚流程
**当生产部署后出现严重 Bug 时**：
```bash
# 1. 立即通知
# 飞书群通知：「生产环境出现异常，准备回滚到 v1.1.0」
# 2. 执行回滚
# Jenkins 选择「回滚」Job，选择上一个稳定版本 v1.1.0
# 3. 验证回滚
# - 确认服务恢复正常
# - 检查数据一致性（是否有脏数据）
# 4. 事后复盘
# - 记录事故时间线
# - 分析根本原因
# - 制定改进措施
```
---
## 五、Docker 部署详解
### 5.1 Dockerfile 示例（后端）
```dockerfile
# 构建阶段
FROM maven:3.8-openjdk-17 AS builder
WORKDIR /build
COPY pom.xml .
COPY module-ops/pom.xml module-ops/
RUN mvn -f module-ops/pom.xml dependency:go-offline -B
COPY module-ops/src module-ops/src
RUN mvn -f module-ops/pom.xml clean package -DskipTests
# 运行阶段
FROM openjdk:17-slim
WORKDIR /app
# 创建非 root 用户
RUN useradd -m -u 1000 appuser
# 复制 JAR
COPY --from=builder /build/module-ops/target/*.jar app.jar
# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \\
CMD curl -f http://localhost:18080/actuator/health || exit 1
# 切换用户
USER appuser
EXPOSE 18080
ENTRYPOINT ["java", "-jar", "app.jar", "--spring.profiles.active=prod"]
```
### 5.2 Docker Compose 示例（生产）
```yaml
version: '3.8'
services:
gateway:
image: registry.example.com/aiot/viewsh-gateway:v1.2.0
ports:
- "80:18080"
- "443:18443"
environment:
- SPRING_PROFILES_ACTIVE=prod
- NACOS_SERVER_ADDR=nacos:8848
depends_on:
- nacos
restart: always
deploy:
replicas: 2
resources:
limits:
cpus: '2'
memory: 2G
module-ops:
image: registry.example.com/aiot/module-ops:v1.2.0
environment:
- SPRING_PROFILES_ACTIVE=prod
- NACOS_SERVER_ADDR=nacos:8848
depends_on:
- nacos
- mysql
- redis
restart: always
deploy:
replicas: 3
resources:
limits:
cpus: '4'
memory: 4G
nacos:
image: nacos/nacos-server:2.2.0
environment:
- MODE=cluster
- NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
volumes:
- ./nacos/cluster-logs:/home/nacos/logs
restart: always
mysql:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
volumes:
- mysql-data:/var/lib/mysql
restart: always
redis:
image: redis:7-alpine
command: redis-server --appendonly yes
volumes:
- redis-data:/data
restart: always
volumes:
mysql-data:
redis-data:
```
---
## 六、监控与告警
### 6.1 关键监控指标
| 指标类别 | 指标名称 | 告警阈值 | 告警级别 |
|---------|---------|---------|---------|
| **应用层** | HTTP 错误率 | > 1% | P1 |
| | API 响应时间 P99 | > 2000ms | P2 |
| | JVM 堆内存使用率 | > 85% | P2 |
| **中间件** | MySQL 连接数 | > 80% | P2 |
| | Redis 内存使用率 | > 80% | P2 |
| | MQ 消息积压 | > 10000 | P2 |
| **业务层** | 工单派发失败率 | > 5% | P1 |
| | 设备离线率 | > 10% | P2 |
| | 信标感应成功率 | < 95% | P2 |
### 6.2 告警通知渠道
```yaml
# Prometheus Alertmanager 配置
receivers:
- name: 'feishu-p1'
webhook_configs:
- url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx'
send_resolved: true
# P1 级别：电话 + 飞书
- name: 'feishu-p2'
webhook_configs:
- url: 'https://open.feishu.cn/open-apis/bot/v2/hook/yyy'
send_resolved: true
# P2 级别：飞书
- name: 'email'
email_configs:
- to: 'devops@example.com'
send_resolved: true
# P3 级别：邮件
```
---
## 七、相关文档
- [03-CICD 与部署流水线规范.md](../03-CICD 与部署流水线规范.md)
- [01-部署运行与排障视角.md](./01-部署运行与排障视角.md)
- [07-协作规范/02-开发工作流与-Git-规约.md](../../07-协作规范/02-开发工作流与-Git-规约.md)

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

@@ -1,50 +0,0 @@
# 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. **表结构重大重构**：必须在团队群内通报，并更新相关的实体关系说明文档。

140
开发者文档/07-协作规范/01-代码仓协作边界.md Normal file
View File

@@ -0,0 +1,140 @@
# 01-代码仓协作边界
本文档定义 AIOT 项目三大主仓的职责边界、代码归属原则，以及问题排查的入口判断。所有开发人员必须在提代码前确认：这段代码应该放在哪个仓。
---
## 一、三大主仓职责
| 仓库 | 职责 | 技术栈 | 负责人 |
|------|------|--------|--------|
| `aiot-platform-cloud` | 后端业务与平台能力 | Spring Boot / Java | 后端团队 |
| `yudao-ui-admin-vben` | Web 管理端 | Vue3 + Vben Admin / TypeScript | 前端团队 |
| `aiot-uniapp` | 移动端（小程序/App） | Uniapp / Vue3 | 移动端团队 |
---
## 二、代码归属判定原则
### 2.1 后端代码归属 (`aiot-platform-cloud`)
**必须放在后端的代码：**
- 业务实体（Entity）与数据库交互（Mapper/DAO）
- 业务状态机与核心领域逻辑（Service）
- 对外暴露的 REST API（Controller）
- 设备接入协议解析与物模型处理
- 调度算法与队列管理
**严禁放在后端的代码：**
- 页面渲染逻辑
- 客户端状态管理
- 纯展示用的数据转换（应放在前端）
### 2.2 前端代码归属 (`yudao-ui-admin-vben`)
**必须放在前端的代码：**
- 管理台页面组件（views）
- 页面级状态管理（Pinia store）
- API 调用封装（api）
- 业务组件与页面布局
**严禁放在前端的代码：**
- 直接操作数据库的 SQL
- 业务状态机核心逻辑（只能调用后端接口）
- 设备协议解析
### 2.3 移动端代码归属 (`aiot-uniapp`)
**必须放在移动端的代码：**
- 小程序/App 页面
- 现场作业流程页面（接单、执行、反馈）
- 扫码、定位、拍照等原生能力调用
- 离线缓存与本地数据管理
**严禁放在移动端的代码：**
- 工单状态机核心逻辑（只能调用后端接口）
- 派单算法
- 设备控制指令生成（只能调用后端接口）
---
## 三、跨仓调用规范
### 3.1 调用方向
```
移动端 ──HTTP──┐
├──→ 后端 (aiot-platform-cloud)
Web前端 ──HTTP─┘
```
- 前端/移动端只允许通过 HTTP API 调用后端
- 严禁前端直接操作数据库或 Redis
- 严禁移动端直接调用设备网关
### 3.2 API 契约管理
- 后端 Controller 必须提供 Swagger 注解
- 前端/移动端必须按 Swagger 定义封装 API，禁止随意构造请求
- API 变更必须同步更新 Swagger 并通知调用方
---
## 四、问题排查入口判断
遇到问题时，按以下优先级确定先去哪个仓排查：
### 4.1 问题分类速查表
| 现象 | 优先排查仓 | 可能原因 |
|------|-----------|---------|
| 页面白屏/样式错乱 | `yudao-ui-admin-vben` | 前端组件、路由、样式 |
| 接口返回 500 | `aiot-platform-cloud` | 后端业务逻辑、数据库 |
| 接口返回 404/403 | `aiot-platform-cloud` | 路由配置、权限配置 |
| 小程序无法加载 | `aiot-uniapp` | 分包配置、页面路径 |
| 扫码/定位失败 | `aiot-uniapp` | 原生能力调用、权限 |
| 工单状态不更新 | `aiot-platform-cloud` | 状态机、调度逻辑 |
| 设备状态不刷新 | `aiot-platform-cloud` | 设备接入、物模型 |
| 推送消息收不到 | `aiot-platform-cloud` | 消息推送服务 |
### 4.2 排查流程
1. **先看报错位置**：浏览器控制台 / 小程序调试器 / 后端日志
2. **确定边界**：是前端渲染问题，还是接口返回问题？
3. **定位仓库**：按上表确定优先排查的仓库
4. **跨仓确认**：如果怀疑是接口问题，先在后端单元测试复现
---
## 五、新增代码的归属决策
如果不确定新代码该放哪个仓，按以下决策树：
```
这段代码是否涉及数据库操作？
├── 是 → 必须放在 aiot-platform-cloud
└── 否 → 这段代码是否在小程序/App 中运行？
├── 是 → 必须放在 aiot-uniapp
└── 否 → 这段代码是否在 Web 管理台中运行？
├── 是 → 必须放在 yudao-ui-admin-vben
└── 否 → 找 Tech Lead 确认
```
---
## 六、禁止行为
以下行为一经发现，必须立即整改：
1. **跨仓复制代码**：同样的逻辑在多个仓重复实现
2. **前端直接操作数据库**：通过暴露的接口绕过后端
3. **后端返回未定义的字段**：Swagger 与实际返回不一致
4. **移动端硬编码业务规则**：如工单状态流转逻辑
5. **跨仓提交代码**：在 A 仓提交 B 仓的代码（应使用 submodule 或 npm 包）
---
## 七、相关文档
- [00-导航与总览/03-代码仓与协作边界.md](../00-导航与总览/03-代码仓与协作边界.md) - 项目级别的仓边界说明
- [02-开发工作流与 Git 规约.md](./02-开发工作流与-Git-规约.md) - 提交与分支规范

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

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

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

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

207
开发者文档/07-协作规范/02-开发工作流与-Git-规约.md Normal file
View File

@@ -0,0 +1,207 @@
# 02-开发工作流与 Git 规约
本文档定义 AIOT 项目的日常开发工作流、Git 使用规范，以及代码提交的底线要求。所有开发人员必须遵守，Code Review 以此为准绳。
---
## 一、分支策略
### 1.1 主分支
| 分支 | 用途 | 保护级别 |
|------|------|---------|
| `main` | 生产环境代码 | 严格保护，需 PR + Review |
| `develop` | 集成测试环境 | 保护，需 PR |
### 1.2 功能分支命名
所有开发必须在功能分支上进行，禁止直接向 `main` 或 `develop` 提交。
```
类型/描述
示例：
feature/order-status-flow # 新功能
fix/inspection-bug-20240407 # Bug 修复
refactor/cleaner-service # 代码重构
docs/api-swagger-update # 文档更新
perf/query-optimization # 性能优化
test/unit-test-coverage # 测试相关
```
**命名规则：**
- 使用小写字母和连字符 `-`
- 描述简洁，能一眼看出分支目的
- 关联 Jira/Tapd 任务时，可在描述后加任务号
---
## 二、Commit 规范
### 2.1 Commit 消息格式
```
<类型>(<范围>): <简短描述>
<详细说明（可选）>
<关联任务（可选）>
```
### 2.2 类型定义
| 类型 | 用途 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(order): 新增工单申诉功能` |
| `fix` | Bug 修复 | `fix(device): 修复设备离线状态同步延迟` |
| `docs` | 文档更新 | `docs(api): 更新保洁单接口 Swagger 注解` |
| `style` | 代码格式（不影响功能） | `style(cleaner): 统一 Service 代码缩进` |
| `refactor` | 代码重构 | `refactor(inspection): 抽取巡检定责逻辑到独立 Service` |
| `perf` | 性能优化 | `perf(query): 优化工单列表查询 SQL` |
| `test` | 测试相关 | `test(unit): 新增 CleanerService 单元测试` |
| `chore` | 构建/工具/依赖 | `chore(deps): 升级 Spring Boot 至 3.2.x` |
### 2.3 范围定义
范围指本次变更影响的模块或业务域：
```
# 后端范围
system # 系统管理模块
infra # 基础设施模块
iot # IoT 设备模块
ops # Ops 工单模块 (cleaner/inspection/security)
cleaner # 保洁模块
inspection# 巡检模块
security # 安保模块
framework # 框架层
# 前端/移动端范围
views # 页面组件
api # API 封装
components# 共享组件
store # 状态管理
utils # 工具函数
```
### 2.4 Commit 示例
```bash
# 简单提交
feat(cleaner): 新增保洁单批量派单接口
# 带详细说明
fix(inspection): 修复巡检不合格时定责算法空指针异常
- 原逻辑未处理 cleanerWorkOrder 为 null 的情况
- 新增空值检查，无关联保洁单时判定为"突发状况"
Closes #123
# 文档更新
docs(api): 更新工单状态机文档，补充 ARRIVED 状态说明
- 说明 ARRIVED 状态由工牌蓝牙信标自动触发
- 移除错误的"手机 GPS 打卡"描述
```
---
## 三、Pull Request 规范
### 3.1 PR 创建要求
- 必须从功能分支向 `develop` 或 `main` 创建 PR
- PR 标题格式：`[类型] 简短描述`，如 `[feat] 新增工单申诉功能`
- PR 描述必须包含：
- 变更目的
- 主要改动点
- 测试情况
- 关联的任务/缺陷单号
### 3.2 PR Review 要求
| 场景 | Reviewer 要求 |
|------|--------------|
| 业务逻辑变更 | 必须找熟悉该业务域的同事 Review |
| 跨模块改动 | 必须找各模块负责人 Review |
| 数据库变更 | 必须找 Tech Lead Review |
| 公共框架改动 | 必须找架构组 Review |
### 3.3 Review 通过标准
- 至少 1 个 Approve（复杂改动需 2 个）
- 所有评论必须 Resolved
- CI 检查通过（编译、单元测试、代码规范）
---
## 四、冲突处理
### 4.1 预防冲突
- 功能分支生命周期尽量短（建议不超过 1 周）
- 每天开始工作前先 `git pull origin develop`
- 大型改动提前在群里同步，避免多人同时改同一文件
### 4.2 解决冲突
```bash
# 1. 更新本地主分支
git checkout develop
git pull origin develop
# 2. 切换回功能分支并 rebase
git checkout feature/your-branch
git rebase develop
# 3. 解决冲突（编辑冲突文件）
# 冲突标记格式：
# <<<<<<< HEAD
# 当前分支的代码
# =======
# develop 分支的代码
# >>>>>>> develop
# 4. 标记已解决
git add <冲突文件>
git rebase --continue
# 5. 强制推送（因为 rebase 会改写历史）
git push origin feature/your-branch -f
```
**冲突解决原则：**
- 不要只保留自己的代码，要理解对方改动的意图
- 涉及业务逻辑的冲突，找对方确认后再提交
- 冲突解决后必须重新测试
---
## 五、代码提交底线
以下情况禁止提交代码：
1. **未自测的代码**：至少本地能跑通主流程
2. **包含调试代码**：如 `console.log`、`System.out.println`、临时注释
3. **未处理的 TODO**：如果必须留 TODO，要在 PR 中说明计划处理时间
4. **敏感信息**：密码、密钥、内网 IP、个人配置
5. **大文件**：二进制文件、日志文件、本地缓存
---
## 六、紧急修复流程
生产环境出现紧急 Bug，需要绕过正常流程时：
1. 从 `main` 切出 `hotfix/xxx` 分支
2. 修复后直接向 `main` 提 PR，同时向 `develop` 提 PR 同步修复
3. 在群里同步 hotfix 内容
4. 事后补全测试用例
---
## 七、相关文档
- [01-代码仓协作边界.md](./01-代码仓协作边界.md) - 代码归属与问题排查
- [03-文档回补触发清单.md](./03-文档回补触发清单.md) - 变更后必须同步的文档

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

@@ -1,319 +0,0 @@
# 开发工作流
本文档描述了 AIOT 项目的日常开发工作流和最佳实践。
## 🔄 日常工作流
### 1. 同步最新代码
```bash
# 更新 main 分支
git fetch origin
git checkout main
git pull origin main
# 创建功能分支
git checkout -b feature/your-feature
```
### 2. 本地开发
```bash
# 后端
cd backend
npm install # 或 pip install
npm run dev
# 前端
cd frontend
npm install
npm run dev
# 移动端
cd mobile
npm install
npm start
```
### 3. 测试
```bash
# 后端测试
cd backend
npm run test
npm run test:coverage
# 前端测试
cd frontend
npm run test
npm run test:e2e
# 移动测试
cd mobile
npm run test
npm run test:e2e
```
### 4. 提交代码
```bash
# 检查代码风格
npm run lint
npm run lint:fix
# 提交
git add .
git commit -m "feat(scope): description"
```
### 5. 推送和创建 PR
```bash
# 推送到远程
git push origin feature/your-feature
# 在 GitHub 创建 PR
# 1. 访问 GitHub
# 2. 点击 "New Pull Request"
# 3. 选择 base: main, compare: feature/your-feature
# 4. 填写 PR 标题和描述
```
## 📦 环境设置
### 前置条件
| 工具 | 版本 | 说明 |
|-----|------|------|
| Node.js | 18+ | JavaScript 运行时 |
| Python | 3.9+ | 后端（如果使用） |
| Docker | 24+ | 容器化 |
| PostgreSQL | 14+ | 数据库 |
| Redis | 7+ | 缓存 |
### 快速设置
详见各端的设置指南：
- [后端设置](03-backend/01-setup.md)
- [前端设置](04-frontend/01-setup.md)
- [移动设置](05-mobile/01-setup.md)
## 🐛 调试
### 后端调试
```bash
# 启用调试模式
DEBUG=* npm run dev
# 使用 debugger
node --inspect backend/server.js
# 访问 chrome://inspect
```
### 前端调试
```bash
# React DevTools 浏览器扩展
# Redux DevTools 扩展
# 控制台日志
console.log()
console.table()
```
### 移动调试
```bash
# React Native Debugger
npm install -g react-native-debugger
# Xcode Debugger（iOS）
# Android Studio Debugger（Android）
```
详见：[调试指南](11-guides/02-debugging.md)
## 🧪 测试工作流
### 单元测试
```bash
# 运行所有测试
npm run test
# 监视模式
npm run test:watch
# 覆盖率报告
npm run test:coverage
```
### 集成测试
```bash
# 启动测试服务
npm run test:integration
```
### 端到端测试
```bash
# 启动应用
npm run dev
# 运行 E2E 测试
npm run test:e2e
```
## 📝 编码规范
### 前端
- [代码风格](10-standards/01-code-style.md#前端)
- [命名规范](10-standards/02-naming-conventions.md#前端)
- 使用 ESLint + Prettier
### 后端
- [代码风格](10-standards/01-code-style.md#后端)
- [命名规范](10-standards/02-naming-conventions.md#后端)
- 使用 Linter（ESLint/Pylint）
### 移动端
- [代码风格](10-standards/01-code-style.md#移动端)
- [命名规范](10-standards/02-naming-conventions.md#移动端)
### 自动修复
```bash
# 格式化代码
npm run lint:fix
# 自动修复所有端
npm run lint:fix:all
```
## 🔀 Git 工作流
### 分支命名规范
```
feature/描述 # 新功能
fix/issue-number # 错误修复
refactor/描述 # 代码重构
docs/描述 # 文档改进
perf/描述 # 性能优化
test/描述 # 测试相关
```
### 提交信息规范
```
<type>(<scope>): <subject>
<body>
<footer>
```
详见：[Commit 信息规范](10-standards/04-commit-messages.md)
### 处理冲突
```bash
# 更新分支
git fetch origin
git rebase origin/main
# 解决冲突
# 编辑冲突文件
# 标记为已解决
git add .
git rebase --continue
# 推送
git push origin feature/your-feature -f
```
## 📊 性能检查
### 页面加载性能
```bash
# 前端性能分析
npm run analyze
# Lighthouse 检查
npm run lighthouse
```
### API 性能
```bash
# 后端性能测试
npm run test:performance
# 数据库查询分析
EXPLAIN ANALYZE SELECT ...;
```
### 内存使用
```bash
# 监控内存
node --max-old-space-size=4096 server.js
# 堆快照
node --inspect server.js
# 访问 chrome://inspect
```
详见：[性能优化](11-guides/03-performance-tuning.md)
## 🔒 安全检查
### 依赖安全
```bash
# 检查已知漏洞
npm audit
npm audit fix
# 定期更新
npm update
```
### 代码安全
```bash
# 安全扫描（如果配置）
npm run security:scan
```
详见：[安全检查清单](11-guides/04-security-checklist.md)
## 📚 常用命令
| 命令 | 说明 |
|-----|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm run test` | 运行测试 |
| `npm run lint` | 代码检查 |
| `npm run lint:fix` | 自动修复 |
| `npm run type-check` | TypeScript 检查 |
| `npm run format` | 代码格式化 |
## 🆘 常见问题
详见：[常见任务指南](11-guides/01-common-tasks.md)
## 📖 相关文档
- [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南
- [Git 工作流](10-standards/03-git-workflow.md)
- [编码规范](10-standards/01-code-style.md)
- [测试指南](03-backend/09-testing.md)
---
**新手提示：** 如果你是第一次贡献，请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [快速开始](01-getting-started/04-quick-start.md)。

156
开发者文档/07-协作规范/03-文档回补触发清单.md Normal file
View File

@@ -0,0 +1,156 @@
# 03-文档回补触发清单
本文档定义代码变更后必须同步更新的文档范围。开发人员完成代码提交后，必须按此清单检查并更新对应文档。**代码与文档不同步，视为提交不完整。**
---
## 一、触发条件与对应文档
### 1.1 接口变更
**触发条件：**
- 新增 Controller 方法
- 修改接口路径、请求参数、响应结构
- 删除或废弃接口
**必须更新的文档：**
- [ ] 后端代码 Swagger 注解（即时）
- [ ] 前端/移动端 API 封装层（即时）
- [ ] 如影响业务状态流：`02-Ops领域/` 或 `03-IoT领域/` 对应文档（24h 内）
**更新示例：**
```java
// 新增接口必须加 Swagger 注解
@Operation(summary = "保洁员批量接单", description = "支持一次确认多个待派单")
@PostMapping("/batch-accept")
public Result<Void> batchAccept(@RequestBody @Valid CleanerBatchAcceptReqVO reqVO) {
// ...
}
```
---
### 1.2 业务状态机变更
**触发条件：**
- 新增/修改/删除业务状态（如工单状态、设备状态）
- 状态流转规则变化
- 状态触发条件变化
**必须更新的文档：**
- [ ] `02-Ops领域/` 或 `03-IoT领域/` 对应的状态机文档（即时）
- [ ] 如影响前端展示：`04-前端开发/` 或 `05-移动端开发/` 相关页面说明（24h 内）
**重要提醒：**
状态机是业务核心，变更必须同步更新 Mermaid 状态图和文字说明。昨天我们刚修正了"手机 GPS 打卡"的错误描述，改为"工牌蓝牙信标自动触发"。
---
### 1.3 调度与队列逻辑变更
**触发条件：**
- 派单算法调整
- 队列排序规则变化
- 抢占/暂停逻辑变化
**必须更新的文档：**
- [ ] `02-Ops领域/` 派单与队列文档（即时）
- [ ] 如影响移动端交互：`05-移动端开发/` 接单流程说明（24h 内）
---
### 1.4 新增外部依赖或中间件
**触发条件：**
- 引入新的 Maven/Gradle 依赖
- 新增中间件（Redis、ES、MQ 等）
- 数据库表结构重大变更
**必须更新的文档：**
- [ ] `06-平台支撑/` 环境搭建指南（即时）
- [ ] `00-导航与总览/README.md` 架构依赖说明（24h 内）
- [ ] 在团队群内通报表结构变更（即时）
---
### 1.5 设备接入与物模型变更
**触发条件：**
- 新增设备类型
- 修改物模型定义
- 变更设备控制指令
- 调整设备数据上报格式
**必须更新的文档：**
- [ ] `03-IoT领域/` 物模型文档（即时）
- [ ] `03-IoT领域/` 设备接入协议文档（即时）
- [ ] 如影响控制链路：联动规则文档（24h 内）
---
### 1.6 前端/移动端页面或交互变更
**触发条件：**
- 新增页面或大幅调整页面结构
- 修改关键交互流程
- 调整权限控制点
**必须更新的文档：**
- [ ] `04-前端开发/` 或 `05-移动端开发/` 对应模块文档（24h 内）
- [ ] 如影响业务闭环：对应业务域文档（如 `02-Ops领域/`）
---
### 1.7 核心算法或定责逻辑变更
**触发条件：**
- 修改巡检定责算法
- 调整工时计算规则
- 变更评分/评级逻辑
**必须更新的文档：**
- [ ] `02-Ops领域/` 对应算法文档（即时）
- [ ] 在团队群内同步算法变更（即时）
---
## 二、文档回补检查清单
提交代码前，在 PR 描述中勾选以下检查项：
```markdown
## 文档回补检查
- [ ] 接口变更已更新 Swagger 注解
- [ ] 状态机变更已更新业务域文档
- [ ] 新增依赖已更新环境搭建指南
- [ ] 表结构变更已在群内通报
- [ ] 前端/移动端变更已更新对应开发文档
- [ ] 算法变更已同步团队
```
---
## 三、不回补文档的后果
1. **Code Review 不通过**：Reviewer 发现文档未同步，直接打回
2. **技术债务累积**：后续开发人员依据过期文档开发，引发连锁 Bug
3. **项目知识流失**：人员变动后，无人知晓真实逻辑
---
## 四、文档更新优先级
| 优先级 | 文档类型 | 更新时限 |
|--------|---------|---------|
| P0 | Swagger 注解、状态机图、物模型定义 | 即时（同 PR） |
| P1 | 业务域文档、开发文档 | 24h 内 |
| P2 | 架构说明、环境指南 | 本周内 |
---
## 五、相关文档
- [01-代码仓协作边界.md](./01-代码仓协作边界.md) - 代码归属与问题排查
- [02-开发工作流与 Git 规约.md](./02-开发工作流与-Git-规约.md) - 提交与分支规范
- [04-代码评审与提测标准.md](./04-代码评审与提测标准.md) - Review 检查项

171
开发者文档/07-协作规范/04-代码评审与提测标准.md Normal file
View File

@@ -0,0 +1,171 @@
# 04-代码评审与提测标准
本文档定义 Code Review 的检查项和提测前必须满足的条件。Reviewer 和 QA 以此为准绳，不达到标准禁止合并和提测。
---
## 一、Code Review 检查项
### 1.1 功能正确性
| 检查项 | 通过标准 |
|--------|---------|
| 需求对齐 | 代码实现与需求文档一致，无偏离 |
| 边界处理 | 空值、越界、异常输入都有处理 |
| 状态流转 | 业务状态变更符合设计，无非法跳转 |
| 并发安全 | 共享资源访问有锁或原子操作保护 |
### 1.2 代码质量
| 检查项 | 通过标准 |
|--------|---------|
| 命名规范 | 类名、方法名、变量名见名知意，符合团队约定 |
| 代码重复 | 无重复代码，复用已有工具类或抽取公共方法 |
| 方法长度 | 单个方法不超过 50 行（特殊情况需注释说明） |
| 圈复杂度 | 单个方法不超过 10（switch/case 除外） |
| 注释完整 | 复杂逻辑有注释，公共方法有 JavaDoc |
### 1.3 性能与资源
| 检查项 | 通过标准 |
|--------|---------|
| SQL 优化 | 无 N+1 查询，复杂查询有索引支持 |
| 内存泄漏 | 无未关闭的资源（流、连接等） |
| 循环效率 | 无在循环内重复查询数据库或调用远程接口 |
| 大数据量 | 列表查询有分页，批量操作有数量限制 |
### 1.4 安全与合规
| 检查项 | 通过标准 |
|--------|---------|
| 注入防护 | SQL 使用参数化查询，无字符串拼接 |
| 敏感信息 | 无硬编码密码、密钥，配置外置 |
| 权限控制 | 敏感操作有权限校验，接口有注解 |
| 日志脱敏 | 日志中无手机号、身份证号等敏感信息 |
### 1.5 测试覆盖
| 检查项 | 通过标准 |
|--------|---------|
| 单元测试 | 核心业务逻辑有单元测试 |
| 测试通过 | 本地运行 `mvn test` 或 `npm test` 全绿 |
| 边界测试 | 单元测试包含正常、异常、边界场景 |
---
## 二、Review 评论规范
### 2.1 评论分级
| 级别 | 标记 | 含义 | 处理方式 |
|------|------|------|---------|
| Blocker | 🔴 | 必须修复，否则不能合并 | 修复后重新 Review |
| Major | 🟡 | 建议修复，影响代码质量 | 修复后确认即可 |
| Minor | 🟢 | 小问题，可选修复 | 作者决定 |
| Question | ❓ | 疑问，需要作者解释 | 解释清楚即可 |
| NIT | 💬 | 吹毛求疵，可忽略 | 可选 |
### 2.2 评论示例
```
🔴 Blocker: 这里存在 SQL 注入风险，必须使用参数化查询。
🟡 Major: 建议将这段逻辑抽取到单独的 Service 方法中，提高可测试性。
🟢 Minor: 变量名 `a` 不够清晰，建议改为 `orderCount`。
❓ Question: 这里的超时时间是 30 秒，是基于什么考虑？业务场景允许这么久吗？
💬 NIT: 这行可以链式调用，不用拆成两行。
```
---
## 三、提测标准
### 3.1 提测前自检清单
开发人员在提测前必须完成以下检查：
```markdown
## 提测自检清单
### 功能
- [ ] 需求功能点全部实现
- [ ] 本地自测通过（主流程至少跑通 3 遍）
- [ ] 边界场景已验证（空值、极限值、异常输入）
- [ ] 并发场景已验证（如有）
### 代码
- [ ] Code Review 通过（至少 1 个 Approve）
- [ ] CI 检查通过（编译、单元测试、代码规范）
- [ ] 无编译警告（或已确认可忽略）
### 文档
- [ ] 接口 Swagger 已更新
- [ ] 业务文档已同步（如影响状态机、算法）
- [ ] 数据库变更已在群内通报
### 联调
- [ ] 与前端/移动端已联调通过（如涉及接口变更）
- [ ] 环境配置已同步（如新增依赖、配置项）
```
### 3.2 提测流程
1. 开发完成 → 本地自检 → 提交 PR
2. Code Review → 修改 → Review 通过
3. 合并到 `develop` → 部署测试环境
4. 在群里发送提测通知：
```
【提测】保洁单批量派单功能
- 分支：feature/batch-dispatch
- 已合并到 develop
- 测试环境：http://test-aiot.xxx.com
- 测试账号：cleaner001 / 123456
- 涉及文档：02-Ops领域/派单流程.md
```
---
## 四、禁止提测的情况
以下情况 QA 有权直接打回：
1. **主流程跑不通**：最基本的功能都无法使用
2. **明显 Bug**：一眼就能看出的问题未修复
3. **文档未同步**：接口或状态变更未更新文档
4. **环境未就绪**：依赖服务未部署或配置错误
5. **无测试数据**：未提供测试账号、测试数据
---
## 五、Review 与提测的协作原则
### 5.1 开发者责任
- 提交前自己先 Review 一遍（站在 Reviewer 角度）
- 回复所有评论，即使是 Minor 或 NIT
- 不辩解，先理解 Reviewer 的意图
- 大改动提前沟通，避免 Review 时才发现方向错误
### 5.2 Reviewer 责任
- 24h 内响应 Review 请求（紧急可当面找）
- 评论要具体，指出问题 + 建议方案
- 区分 Blocker 和 Minor，不要所有问题都卡
- 认可好的代码，不吝赞美
### 5.3 QA 责任
- 按提测清单验收，不达到标准不开始测试
- 测试中发现问题及时反馈，附带复现步骤
- 回归测试确保修复不引入新问题
---
## 六、相关文档
- [01-代码仓协作边界.md](./01-代码仓协作边界.md) - 代码归属与问题排查
- [02-开发工作流与 Git 规约.md](./02-开发工作流与-Git-规约.md) - 提交与分支规范
- [03-文档回补触发清单.md](./03-文档回补触发清单.md) - 变更后必须同步的文档