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

书籍章节 admin 接口

基本信息

• 模块：book
• 资源：书籍章节
• 端：admin
• 鉴权：PrivateGroup，需要 JWT + Casbin
• 审计：创建、更新、单删、批量删除启用 OperationRecord
• 前缀：/book
• 实体模型：book.BookChapter
• 搜索入参：bookReq.BookChapterSearch
• 详情响应：bookRes.BookChapterResponse
• 列表项：bookRes.BookChapterListItem
• 返回：写操作 response.Response{msg}；详情 response.Response{data}；列表 response.PageResult
• 删除策略：硬删

CRUD

创建书籍章节

• Method：POST
• Path：/book/createBookChapter
• Handler：BookChapterApi.CreateBookChapter
• Service：BookChapterService.CreateBookChapter
• 审计：是

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.bookTitle	string	书籍标题展示字段，来源于 book.title AS book_title
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	bookRes.BookChapterListItem 列表
list[].id	uint	章节 ID
list[].createdAt	string	创建时间
list[].updatedAt	string	更新时间
list[].bookId	uint	所属书籍 ID
list[].bookTitle	string	书籍标题展示字段，来源于 book.title AS book_title
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。
• 列表通过 book_chapter 联表 book 补充 bookTitle 展示字段；写接口仍只接收 bookId。

规则

• 章节使用硬删；删除后数据库不保留软删标记。
• bookId + chapterNo 是章节唯一约束；新增或更新时不能与同书已有章节冲突。
• chapterNo 必须大于 0。
• totalLines 不能小于 0；isReadable=true 时 totalLines 必须大于 0。
• 创建、更新复用实体 book.BookChapter；列表查询复用 bookReq.BookChapterSearch；详情返回 bookRes.BookChapterResponse。
• bookTitle 为只读展示字段，禁止写入实体表结构，禁止作为创建或更新入参。