# 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` 标识业务状态。

```json
{
  "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**:
    ```json
    {
      "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}`
*   **Body**:
    ```json
    {
      "type": "REPAIR",
      "deviceId": 10001,
      "desc": "空调异响，需检查风扇",
      "priority": 2
    }
    ```