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

书籍作者 admin 接口

基本信息

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

CRUD

创建书籍作者

• Method：POST
• Path：/book/createBookAuthor
• Handler：BookAuthorApi.CreateBookAuthor
• Service：BookAuthorService.CreateBookAuthor
• 审计：是

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 为准。