# HTTP 调试与文档规范

本目录下的 `.http` 文件同时承担接口调试和接口文档职责，也要保证 AIAgent 能稳定读取

## 目录分工

### `.http`

`.http` 只描述接口级信息：

1. 接口中文名
2. 权限要求
3. 前置条件
4. 请求参数对应的对象说明
5. 返回参数对应的对象说明

`.http` 不重复展开对象字段明细，复杂字段、嵌套结构、枚举值统一写到 `./object` 下

### `./object`

`./object` 只描述对象级信息：

1. 字段名
2. 字段类型
3. 字段说明
4. 枚举值及含义

所有模块都可能复用的通用对象必须写在 `./object/common.md`

按业务领域拆分对象说明文件，例如：

1. `./object/common.md`
2. `./object/user.md`
3. `./object/role.md`
4. `./object/permission.md`

不要把同一个对象的字段说明散落到多个文件里

## 全局约定

### 返回包装

除使用 `IgnoreGlobalReturn` 跳过全局包装的方法外，接口默认都会经过
[GlobalReturnHandler](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java)
统一包装返回

因此 `.http` 里的 `返回参数` 默认只描述业务 `data` 对象，不再重复赘述全局包装结构

全局返回包装、通用成功码、错误信息、常见分页壳子等内容统一维护在 `./object/common.md`

如果接口使用
[IgnoreGlobalReturn](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/annotation/IgnoreGlobalReturn.java)
跳过全局包装，必须在对应接口的 `前置条件` 或补充说明里明确写出“该接口不走全局返回包装”

### 文档真实性

1. 文档只记录服务端真实行为
2. 不写猜测
3. 不写“看代码”
4. 接口改了就同步更新 `.http` 和 `./object`

### 变量复用

能复用的变量统一放在文件顶部，例如 `@user_token`、`@userId`

## `.http` 模板

每个接口块固定使用下面格式，不要擅自增删字段名：

```http
### <接口中文名>
### 权限：
### 前置条件：
### 请求参数：
### 返回参数：

POST {{baseUrl}}/path
Content-Type: application/json
Token: {{user_token}}

{}
```

## `.http` 填写要求

### 接口中文名

直接写接口用途，别写成控制器方法名

### 权限

1. 优先直接翻译控制器上的真实注解
2. 同时存在角色和权限时一起写，例如 `需要 ADMIN 角色 + USER_UPDATE 权限`
3. 只有 Token 要求时写 `需要有效 Token`
4. 无需登录时直接写 `无需登录`

### 前置条件

这里只写接口调用前必须知道的约束，例如：

1. 需要先登录并回填 `user_token`
2. 需要先创建用户再传入 `userId`
3. 重复调用可能因为唯一约束失败
4. 接口当前实现为空
5. 该接口不走全局返回包装

没有额外限制时写 `无`

### 请求参数

只写请求对象名和对象说明文件，不在 `.http` 内展开字段

推荐格式：

1. `无`
2. `UserCreateRequest，详见 ./object/user.md`
3. `Page<UserQuery>，详见 ./object/common.md 和 ./object/user.md`

### 返回参数

只写业务返回对象名和对象说明文件，不在 `.http` 内展开字段

推荐格式：

1. `无`
2. `User，详见 ./object/user.md`
3. `PageResult<User>，详见 ./object/common.md 和 ./object/user.md`
4. `二进制数据流，该接口不走全局返回包装`

## `./object` 编写要求

对象说明统一使用 Markdown 表格，推荐结构如下

```md
## User

| 字段 | 类型 | 说明 |
|---|---|---|
| name | String | 登录名，系统内唯一 |

## RoleCode

| 枚举 | 说明 |
|---|---|
| SYSTEM | 系统 |
| ADMIN | 管理员 |
```

### 对象说明规则

1. 一个对象一个标题，标题名必须和 `.http` 里引用的对象名一致
2. 字段说明只写真实存在且调用方需要关心的内容
3. 枚举单独列出，不要把枚举值混进普通字段表
4. 嵌套对象、列表元素对象也要有独立标题
5. 通用壳子对象统一写在 `./object/common.md`

## 维护要求

1. 一个控制器通常对应一个 `.http` 文件
2. 新增接口时，同步补齐对应 `.http`
3. 新增或修改对象字段时，同步更新对应 `./object/*.md`
4. 注释语言统一用中文
5. 示例请求优先保证可调试，其次才是看起来完整