194 lines
5.8 KiB
Markdown
194 lines
5.8 KiB
Markdown
# 书籍作者 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` 字符，唯一 | 作者名称 |
|
||
| isEnabled | bool | 否 | 默认 `true` | 作者是否启用 |
|
||
| intro | string | 否 | 可为空 | 作者简介 |
|
||
| coverUrl | string | 否 | 可为空，最大 `500` 字符 | 作者头像或封面 URL |
|
||
|
||
#### Response
|
||
|
||
- `response.Response{msg}`
|
||
|
||
#### 规则
|
||
|
||
- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
|
||
- `name` 必须唯一，对应唯一索引 `uk_book_author_name`。
|
||
- `isEnabled` 未传时按数据库默认值 `true` 落库。
|
||
|
||
### 删除书籍作者
|
||
|
||
- 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` 字符，唯一 | 作者名称 |
|
||
| isEnabled | bool | 否 | `true/false` | 作者是否启用 |
|
||
| intro | string | 否 | 可为空 | 作者简介 |
|
||
| coverUrl | string | 否 | 可为空，最大 `500` 字符 | 作者头像或封面 URL |
|
||
|
||
#### Response
|
||
|
||
- `response.Response{msg}`
|
||
|
||
#### 规则
|
||
|
||
- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
|
||
- 更新为实体全量保存，前端应传完整可编辑实体，避免字段被零值覆盖。
|
||
- `name` 必须唯一，对应唯一索引 `uk_book_author_name`。
|
||
|
||
### 查询书籍作者详情
|
||
|
||
- 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.isEnabled | bool | 作者是否启用 |
|
||
| 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` | 作者名称 |
|
||
| isEnabled | bool | 否 | `true/false` | 作者是否启用 |
|
||
|
||
#### Response `response.PageResult`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|:---|:---|:---|
|
||
| list | array | `bookRes.BookAuthorListItem` 列表 |
|
||
| list[].id | uint | 作者 ID |
|
||
| list[].createdAt | time | 创建时间 |
|
||
| list[].updatedAt | time | 更新时间 |
|
||
| list[].name | string | 作者名称 |
|
||
| list[].isEnabled | bool | 作者是否启用 |
|
||
| 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()`；读操作不挂操作审计。
|
||
- “是否启用”统一使用 `isEnabled` 布尔字段：`true` 表示启用，`false` 表示禁用。
|
||
- 表结构、字段长度、唯一约束和索引以 `.ai-specs/doc-sql/book_author.sql` 为准。
|