# {模块名称} - API 文档

> **module**: {模块名}
> **doc_type**: API
> **status**: Draft / Review / Active
> **owner**: {负责人}
> **upstream_docs**: 01-prd.md, 04-state-machine.md, 06-data-model.md
> **last_verified**: YYYY-MM-DD

---

## API 摘要

### 最小必填项

- Base URL: `/api/v1/<module>`
- 认证: Bearer Token (JWT)
- 错误码: [08-error-codes.md](./08-error-codes.md)

### 统一约定（如需）

- Base URL: `/api/v1/<module>`
- 认证: Bearer Token (JWT)
- 错误码: [08-error-codes.md](./08-error-codes.md)
- 统一拦截器: 成功响应由 `TransformInterceptor` 统一包装；错误响应由 `AllExceptionsFilter` 统一格式化
- 响应封装:
  - 成功: `{ "success": true, "data": {...}, "message": "success", "timestamp": "...", "path": "/api/v1/..." }`
  - 分页: `{ "success": true, "data": { items, pagination: { page, pageSize, total, totalPages } }, "timestamp": "...", "path": "/api/v1/..." }`
  - 失败: `{ "success": false, "error": { "code": "<ERROR_CODE>", "message": "<i18n.key>", "...": "..." }, "timestamp": "...", "path": "/api/v1/...", "method": "GET", "statusCode": 400 }`
- 示例说明: 示例响应默认展示完整封装；若仅展示 `data` 字段会显式标注

### 通用状态码（如需）

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 参数错误/业务校验失败 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 业务冲突（状态不允许/重复） |
| 422 | 数据校验失败 |

### API 说明

- 覆盖模块全链路接口（与 UI/状态机/数据模型一致）
- 所有接口返回统一封装格式（见“统一约定”）
- 变更接口需同步更新错误码文档与测试场景

### 接口数量汇总

- 总计: <N> 个接口
- 统计口径: 下方“接口清单（按域）”中的全部路径

---

## 接口清单（按域）

### 1) <域名>（<N>）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 001 | GET | /<path> | <角色> |

---

## 数据结构定义（字段级）

> 说明：所有请求/响应类型必须在本节提供字段级定义。接口内的 `请求 Body/Query/Path` 与 `响应 Data` 只能引用这里的类型名称。

### 通用响应封装（如需）

#### SuccessResponse<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 true |
| data | T | ✅ | 业务数据 |
| message | String | ✅ | 提示信息，默认 `success` |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |

#### ErrorResponse

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 false |
| error.code | String | ✅ | 错误码（与 08-error-codes 一致） |
| error.message | String | ✅ | i18n key 或可读信息 |
| error.details | JSON | ❌ | 额外上下文 |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |
| method | String | ✅ | HTTP 方法 |
| statusCode | Int | ✅ | HTTP 状态码 |

### 通用列表与分页（如需）

#### PageResult<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | T[] | ✅ | 列表数据 |
| pagination | Pagination | ✅ | 分页信息 |

#### Pagination

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Int | ✅ | 页码（从 1 开始） |
| pageSize | Int | ✅ | 每页数量 |
| total | Int | ✅ | 总数 |
| totalPages | Int | ✅ | 总页数 |

#### ListResult<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | T[] | ✅ | 不分页列表 |

### 业务实体与 DTO

> 每个业务实体/DTO 在此定义字段表，字段类型与必填性必须与 06-data-model 或 UI 交互规范一致。

---

## 统一格式 + 简短示例

### 1) <域名>（<N>）

**[001] <METHOD> /<path>**
- 说明: <说明>
- 请求 Query: { <字段?> }
- 响应 Data: <类型/结构>
- 示例请求: `<METHOD> /<path>?<query>`
- 示例响应: `{ "success": true, "data": { ... }, "message": "success", "timestamp": "YYYY-MM-DDTHH:mm:ssZ", "path": "/api/v1/<module>/<path>" }`
- 状态码: 200, 401, 403