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。

文档结构

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

## 基本信息

- 模块：<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 的 ## 规则 写明。

创建

### 创建<资源>

- 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`。
- <唯一约束、默认值、引用校验等创建规则>

单删

### 删除<资源>

- 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}`

批量删除

### 批量删除<资源>

- 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[]` 二选一。

更新

### 更新<资源>

- 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`。
- <全量保存/局部更新、唯一约束、引用校验等更新规则>

详情

### 查询<资源>详情

- 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> | <字段说明> |

分页列表

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

- 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。