书籍模块

2026-04-27 10:12:21 +08:00
parent 1e33640629
commit 13db6e89f0
33 changed files with 8820 additions and 738 deletions
--- a/server/.ai-specs/sys-specs/doc-api-doc-spec.md
+++ b/server/.ai-specs/sys-specs/doc-api-doc-spec.md
@@ -0,0 +1,240 @@
+# 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` 字段、额外展示字段。
+- 字段规则：取 `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`。