书籍模块

server/.ai-specs/doc-api/admin/book_author_relation.md

@@ -1,29 +1,180 @@
-# 书籍作者关系 admin 接口
+# 书籍作者关系 admin 接口
 
 ## 基本信息
 
 - 模块：book
 - 资源：书籍作者关系
 - 端：admin
-- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
-- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
-- 路由前缀：`/book`
+- 鉴权：`PrivateGroup`，需要 `JWT + Casbin`
+- 审计：创建、更新、单删、批量删除启用 `OperationRecord`
+- 前缀：`/book`
+- 实体模型：`book.BookAuthorRelation`
+- 搜索入参：`bookReq.BookAuthorRelationSearch`
+- 详情响应：`bookRes.BookAuthorRelationResponse`
+- 列表项：`bookRes.BookAuthorRelationListItem`
+- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
+- 删除策略：硬删
 
-## 默认 CRUD
+## CRUD
 
-| 动作 | Method | 路径 | API 方法 | Service 方法 |
-|:---|:---|:---|:---|:---|
-| 创建 | `POST` | `/book/createBookAuthorRelation` | `CreateBookAuthorRelation` | `CreateBookAuthorRelation` |
-| 单删 | `DELETE` | `/book/deleteBookAuthorRelation` | `DeleteBookAuthorRelation` | `DeleteBookAuthorRelation` |
-| 批量删除 | `DELETE` | `/book/deleteBookAuthorRelationByIds` | `DeleteBookAuthorRelationByIds` | `DeleteBookAuthorRelationByIds` |
-| 更新 | `PUT` | `/book/updateBookAuthorRelation` | `UpdateBookAuthorRelation` | `UpdateBookAuthorRelation` |
-| 详情 | `GET` | `/book/findBookAuthorRelation` | `FindBookAuthorRelation` | `GetBookAuthorRelation` |
-| 分页列表 | `GET` | `/book/getBookAuthorRelationList` | `GetBookAuthorRelationList` | `GetBookAuthorRelationInfoList` |
+### 创建书籍作者关系
 
-## 参数与返回
+- Method：`POST`
+- Path：`/book/createBookAuthorRelation`
+- Handler：`BookAuthorRelationApi.CreateBookAuthorRelation`
+- Service：`BookAuthorRelationService.CreateBookAuthorRelation`
+- 审计：是
 
-- 创建、更新：`body` 使用 `book.BookAuthorRelation`。
-- 单删、详情：`query id`。
-- 批量删除：`query ids[]`。
-- 分页列表：`query` 使用 `bookReq.BookAuthorRelationSearch`，返回 `response.PageResult`。
-- 详情返回：`bookRes.BookAuthorRelationResponse`。
+#### Request Body `book.BookAuthorRelation`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| bookId | uint | 是 | `> 0` | 关联书籍 ID |
+| authorId | uint | 是 | `> 0` | 关联作者 ID |
+| authorSort | int | 否 | 未传或为 `0` 时默认 `1`；最终值必须 `> 0` | 展示顺序 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 创建请求禁止传 `id/createdAt/updatedAt`。
+- 创建前必须校验 `bookId + authorId` 未被占用。
+
+### 删除书籍作者关系
+
+- Method：`DELETE`
+- Path：`/book/deleteBookAuthorRelation`
+- Handler：`BookAuthorRelationApi.DeleteBookAuthorRelation`
+- Service：`BookAuthorRelationService.DeleteBookAuthorRelation`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 关系 ID |
+
+#### Response
+
+- `response.Response{msg}`
+
+### 批量删除书籍作者关系
+
+- Method：`DELETE`
+- Path：`/book/deleteBookAuthorRelationByIds`
+- Handler：`BookAuthorRelationApi.DeleteBookAuthorRelationByIds`
+- Service：`BookAuthorRelationService.DeleteBookAuthorRelationByIds`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| ids | int[] | 二选一 | 非空，元素均 `> 0` | 关系 ID 数组 |
+| ids[] | int[] | 二选一 | 非空，元素均 `> 0` | 关系 ID 数组，兼容数组写法 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- `ids` 与 `ids[]` 二选一。
+
+### 更新书籍作者关系
+
+- Method：`PUT`
+- Path：`/book/updateBookAuthorRelation`
+- Handler：`BookAuthorRelationApi.UpdateBookAuthorRelation`
+- Service：`BookAuthorRelationService.UpdateBookAuthorRelation`
+- 审计：是
+
+#### Request Body `book.BookAuthorRelation`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | uint | 是 | `> 0` | 关系 ID |
+| bookId | uint | 是 | `> 0` | 关联书籍 ID |
+| authorId | uint | 是 | `> 0` | 关联作者 ID |
+| authorSort | int | 是 | `> 0` | 展示顺序 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 更新请求禁止传 `createdAt/updatedAt`。
+- 更新前必须校验 `bookId + authorId` 未被其他记录占用。
+- 更新为实体全量保存，前端应传完整可编辑实体，避免字段被零值覆盖。
+
+### 查询书籍作者关系详情
+
+- Method：`GET`
+- Path：`/book/findBookAuthorRelation`
+- Handler：`BookAuthorRelationApi.FindBookAuthorRelation`
+- Service：`BookAuthorRelationService.GetBookAuthorRelation`
+- 审计：否
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 关系 ID |
+
+#### Response `bookRes.BookAuthorRelationResponse`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| bookAuthorRelation | object | 关系实体 |
+| bookAuthorRelation.id | uint | 关系 ID |
+| bookAuthorRelation.bookId | uint | 书籍 ID |
+| bookAuthorRelation.authorId | uint | 作者 ID |
+| bookAuthorRelation.authorSort | int | 作者展示顺序 |
+| bookAuthorRelation.createdAt | string | 创建时间 |
+| bookAuthorRelation.updatedAt | string | 更新时间 |
+
+### 分页查询书籍作者关系列表
+
+- Method：`GET`
+- Path：`/book/getBookAuthorRelationList`
+- Handler：`BookAuthorRelationApi.GetBookAuthorRelationList`
+- Service：`BookAuthorRelationService.GetBookAuthorRelationInfoList`
+- 审计：否
+
+#### Request Query `bookReq.BookAuthorRelationSearch`
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
+| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
+| bookId | uint | 否 | `> 0` | 按书籍 ID 精确筛选 |
+| authorId | uint | 否 | `> 0` | 按作者 ID 精确筛选 |
+
+#### Response `response.PageResult`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| list | array | `bookRes.BookAuthorRelationListItem` 列表 |
+| list[].id | uint | 关系 ID |
+| list[].bookId | uint | 书籍 ID |
+| list[].authorId | uint | 作者 ID |
+| list[].authorSort | int | 作者展示顺序 |
+| list[].authorName | string | 作者名称展示字段 |
+| total | int64 | 总数 |
+| page | int | 当前页 |
+| pageSize | int | 每页数量 |
+
+#### 规则
+
+- 列表默认排序：`bookId asc, authorSort asc, id desc`。
+
+## 规则
+
+- 默认鉴权为 `PrivateGroup`，需要 `JWT + Casbin`。
+- `bookId + authorId` 唯一，对应数据库唯一索引 `uk_book_author_relation_book_id_author_id`。
+- `authorSort` 必须大于 `0`。
+- 创建时 `authorSort` 未传或为 `0` 时默认 `1`。
+- 删除策略为硬删。