xuanzhi-service/server/.ai-specs/sys-specs/doc-api-doc-spec.md

# doc-api 文档规范

## 适用范围

- 新增、重建、校准 `.ai-specs/doc-api/<端>/<resource>.md` 时必读。
- 目标：即使目标 `doc-api` 为空，也能按本文稳定生成接口 contract 文档。
- `doc-api` 只写端点、`Handler`、`Service`、鉴权、审计、请求、响应、规则；表结构看 `doc-sql`，值域看 `doc-dict`，代码落点看 `coding-specs`。

## 生成输入

按顺序读取，缺失则跳过并从下一项补齐：

1. `AGENTS.md`：确认项目链路、文档索引、鉴权入口。
2. `.ai-specs/coding-specs/module-admin-crud-default.md`：确认 admin 默认 CRUD、命名、Method、Service 映射。
3. `.ai-specs/coding-specs/api-auth-control.md`：确认 `PublicGroup`、`PrivateGroup`、`JWT + Casbin` 规则。
4. `.ai-specs/coding-specs/vo-model-request-response.md`：确认实体、request、response 落点。
5. 对应 `.ai-specs/doc-sql/<resource>.sql`：确认字段、默认值、唯一约束、索引、删除策略、排序依据。
6. 对应 `.ai-specs/doc-dict/*.md`：确认状态、类型、枚举值域。
7. 源码：`router/<module>`、`api/v1/<module>`、`service/<module>`、`model/<module>`、`initialize/router_biz.go`。

## 文档结构

```md
# <资源中文名> <端> 接口

## 基本信息

- 模块：<module>
- 资源：<资源中文名>
- 端：<admin/app/平台>
- 鉴权：<PrivateGroup/PublicGroup/LoginGroup 描述>
- 审计：<启用 OperationRecord 的端点>
- 前缀：/<abbreviation>
- 实体模型：<model>
- 搜索入参：<Search request，可选>
- 详情响应：<Detail response，可选>
- 列表项：<ListItem response，可选>
- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
- 删除策略：<硬删/软删/不支持删除>

## CRUD

<按端点模板展开>

## 规则

- <资源级通用规则>
```

## admin CRUD 模板

默认 admin CRUD 必须按以下 6 个端点展开；有明确例外时，在对应 `doc-api` 的 `## 规则` 写明。

### 创建

```md
### 创建<资源>

- Method：`POST`
- Path：`/<abbreviation>/create<StructName>`
- Handler：`<StructName>Api.Create<StructName>`
- Service：`<StructName>Service.Create<StructName>`
- 审计：是

#### Request Body `<Entity 或 CreateReq>`

| 字段 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| <field> | <type> | <是/否> | <来自 doc-sql/doc-dict/代码校验> | <字段说明> |

#### Response

- `response.Response{msg}`

#### 规则

- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
- <唯一约束、默认值、引用校验等创建规则>
```

### 单删

```md
### 删除<资源>

- Method：`DELETE`
- Path：`/<abbreviation>/delete<StructName>`
- Handler：`<StructName>Api.Delete<StructName>`
- Service：`<StructName>Service.Delete<StructName>`
- 审计：是

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | int | 是 | `> 0` | 主键 ID |

#### Response

- `response.Response{msg}`
```

### 批量删除

```md
### 批量删除<资源>

- Method：`DELETE`
- Path：`/<abbreviation>/delete<StructName>ByIds`
- Handler：`<StructName>Api.Delete<StructName>ByIds`
- Service：`<StructName>Service.Delete<StructName>ByIds`
- 审计：是

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| ids | int[] | 二选一 | 非空，元素均 `> 0` | 主键 ID 数组 |
| ids[] | int[] | 二选一 | 非空，元素均 `> 0` | 主键 ID 数组，兼容数组写法 |

#### Response

- `response.Response{msg}`

#### 规则

- `ids` 与 `ids[]` 二选一。
```

### 更新

```md
### 更新<资源>

- Method：`PUT`
- Path：`/<abbreviation>/update<StructName>`
- Handler：`<StructName>Api.Update<StructName>`
- Service：`<StructName>Service.Update<StructName>`
- 审计：是

#### Request Body `<Entity 或 UpdateReq>`

| 字段 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | uint | 是 | `> 0` | 主键 ID |
| <field> | <type> | <是/否> | <来自 doc-sql/doc-dict/代码校验> | <字段说明> |

#### Response

- `response.Response{msg}`

#### 规则

- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
- <全量保存/局部更新、唯一约束、引用校验等更新规则>
```

### 详情

```md
### 查询<资源>详情

- Method：`GET`
- Path：`/<abbreviation>/find<StructName>`
- Handler：`<StructName>Api.Find<StructName>`
- Service：`<StructName>Service.Get<StructName>`
- 审计：否

#### Request Query

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| id | int | 是 | `> 0` | 主键 ID |

#### Response `<StructName>Response`

| 字段 | 类型 | 说明 |
|:---|:---|:---|
| <resource> | object | 详情实体 |
| <resource>.id | uint | 主键 ID |
| <resource>.<field> | <type> | <字段说明> |
```

### 分页列表

```md
### 分页查询<资源>列表

- Method：`GET`
- Path：`/<abbreviation>/get<StructName>List`
- Handler：`<StructName>Api.Get<StructName>List`
- Service：`<StructName>Service.Get<StructName>InfoList`
- 审计：否

#### Request Query `<StructName>Search`

| 参数 | 类型 | 必填 | 规则 | 说明 |
|:---|:---|:---:|:---|:---|
| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
| <filter> | <type> | 否 | <规则> | <筛选说明> |

#### Response `response.PageResult`

| 字段 | 类型 | 说明 |
|:---|:---|:---|
| list | array | `<ListItem>` 列表 |
| list[].id | uint | 主键 ID |
| list[].<field> | <type> | <字段说明> |
| total | int64 | 总数 |
| page | int | 当前页 |
| pageSize | int | 每页数量 |

#### 规则

- 列表默认排序：`<order by>`。
```

## 字段来源

- Body 字段：优先取 `request`；没有独立 `request` 时取实体可编辑字段。
- Query 字段：取 `request/Search`、`common.GetById`、`common.IdsReq`。
- Detail 响应：取 `response` 包装结构和实体 JSON 字段。
- List 响应：取 `ListItem`、`Select/Scan` 字段、额外展示字段。
- 关联表响应：列表默认写明关联对象展示字段；详情用于前端展示或编辑时同步写明同口径展示字段。
- 关联展示字段：来源于关联表 `JOIN`、预加载或批量查询组装；字段名使用 `<关联对象语义><Name/Title/Label>`，例如 `authorName`、`bookTitle`。
- 字段规则：取 `doc-sql` 非空/默认值/唯一索引/check，叠加 `doc-dict` 值域和 `Service` 校验。
- 字段名：使用实际 `json/form` 名称，禁止使用 Go 字段名替代。
- 端点鉴权：默认继承 `## 基本信息`；只有端点鉴权不同才在端点内单独写。
- 写操作响应：统一写 `response.Response{msg}`，不展开 `code/msg` 表格。
- 请求/响应汇总：默认不写 `## 请求字段`、`## 响应字段`；字段以端点内 `Request/Response` 为准。

## 硬性要求

- `## CRUD` 必须展开端点，禁止只写 CRUD 总表。
- 每个端点必须有自己的 `Request`、`Response`；无请求参数时保留 `Request` 小节并写 `- 无。`。
- 端点特有规则按需写在端点下；通用规则写到文末 `## 规则`。
- 请求字段表列固定为：字段/参数、类型、必填、规则、说明。
- 详情/列表响应字段表列固定为：字段、类型、说明；写操作响应简写为 `response.Response{msg}`。
- 关键响应字段必须展开，禁止写 `mixed`。
- `ids` 与 `ids[]` 必须写清二选一。
- 文档规则要求业务校验时，代码必须同步落到 `API` 或 `Service`。