书籍模块
This commit is contained in:
@@ -1,29 +1,199 @@
|
||||
# 书籍评论 admin 接口
|
||||
# 书籍评论 admin 接口
|
||||
|
||||
## 基本信息
|
||||
|
||||
- 模块：book
|
||||
- 资源：评论
|
||||
- 资源：书籍评论
|
||||
- 端：admin
|
||||
- 鉴权：挂载 `PrivateGroup`，需要 `JWT + Casbin`
|
||||
- 操作审计：创建、更新、单删、批量删除写操作启用 `OperationRecord`
|
||||
- 路由前缀：`/book`
|
||||
- 鉴权：`PrivateGroup`，需要 `JWT + Casbin`
|
||||
- 审计：创建、更新、单删、批量删除启用 `OperationRecord`
|
||||
- 前缀：`/book`
|
||||
- 实体模型：`book.BookComment`
|
||||
- 搜索入参：`bookReq.BookCommentSearch`
|
||||
- 详情响应：`bookRes.BookCommentResponse`
|
||||
- 返回：写操作 `response.Response{msg}`；详情 `response.Response{data}`；列表 `response.PageResult`
|
||||
- 删除策略：硬删
|
||||
|
||||
## 默认 CRUD
|
||||
## CRUD
|
||||
|
||||
| 动作 | Method | 路径 | API 方法 | Service 方法 |
|
||||
|:---|:---|:---|:---|:---|
|
||||
| 创建 | `POST` | `/book/createBookComment` | `CreateBookComment` | `CreateBookComment` |
|
||||
| 单删 | `DELETE` | `/book/deleteBookComment` | `DeleteBookComment` | `DeleteBookComment` |
|
||||
| 批量删除 | `DELETE` | `/book/deleteBookCommentByIds` | `DeleteBookCommentByIds` | `DeleteBookCommentByIds` |
|
||||
| 更新 | `PUT` | `/book/updateBookComment` | `UpdateBookComment` | `UpdateBookComment` |
|
||||
| 详情 | `GET` | `/book/findBookComment` | `FindBookComment` | `GetBookComment` |
|
||||
| 分页列表 | `GET` | `/book/getBookCommentList` | `GetBookCommentList` | `GetBookCommentInfoList` |
|
||||
### 创建书籍评论
|
||||
|
||||
## 参数与返回
|
||||
- Method：`POST`
|
||||
- Path：`/book/createBookComment`
|
||||
- Handler：`BookCommentApi.CreateBookComment`
|
||||
- Service：`BookCommentService.CreateBookComment`
|
||||
- 审计：是
|
||||
|
||||
- 创建、更新：`body` 使用 `book.BookComment`。
|
||||
- 单删、详情：`query id`。
|
||||
- 批量删除：`query ids[]`。
|
||||
- 分页列表：`query` 使用 `bookReq.BookCommentSearch`，返回 `response.PageResult`。
|
||||
- 详情返回：`bookRes.BookCommentResponse`。
|
||||
#### Request Body `book.BookComment`
|
||||
|
||||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| memberUserId | uint | 是 | 数据库非空 | 评论用户的会员 ID |
|
||||
| bookId | uint | 是 | 数据库非空 | 所属书籍 ID |
|
||||
| chapterId | uint | 否 | 默认 `0`；`>= 0` | 评论目标章节 ID，`0` 表示整本书 |
|
||||
| lineIndex | int | 否 | 默认 `0`；`>= 0`；整书评论时必须为 `0` | 评论目标文本行下标，`0` 表示整章或整本书 |
|
||||
| content | string | 是 | 数据库非空 | 评论正文内容 |
|
||||
| likeCount | int64 | 否 | 默认 `0`；`>= 0` | 评论点赞聚合值 |
|
||||
| commentStatus | string | 否 | 默认 `normal`；仅允许 `normal/hidden` | 评论状态字典值，对应 `book_comment_status` |
|
||||
|
||||
#### Response
|
||||
|
||||
- `response.Response{msg}`
|
||||
|
||||
#### 规则
|
||||
|
||||
- 创建请求禁止传服务端生成字段：`id/createdAt/updatedAt`。
|
||||
- `chapterId=0` 表示整书评论，此时 `lineIndex` 必须为 `0`。
|
||||
- `chapterId>0` 时允许 `lineIndex>=0`，其中 `lineIndex=0` 表示整章评论。
|
||||
|
||||
### 删除书籍评论
|
||||
|
||||
- Method：`DELETE`
|
||||
- Path：`/book/deleteBookComment`
|
||||
- Handler：`BookCommentApi.DeleteBookComment`
|
||||
- Service：`BookCommentService.DeleteBookComment`
|
||||
- 审计：是
|
||||
|
||||
#### Request Query
|
||||
|
||||
| 参数 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| id | int | 是 | `> 0` | 评论 ID |
|
||||
|
||||
#### Response
|
||||
|
||||
- `response.Response{msg}`
|
||||
|
||||
### 批量删除书籍评论
|
||||
|
||||
- Method：`DELETE`
|
||||
- Path：`/book/deleteBookCommentByIds`
|
||||
- Handler：`BookCommentApi.DeleteBookCommentByIds`
|
||||
- Service：`BookCommentService.DeleteBookCommentByIds`
|
||||
- 审计：是
|
||||
|
||||
#### Request Query
|
||||
|
||||
| 参数 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| ids | int[] | 二选一 | 非空，元素均为主键 ID | 评论 ID 数组 |
|
||||
| ids[] | int[] | 二选一 | 非空，元素均为主键 ID | 评论 ID 数组，兼容数组写法 |
|
||||
|
||||
#### Response
|
||||
|
||||
- `response.Response{msg}`
|
||||
|
||||
#### 规则
|
||||
|
||||
- `ids` 与 `ids[]` 二选一。
|
||||
|
||||
### 更新书籍评论
|
||||
|
||||
- Method：`PUT`
|
||||
- Path：`/book/updateBookComment`
|
||||
- Handler：`BookCommentApi.UpdateBookComment`
|
||||
- Service：`BookCommentService.UpdateBookComment`
|
||||
- 审计：是
|
||||
|
||||
#### Request Body `book.BookComment`
|
||||
|
||||
| 字段 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| id | uint | 是 | `> 0` | 评论 ID |
|
||||
| memberUserId | uint | 是 | 数据库非空 | 评论用户的会员 ID |
|
||||
| bookId | uint | 是 | 数据库非空 | 所属书籍 ID |
|
||||
| chapterId | uint | 否 | 默认 `0`；`>= 0` | 评论目标章节 ID，`0` 表示整本书 |
|
||||
| lineIndex | int | 否 | 默认 `0`；`>= 0`；整书评论时必须为 `0` | 评论目标文本行下标，`0` 表示整章或整本书 |
|
||||
| content | string | 是 | 数据库非空 | 评论正文内容 |
|
||||
| likeCount | int64 | 否 | 默认 `0`；`>= 0` | 评论点赞聚合值 |
|
||||
| commentStatus | string | 否 | 默认 `normal`；仅允许 `normal/hidden` | 评论状态字典值，对应 `book_comment_status` |
|
||||
|
||||
#### Response
|
||||
|
||||
- `response.Response{msg}`
|
||||
|
||||
#### 规则
|
||||
|
||||
- 更新请求禁止传服务端维护字段：`createdAt/updatedAt`。
|
||||
- 更新为实体全量保存，前端应传完整可编辑实体，避免字段被零值覆盖。
|
||||
- `chapterId=0` 表示整书评论，此时 `lineIndex` 必须为 `0`。
|
||||
- `chapterId>0` 时允许 `lineIndex>=0`，其中 `lineIndex=0` 表示整章评论。
|
||||
|
||||
### 查询书籍评论详情
|
||||
|
||||
- Method：`GET`
|
||||
- Path：`/book/findBookComment`
|
||||
- Handler：`BookCommentApi.FindBookComment`
|
||||
- Service：`BookCommentService.GetBookComment`
|
||||
- 审计：否
|
||||
|
||||
#### Request Query
|
||||
|
||||
| 参数 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| id | int | 是 | `> 0` | 评论 ID |
|
||||
|
||||
#### Response `bookRes.BookCommentResponse`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| bookComment | object | 评论实体 |
|
||||
| bookComment.id | uint | 评论 ID |
|
||||
| bookComment.createdAt | time | 创建时间 |
|
||||
| bookComment.updatedAt | time | 更新时间 |
|
||||
| bookComment.memberUserId | uint | 评论用户的会员 ID |
|
||||
| bookComment.bookId | uint | 所属书籍 ID |
|
||||
| bookComment.chapterId | uint | 评论目标章节 ID，`0` 表示整本书 |
|
||||
| bookComment.lineIndex | int | 评论目标文本行下标，`0` 表示整章或整本书 |
|
||||
| bookComment.content | string | 评论正文内容 |
|
||||
| bookComment.likeCount | int64 | 评论点赞聚合值 |
|
||||
| bookComment.commentStatus | string | 评论状态字典值，对应 `book_comment_status` |
|
||||
|
||||
### 分页查询书籍评论列表
|
||||
|
||||
- Method：`GET`
|
||||
- Path：`/book/getBookCommentList`
|
||||
- Handler：`BookCommentApi.GetBookCommentList`
|
||||
- Service：`BookCommentService.GetBookCommentInfoList`
|
||||
- 审计：否
|
||||
|
||||
#### Request Query `bookReq.BookCommentSearch`
|
||||
|
||||
| 参数 | 类型 | 必填 | 规则 | 说明 |
|
||||
|:---|:---|:---:|:---|:---|
|
||||
| page | int | 否 | 默认 `1`，最小 `1` | 页码 |
|
||||
| pageSize | int | 否 | 默认 `10`，最大 `100` | 每页数量 |
|
||||
| memberUserId | uint | 否 | 精确匹配 | 评论用户的会员 ID |
|
||||
| bookId | uint | 否 | 精确匹配 | 所属书籍 ID |
|
||||
| chapterId | uint | 否 | 精确匹配 | 评论目标章节 ID，`0` 表示整本书 |
|
||||
| commentStatus | string | 否 | 仅允许 `normal/hidden` | 评论状态字典值，对应 `book_comment_status` |
|
||||
|
||||
#### Response `response.PageResult`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| list | array | `book.BookComment` 列表 |
|
||||
| list[].id | uint | 评论 ID |
|
||||
| list[].createdAt | time | 创建时间 |
|
||||
| list[].updatedAt | time | 更新时间 |
|
||||
| list[].memberUserId | uint | 评论用户的会员 ID |
|
||||
| list[].bookId | uint | 所属书籍 ID |
|
||||
| list[].chapterId | uint | 评论目标章节 ID，`0` 表示整本书 |
|
||||
| list[].lineIndex | int | 评论目标文本行下标，`0` 表示整章或整本书 |
|
||||
| list[].content | string | 评论正文内容 |
|
||||
| list[].likeCount | int64 | 评论点赞聚合值 |
|
||||
| list[].commentStatus | string | 评论状态字典值，对应 `book_comment_status` |
|
||||
| total | int64 | 总数 |
|
||||
| page | int | 当前页 |
|
||||
| pageSize | int | 每页数量 |
|
||||
|
||||
#### 规则
|
||||
|
||||
- 列表默认排序：`id desc`。
|
||||
|
||||
## 规则
|
||||
|
||||
- `commentStatus` 必须符合 `book_comment_status`：`normal` 正常，`hidden` 隐藏。
|
||||
- `lineIndex/likeCount` 不能小于 `0`。
|
||||
- 整书评论 `chapterId=0` 时 `lineIndex` 必须为 `0`。
|
||||
- 删除策略为硬删。
|
||||
|
||||
Reference in New Issue
Block a user