Part 7: 接口文档

文档定位：明确前后端交互的接口标准 (RESTful API)，介绍 API 文档的自动生成与聚合访问方式，以及网关层的路由转发规则。

7.1 RESTful API 规范

平台所有 HTTP 接口严格遵循 RESTful 设计风格，HTTP Status Code 与业务 Error Code 分离。

7.1.1 URL 设计

版本控制：/admin-api/system/user/v1/page
动词使用：
- GET：查询资源（幂等）
- POST：创建资源（非幂等）
- PUT：更新资源（全量）
- DELETE：删除资源

7.1.2 响应结构

HTTP Status Code 标识网络层状态，Response Body 中的 code 标识业务状态。

{
  "code": 0,          // 0 表示成功，非 0 表示业务异常
  "msg": "success",   // 错误提示信息
  "data": {           // 业务数据
    "id": 1001,
    "username": "admin"
  }
}

7.1.3 常用错误码

Code	类型	说明
0	Success	请求成功
400	Client Error	参数校验失败
401	Unauthorized	未登录或 Token 过期
403	Forbidden	无权限访问该资源
429	Too Many Requests	请求过于频繁（触发限流）
500	Server Error	系统内部未知错误
100xxx	Biz Error	[100001] 系统模块异常
200xxx	Biz Error	[200001] IoT 模块异常

7.2 接口文档聚合 (Knife4j)

项目采用 Knife4j (Swagger 的增强版) 实现接口文档的自动生成与微服务聚合。

7.2.1 访问地址

统一入口：http://{gateway-ip}:48080/doc.html
原理：Gateway 服务集成 knife4j-gateway-spring-boot-starter，自动发现并聚合所有 Nacos 中注册的微服务 Swagger 文档。

7.2.2 开发注解规范

后端开发必须使用 Swagger 注解描述接口含义：

@Tag(name = "管理后台 - 用户管理")：标记 Controller。
@Operation(summary = "获得用户分页")：标记接口方法。
@Schema(description = "用户编号")：标记 VO/DTO 字段。

7.3 Gateway 路由规则

网关根据请求 Path 前缀将流量转发至对应的微服务。

请求前缀 (Prefix)	目标服务 (Target Service)	说明
`/admin-api/system/**`	`viewsh-module-system-server`	系统/租户/权限相关
`/admin-api/infra/**`	`viewsh-module-infra-server`	文件/定时任务相关
`/admin-api/iot/**`	`viewsh-module-iot-server`	设备管理/规则引擎
`/admin-api/ops/**`	`viewsh-module-ops-server`	运营工单/报修
`/app-api/**`	`viewsh-module-system-server`	移动端 App 接口（部分复用）

7.4 核心接口示例

7.4.1 设备遥测数据上报 (HTTP)

URL: http://{gateway}:8092/iot/device/report
Method: POST

Body:

{
  "productKey": "a1B2c3D4",
  "deviceName": "sn-0001",
  "ts": 1678888888000,
  "params": {
    "temperature": 25.6,
    "humidity": 60
  }
}

7.4.2 创建维修工单 (Admin)

URL: http://{gateway}:48080/admin-api/ops/work-order/create
Method: POST
Header: Authorization: Bearer {token}