书籍模块

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

@@ -1,29 +1,194 @@
-# 书籍作者 admin 接口
+# 书籍作者 admin 接口
 
 ## 基本信息
 
 - 模块：book
-- 资源：作者
+- 资源：书籍作者
 - 端：admin
-- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
-- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
-- 路由前缀：`/book`
+- 鉴权：`PrivateGroup`，需要 `JWT + Casbin`
+- 审计：创建、更新、单删、批量删除启用 `OperationRecord`
+- 前缀：`/book`
+- 实体模型：`book.BookAuthor`
+- 搜索入参：`bookReq.BookAuthorSearch`
+- 详情响应：`bookRes.BookAuthorResponse`
+- 列表项：`bookRes.BookAuthorListItem`
+- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
+- 删除策略：硬删
 
-## 默认 CRUD
+## CRUD
 
-| 动作 | Method | 路径 | API 方法 | Service 方法 |
-|:---|:---|:---|:---|:---|
-| 创建 | `POST` | `/book/createBookAuthor` | `CreateBookAuthor` | `CreateBookAuthor` |
-| 单删 | `DELETE` | `/book/deleteBookAuthor` | `DeleteBookAuthor` | `DeleteBookAuthor` |
-| 批量删除 | `DELETE` | `/book/deleteBookAuthorByIds` | `DeleteBookAuthorByIds` | `DeleteBookAuthorByIds` |
-| 更新 | `PUT` | `/book/updateBookAuthor` | `UpdateBookAuthor` | `UpdateBookAuthor` |
-| 详情 | `GET` | `/book/findBookAuthor` | `FindBookAuthor` | `GetBookAuthor` |
-| 分页列表 | `GET` | `/book/getBookAuthorList` | `GetBookAuthorList` | `GetBookAuthorInfoList` |
+### 创建书籍作者
 
-## 参数与返回
+- Method：`POST`
+- Path：`/book/createBookAuthor`
+- Handler：`BookAuthorApi.CreateBookAuthor`
+- Service：`BookAuthorService.CreateBookAuthor`
+- 审计：是
 
-- 创建、更新：`body` 使用 `book.BookAuthor`。
-- 单删、详情：`query id`。
-- 批量删除：`query ids[]`。
-- 分页列表：`query` 使用 `bookReq.BookAuthorSearch`，返回 `response.PageResult`。
-- 详情返回：`bookRes.BookAuthorResponse`。
+#### Request Body `book.BookAuthor`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| name | string | 是 | 非空，最大 `128` 字符，唯一 | 作者名称 |
+| authorStatus | string | 否 | `common_enabled_status`：`enabled`/`disabled`；默认 `enabled` | 作者启用状态 |
+| intro | string | 否 | 可为空 | 作者简介 |
+| coverUrl | string | 否 | 可为空，最大 `500` 字符 | 作者头像或封面 URL |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
+- `name` 必须唯一，对应唯一索引 `uk_book_author_name`。
+- `authorStatus` 为空时按数据库默认值 `enabled` 落库；传值时必须符合 `common_enabled_status`。
+
+### 删除书籍作者
+
+- Method：`DELETE`
+- Path：`/book/deleteBookAuthor`
+- Handler：`BookAuthorApi.DeleteBookAuthor`
+- Service：`BookAuthorService.DeleteBookAuthor`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 作者 ID |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 删除策略为硬删。
+
+### 批量删除书籍作者
+
+- Method：`DELETE`
+- Path：`/book/deleteBookAuthorByIds`
+- Handler：`BookAuthorApi.DeleteBookAuthorByIds`
+- Service：`BookAuthorService.DeleteBookAuthorByIds`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| ids | int[] | 二选一 | 非空，元素均 `> 0` | 作者 ID 数组 |
+| ids[] | int[] | 二选一 | 非空，元素均 `> 0` | 作者 ID 数组，兼容数组写法 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- `ids` 与 `ids[]` 二选一。
+- 删除策略为硬删。
+
+### 更新书籍作者
+
+- Method：`PUT`
+- Path：`/book/updateBookAuthor`
+- Handler：`BookAuthorApi.UpdateBookAuthor`
+- Service：`BookAuthorService.UpdateBookAuthor`
+- 审计：是
+
+#### Request Body `book.BookAuthor`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | uint | 是 | `> 0` | 作者 ID |
+| name | string | 是 | 非空，最大 `128` 字符，唯一 | 作者名称 |
+| authorStatus | string | 否 | `common_enabled_status`：`enabled`/`disabled` | 作者启用状态 |
+| intro | string | 否 | 可为空 | 作者简介 |
+| coverUrl | string | 否 | 可为空，最大 `500` 字符 | 作者头像或封面 URL |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
+- 更新为实体全量保存，前端应传完整可编辑实体，避免字段被零值覆盖。
+- `name` 必须唯一，对应唯一索引 `uk_book_author_name`。
+- `authorStatus` 为空时会按空值保存；传值时必须符合 `common_enabled_status`。
+
+### 查询书籍作者详情
+
+- Method：`GET`
+- Path：`/book/findBookAuthor`
+- Handler：`BookAuthorApi.FindBookAuthor`
+- Service：`BookAuthorService.GetBookAuthor`
+- 审计：否
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 作者 ID |
+
+#### Response `bookRes.BookAuthorResponse`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| bookAuthor | object | 作者实体 |
+| bookAuthor.id | uint | 作者 ID |
+| bookAuthor.createdAt | time | 创建时间 |
+| bookAuthor.updatedAt | time | 更新时间 |
+| bookAuthor.name | string | 作者名称 |
+| bookAuthor.authorStatus | string | 作者启用状态，见 `common_enabled_status` |
+| bookAuthor.intro | string | 作者简介 |
+| bookAuthor.coverUrl | string | 作者头像或封面 URL |
+
+### 分页查询书籍作者列表
+
+- Method：`GET`
+- Path：`/book/getBookAuthorList`
+- Handler：`BookAuthorApi.GetBookAuthorList`
+- Service：`BookAuthorService.GetBookAuthorInfoList`
+- 审计：否
+
+#### Request Query `bookReq.BookAuthorSearch`
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
+| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
+| keyword | string | 否 | 模糊匹配 `name` | 通用关键字 |
+| name | string | 否 | 模糊匹配 `name` | 作者名称 |
+| authorStatus | string | 否 | `common_enabled_status`：`enabled`/`disabled` | 作者启用状态 |
+
+#### Response `response.PageResult`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| list | array | `bookRes.BookAuthorListItem` 列表 |
+| list[].id | uint | 作者 ID |
+| list[].createdAt | time | 创建时间 |
+| list[].updatedAt | time | 更新时间 |
+| list[].name | string | 作者名称 |
+| list[].authorStatus | string | 作者启用状态，见 `common_enabled_status` |
+| list[].intro | string | 作者简介 |
+| list[].coverUrl | string | 作者头像或封面 URL |
+| list[].authorName | string | 作者名称展示字段，来源于 `book_author.name AS author_name` |
+| total | int64 | 总数 |
+| page | int | 当前页 |
+| pageSize | int | 每页数量 |
+
+#### 规则
+
+- 列表默认排序：`id desc`。
+- `keyword` 与 `name` 同时传入时，会叠加为两个 `name LIKE` 条件。
+
+## 规则
+
+- admin 端书籍作者 CRUD 挂载到 `PrivateGroup`，需要 `JWT + Casbin`。
+- 写操作挂载 `middleware.OperationRecord()`；读操作不挂操作审计。
+- `authorStatus` 固定值域来自 `common_enabled_status`：`enabled`、`disabled`。
+- 表结构、字段长度、唯一约束和索引以 `.ai-specs/doc-sql/book_author.sql` 为准。