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

书籍信息 admin 接口

基本信息

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

CRUD

创建书籍信息

• Method：POST
• Path：/book/createBook
• Handler：BookApi.CreateBook
• Service：BookService.CreateBook
• 审计：是

Request Body book.Book

字段	类型	必填	规则	说明
title	string	是	非空，最大 255	书名主标题
subtitle	string	否	最大 255	书籍副标题
bookType	string	是	非空，值必须存在于系统字典 book_type	书籍类型字典值
eraTag	string	否	book_era_tag：unknown/ancient/han/tang/song/yuan/ming/qing/modern/contemporary；默认 unknown	时代标签字典值
coverUrl	string	否	最大 500	封面图片 URL
publisher	string	否	最大 128	出版社名称
publishedAt	string	否	日期类型	出版日期
intro	string	否	文本	书籍简介
hotScore	int64	否	>= 0；默认 0	热度聚合值
rating	float64	否	0 <= rating <= 10；默认 0.0	书籍评分
commentCount	int64	否	>= 0；默认 0	点评数聚合值
wordCount	int64	否	>= 0；默认 0	书籍总字数
completionStatus	string	否	book_completion_status：completed/serializing；默认 serializing	书籍完结状态
publishStatus	string	否	book_publish_status：draft/off_shelf/on_shelf；默认 draft	书籍上下架状态
seriesId	uint	否	可为空；存在时应为有效系列 ID	所属系列 ID
seriesSort	int	否	>= 0；默认 0	同系列内展示排序
rawTxtUrl	string	否	最大 500	原始 txt 文件 URL

Response

• response.Response{msg}

规则

• 创建请求禁止传服务端生成字段：id/createdAt/updatedAt。
• bookType 是动态值域字典，业务侧只校验值存在性，不参与状态流转。

删除书籍信息

• Method：DELETE
• Path：/book/deleteBook
• Handler：BookApi.DeleteBook
• Service：BookService.DeleteBook
• 审计：是

Request Query

参数	类型	必填	规则	说明
id	int	是	> 0	书籍 ID

Response

• response.Response{msg}

批量删除书籍信息

• Method：DELETE
• Path：/book/deleteBookByIds
• Handler：BookApi.DeleteBookByIds
• Service：BookService.DeleteBookByIds
• 审计：是

Request Query

参数	类型	必填	规则	说明
ids	int[]	二选一	非空，元素均 > 0	书籍 ID 数组
ids[]	int[]	二选一	非空，元素均 > 0	书籍 ID 数组，兼容数组写法

Response

• response.Response{msg}

规则

• ids 与 ids[] 二选一。

更新书籍信息

• Method：PUT
• Path：/book/updateBook
• Handler：BookApi.UpdateBook
• Service：BookService.UpdateBook
• 审计：是

Request Body book.Book

字段	类型	必填	规则	说明
id	uint	是	> 0	书籍 ID
title	string	是	非空，最大 255	书名主标题
subtitle	string	否	最大 255	书籍副标题
bookType	string	是	非空，值必须存在于系统字典 book_type	书籍类型字典值
eraTag	string	否	book_era_tag：unknown/ancient/han/tang/song/yuan/ming/qing/modern/contemporary	时代标签字典值
coverUrl	string	否	最大 500	封面图片 URL
publisher	string	否	最大 128	出版社名称
publishedAt	string	否	日期类型	出版日期
intro	string	否	文本	书籍简介
hotScore	int64	否	>= 0	热度聚合值
rating	float64	否	0 <= rating <= 10	书籍评分
commentCount	int64	否	>= 0	点评数聚合值
wordCount	int64	否	>= 0	书籍总字数
completionStatus	string	否	book_completion_status：completed/serializing	书籍完结状态
publishStatus	string	否	book_publish_status：draft/off_shelf/on_shelf	书籍上下架状态
seriesId	uint	否	可为空；存在时应为有效系列 ID	所属系列 ID
seriesSort	int	否	>= 0	同系列内展示排序
rawTxtUrl	string	否	最大 500	原始 txt 文件 URL

Response

• response.Response{msg}

规则

• 更新请求禁止传服务端维护字段：createdAt/updatedAt。
• 更新使用实体 Save，前端应传完整可编辑实体，避免字段被零值覆盖。
• bookType 是动态值域字典，业务侧只校验值存在性，不参与状态流转。

查询书籍信息详情

• Method：GET
• Path：/book/findBook
• Handler：BookApi.FindBook
• Service：BookService.GetBook
• 审计：否

Request Query

参数	类型	必填	规则	说明
id	int	是	> 0	书籍 ID

Response bookRes.BookResponse

字段	类型	说明
book	object	书籍实体
book.id	uint	主键 ID
book.createdAt	string	创建时间
book.updatedAt	string	更新时间
book.title	string	书名主标题
book.subtitle	string	书籍副标题
book.bookType	string	书籍类型字典值，对应 book_type
book.eraTag	string	时代标签字典值，对应 book_era_tag
book.coverUrl	string	封面图片 URL
book.publisher	string	出版社名称
book.publishedAt	string	出版日期
book.intro	string	书籍简介
book.hotScore	int64	热度聚合值
book.rating	float64	书籍评分，范围 0-10
book.commentCount	int64	点评数聚合值
book.wordCount	int64	书籍总字数
book.completionStatus	string	书籍完结状态字典值，对应 book_completion_status
book.publishStatus	string	书籍上下架状态字典值，对应 book_publish_status
book.seriesId	uint	所属系列 ID
book.seriesSort	int	同系列内展示排序
book.rawTxtUrl	string	原始 txt 文件 URL

分页查询书籍信息列表

• Method：GET
• Path：/book/getBookList
• Handler：BookApi.GetBookList
• Service：BookService.GetBookInfoList
• 审计：否

Request Query bookReq.BookSearch

参数	类型	必填	规则	说明
page	int	否	默认 1，最小 1	页码
pageSize	int	否	默认 10，最大 100	每页数量
keyword	string	否	模糊匹配 title 或 subtitle	关键字
title	string	否	模糊匹配 title	书名主标题
bookType	string	否	值必须存在于系统字典 book_type	书籍类型
eraTag	string	否	book_era_tag：unknown/ancient/han/tang/song/yuan/ming/qing/modern/contemporary	时代标签
completionStatus	string	否	book_completion_status：completed/serializing	完结状态
publishStatus	string	否	book_publish_status：draft/off_shelf/on_shelf	上下架状态
seriesId	uint	否	> 0	系列 ID

Response response.PageResult

字段	类型	说明
list	array	book.Book 列表
list[].id	uint	主键 ID
list[].createdAt	string	创建时间
list[].updatedAt	string	更新时间
list[].title	string	书名主标题
list[].subtitle	string	书籍副标题
list[].bookType	string	书籍类型字典值，对应 book_type
list[].eraTag	string	时代标签字典值，对应 book_era_tag
list[].coverUrl	string	封面图片 URL
list[].publisher	string	出版社名称
list[].publishedAt	string	出版日期
list[].intro	string	书籍简介
list[].hotScore	int64	热度聚合值
list[].rating	float64	书籍评分，范围 0-10
list[].commentCount	int64	点评数聚合值
list[].wordCount	int64	书籍总字数
list[].completionStatus	string	书籍完结状态字典值，对应 book_completion_status
list[].publishStatus	string	书籍上下架状态字典值，对应 book_publish_status
list[].seriesId	uint	所属系列 ID
list[].seriesSort	int	同系列内展示排序
list[].rawTxtUrl	string	原始 txt 文件 URL
total	int64	总数
page	int	当前页
pageSize	int	每页数量

规则

• 列表默认排序：id desc。

规则

• admin 端书籍信息 CRUD 统一挂载到 PrivateGroup，需要 JWT + Casbin。
• 写操作启用 OperationRecord；读操作不启用操作审计。
• 删除策略为硬删，实体使用 book.HardDeleteModel，不维护 deleted_at。
• eraTag/completionStatus/publishStatus 必须符合对应固定值域字典。
• hotScore/commentCount/wordCount/seriesSort 不能小于 0；rating 范围为 0-10。
• seriesId 可为空；非空时表示书籍挂载到对应系列，展示排序使用 seriesSort。