书籍模块

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

@@ -1,29 +1,201 @@
-# 书籍章节 admin 接口
+# 书籍章节 admin 接口
 
 ## 基本信息
 
 - 模块：book
-- 资源：章节
+- 资源：书籍章节
 - 端：admin
-- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
-- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
-- 路由前缀：`/book`
+- 鉴权：`PrivateGroup`，需要 `JWT + Casbin`
+- 审计：创建、更新、单删、批量删除启用 `OperationRecord`
+- 前缀：`/book`
+- 实体模型：`book.BookChapter`
+- 搜索入参：`bookReq.BookChapterSearch`
+- 详情响应：`bookRes.BookChapterResponse`
+- 列表项：`book.BookChapter`
+- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
+- 删除策略：硬删
 
-## 默认 CRUD
+## CRUD
 
-| 动作 | Method | 路径 | API 方法 | Service 方法 |
-|:---|:---|:---|:---|:---|
-| 创建 | `POST` | `/book/createBookChapter` | `CreateBookChapter` | `CreateBookChapter` |
-| 单删 | `DELETE` | `/book/deleteBookChapter` | `DeleteBookChapter` | `DeleteBookChapter` |
-| 批量删除 | `DELETE` | `/book/deleteBookChapterByIds` | `DeleteBookChapterByIds` | `DeleteBookChapterByIds` |
-| 更新 | `PUT` | `/book/updateBookChapter` | `UpdateBookChapter` | `UpdateBookChapter` |
-| 详情 | `GET` | `/book/findBookChapter` | `FindBookChapter` | `GetBookChapter` |
-| 分页列表 | `GET` | `/book/getBookChapterList` | `GetBookChapterList` | `GetBookChapterInfoList` |
+### 创建书籍章节
 
-## 参数与返回
+- Method：`POST`
+- Path：`/book/createBookChapter`
+- Handler：`BookChapterApi.CreateBookChapter`
+- Service：`BookChapterService.CreateBookChapter`
+- 审计：是
 
-- 创建、更新：`body` 使用 `book.BookChapter`。
-- 单删、详情：`query id`。
-- 批量删除：`query ids[]`。
-- 分页列表：`query` 使用 `bookReq.BookChapterSearch`，返回 `response.PageResult`。
-- 详情返回：`bookRes.BookChapterResponse`。
+#### Request Body `book.BookChapter`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| bookId | uint | 是 | `> 0` | 所属书籍 ID |
+| title | string | 是 | 非空，最长 `255` | 章节标题 |
+| chapterNo | int | 是 | `> 0`；同一 `bookId` 下唯一 | 同书内章节顺序编号 |
+| isReadable | bool | 否 | 默认 `false`；为 `true` 时 `totalLines > 0` | 是否对 app 端开放阅读 |
+| contentFileUrl | string | 是 | 非空，最长 `500` | 章节内容文件 URL |
+| totalLines | int | 否 | 默认 `0`，`>= 0` | 章节正文总行数 |
+| isEnabled | bool | 否 | 默认 `true` | 章节是否启用 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
+- `bookId + chapterNo` 唯一。
+- `isReadable=true` 时，`totalLines` 必须大于 `0`。
+
+### 删除书籍章节
+
+- Method：`DELETE`
+- Path：`/book/deleteBookChapter`
+- Handler：`BookChapterApi.DeleteBookChapter`
+- Service：`BookChapterService.DeleteBookChapter`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 章节 ID |
+
+#### Response
+
+- `response.Response{msg}`
+
+### 批量删除书籍章节
+
+- Method：`DELETE`
+- Path：`/book/deleteBookChapterByIds`
+- Handler：`BookChapterApi.DeleteBookChapterByIds`
+- Service：`BookChapterService.DeleteBookChapterByIds`
+- 审计：是
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| ids | int[] | 二选一 | 非空，元素均 `> 0` | 章节 ID 数组 |
+| ids[] | int[] | 二选一 | 非空，元素均 `> 0` | 章节 ID 数组，兼容数组写法 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- `ids` 与 `ids[]` 二选一。
+
+### 更新书籍章节
+
+- Method：`PUT`
+- Path：`/book/updateBookChapter`
+- Handler：`BookChapterApi.UpdateBookChapter`
+- Service：`BookChapterService.UpdateBookChapter`
+- 审计：是
+
+#### Request Body `book.BookChapter`
+
+| 字段 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | uint | 是 | `> 0` | 章节 ID |
+| bookId | uint | 是 | `> 0` | 所属书籍 ID |
+| title | string | 是 | 非空，最长 `255` | 章节标题 |
+| chapterNo | int | 是 | `> 0`；同一 `bookId` 下唯一 | 同书内章节顺序编号 |
+| isReadable | bool | 否 | 为 `true` 时 `totalLines > 0` | 是否对 app 端开放阅读 |
+| contentFileUrl | string | 是 | 非空，最长 `500` | 章节内容文件 URL |
+| totalLines | int | 否 | `>= 0` | 章节正文总行数 |
+| isEnabled | bool | 否 | 布尔值 | 章节是否启用 |
+
+#### Response
+
+- `response.Response{msg}`
+
+#### 规则
+
+- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
+- 更新为实体全量保存，前端应传完整可编辑实体，避免字段被零值覆盖。
+- `bookId + chapterNo` 唯一。
+- `isReadable=true` 时，`totalLines` 必须大于 `0`。
+
+### 查询书籍章节详情
+
+- Method：`GET`
+- Path：`/book/findBookChapter`
+- Handler：`BookChapterApi.FindBookChapter`
+- Service：`BookChapterService.GetBookChapter`
+- 审计：否
+
+#### Request Query
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| id | int | 是 | `> 0` | 章节 ID |
+
+#### Response `bookRes.BookChapterResponse`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| bookChapter | object | 章节实体 |
+| bookChapter.id | uint | 章节 ID |
+| bookChapter.createdAt | string | 创建时间 |
+| bookChapter.updatedAt | string | 更新时间 |
+| bookChapter.bookId | uint | 所属书籍 ID |
+| bookChapter.title | string | 章节标题 |
+| bookChapter.chapterNo | int | 同书内章节顺序编号 |
+| bookChapter.isReadable | bool | 是否对 app 端开放阅读 |
+| bookChapter.contentFileUrl | string | 章节内容文件 URL |
+| bookChapter.totalLines | int | 章节正文总行数 |
+| bookChapter.isEnabled | bool | 章节是否启用 |
+
+### 分页查询书籍章节列表
+
+- Method：`GET`
+- Path：`/book/getBookChapterList`
+- Handler：`BookChapterApi.GetBookChapterList`
+- Service：`BookChapterService.GetBookChapterInfoList`
+- 审计：否
+
+#### Request Query `bookReq.BookChapterSearch`
+
+| 参数 | 类型 | 必填 | 规则 | 说明 |
+|:---|:---|:---:|:---|:---|
+| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
+| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
+| keyword | string | 否 | 章节标题模糊查询 | 关键字 |
+| bookId | uint | 否 | `> 0` | 所属书籍 ID |
+| isReadable | bool | 否 | 布尔值 | 是否对 app 端开放阅读 |
+| isEnabled | bool | 否 | 布尔值 | 章节是否启用 |
+
+#### Response `response.PageResult`
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| list | array | `book.BookChapter` 列表 |
+| list[].id | uint | 章节 ID |
+| list[].createdAt | string | 创建时间 |
+| list[].updatedAt | string | 更新时间 |
+| list[].bookId | uint | 所属书籍 ID |
+| list[].title | string | 章节标题 |
+| list[].chapterNo | int | 同书内章节顺序编号 |
+| list[].isReadable | bool | 是否对 app 端开放阅读 |
+| list[].contentFileUrl | string | 章节内容文件 URL |
+| list[].totalLines | int | 章节正文总行数 |
+| list[].isEnabled | bool | 章节是否启用 |
+| total | int64 | 总数 |
+| page | int | 当前页 |
+| pageSize | int | 每页数量 |
+
+#### 规则
+
+- 列表默认排序：`book_id asc, chapter_no asc`。
+
+## 规则
+
+- 章节使用硬删；删除后数据库不保留软删标记。
+- `bookId + chapterNo` 是章节唯一约束；新增或更新时不能与同书已有章节冲突。
+- `chapterNo` 必须大于 `0`。
+- `totalLines` 不能小于 `0`；`isReadable=true` 时 `totalLines` 必须大于 `0`。
+- 创建、更新复用实体 `book.BookChapter`；列表查询复用 `bookReq.BookChapterSearch`；详情返回 `bookRes.BookChapterResponse`。