From a1c34b4c83edfab1bc79ae804162e4531291f91c Mon Sep 17 00:00:00 2001
From: lzh <sickone075@gmail.com>
Date: Tue, 7 Apr 2026 19:55:13 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=89=A9=E5=B1=95=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E5=88=86=E5=9F=9F=E4=B8=8E=E7=BB=B4=E6=8A=A4=E5=8E=9F=E5=88=99?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 补充接口分域架构（四大核心域）
- 补充接口 URL 规范和禁止事项
- 补充 Swagger 注解规范和变更流程
- 补充版本管理策略和跨域处理原则
- 补充 Swagger UI 地址和 OpenAPI 导出
---
 .../07-API 文档/01-接口分域与维护原则.md      | 226 ++++++++++++++++++
 1 file changed, 226 insertions(+)
 create mode 100644 开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md

diff --git a/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md b/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md
new file mode 100644
index 0000000..df0320d
--- /dev/null
+++ b/开发者文档/06-平台支撑/07-API 文档/01-接口分域与维护原则.md	
@@ -0,0 +1,226 @@
+# 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)