244 lines
9.4 KiB
Markdown
244 lines
9.4 KiB
Markdown
# 书籍信息 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`。
|