diff --git a/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md b/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md deleted file mode 100644 index df0320d..0000000 --- a/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md +++ /dev/null @@ -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 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) diff --git a/开发者文档/06-平台支撑/09-DevOps 运维/01-部署运行与排障视角.md b/开发者文档/06-平台支撑/09-DevOps 运维/01-部署运行与排障视角.md deleted file mode 100644 index f25abc0..0000000 --- a/开发者文档/06-平台支撑/09-DevOps 运维/01-部署运行与排障视角.md +++ /dev/null @@ -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 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 --tail 100 -f - -# 进入容器调试 -docker exec -it bash - -# 重启容器 -docker restart -``` - -### 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 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 -nc -zv - -# DNS 解析 -nslookup -dig - -# 路由追踪 -traceroute -mtr -``` - ---- - -## 五、相关文档 - -- [00-支撑平台总览.md](../00-支撑平台总览.md) -- [01-统一网关入口规范.md](../01-统一网关入口规范.md) -- [02-中间件使用规约.md](../02-中间件使用规约.md) -- [02-环境部署指南.md](./02-环境部署指南.md) diff --git a/开发者文档/06-平台支撑/09-DevOps 运维/02-环境部署指南.md b/开发者文档/06-平台支撑/09-DevOps 运维/02-环境部署指南.md deleted file mode 100644 index 76e078d..0000000 --- a/开发者文档/06-平台支撑/09-DevOps 运维/02-环境部署指南.md +++ /dev/null @@ -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 中的 1.2.0 -# 修改 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) diff --git a/开发者文档/07-协作规范/01-不同项目的基本规范.md b/开发者文档/07-协作规范/01-不同项目的基本规范.md deleted file mode 100644 index 1d5093f..0000000 --- a/开发者文档/07-协作规范/01-不同项目的基本规范.md +++ /dev/null @@ -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` 格式，附带明确的业务错误码。 - -## 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..fd7dd66 --- /dev/null +++ b/开发者文档/07-协作规范/01-代码仓协作边界.md @@ -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) - 提交与分支规范 diff --git a/开发者文档/07-协作规范/01-需求开发与文档回补流程.md b/开发者文档/07-协作规范/01-需求开发与文档回补流程.md deleted file mode 100644 index 3ae4562..0000000 --- a/开发者文档/07-协作规范/01-需求开发与文档回补流程.md +++ /dev/null @@ -1,30 +0,0 @@ -# 🧪 需求开发与文档回补流程 - -这篇文档只定义一个实用流程：需求来了以后，开发和文档怎么同步推进。 - -## 1. 先定位业务域 - -- system -- infra -- iot -- ops - -## 2. 再定位是否影响状态流 - -如果需求涉及： - -- 工单 -- 派单 -- 设备规则 -- 联动触发 - -那就必须先确认状态流和事件流。 - -## 3. 开发后需要回补的文档 - -- 模块变更：后端模块地图 -- 状态流变更：Ops 生命周期文档 -- 调度变更：派单与队列文档 -- 规则变更：IoT 规则文档 -- 联动变更：IoT 与 Ops 联动文档 - diff --git a/开发者文档/07-协作规范/01-项目编码与文档规范.md b/开发者文档/07-协作规范/01-项目编码与文档规范.md deleted file mode 100644 index 6d46769..0000000 --- a/开发者文档/07-协作规范/01-项目编码与文档规范.md +++ /dev/null @@ -1,23 +0,0 @@ -# ✍️ 项目编码与文档规范 - -这里只记录当前最值得长期保持一致的约定。 - -## 1. 后端 - -- 模块边界优先于临时方便 -- 领域逻辑不直接写进 Controller -- 共性技术能力优先沉淀到 `framework` -- 条线差异优先放对应 `*-biz` - -## 2. 前端与移动端 - -- 页面层与共享层分离 -- 类型与 API 封装同步演进 -- 页面按业务域组织而不是随意堆叠 - -## 3. 文档 - -- 目录级 README 不作为正文 -- 先写边界，再写实现 -- 先写事实，再写建议 - diff --git a/开发者文档/07-协作规范/02-开发工作流与-Git-规约.md b/开发者文档/07-协作规范/02-开发工作流与-Git-规约.md new file mode 100644 index 0000000..45af03a --- /dev/null +++ b/开发者文档/07-协作规范/02-开发工作流与-Git-规约.md @@ -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) - 变更后必须同步的文档 diff --git a/开发者文档/07-协作规范/02-综合开发指南.md b/开发者文档/07-协作规范/02-综合开发指南.md deleted file mode 100644 index cdc5a50..0000000 --- a/开发者文档/07-协作规范/02-综合开发指南.md +++ /dev/null @@ -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/描述 # 测试相关 -``` - -### 提交信息规范 - -``` -(): - - - -