txagent-y/txagent-y
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(admin-api): clarify ppv audit routes

Browse Source
This commit is contained in:
qingfeng 2026-04-10 14:21:50 +08:00
parent 45c3babedb
commit 0d9eae10ec
2 changed files with 136 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
docs/dev/admin-api/ADMIN-API-02-内容审核.md
View File

@ -1,6 +1,6 @@
# ADMIN-API-02 内容审核（AUDIT）
> 共 7 个接口：AUDIT-01~07
> 共 10 条路由：帖子审核 3、PPV 素材审核 2、Banner/头像审核 2、创作者申请审核 3
### 状态枚举映射
@ -39,6 +39,13 @@
| 2 | approved | 已通过 |
| 3 | rejected | 已拒绝 |
### 当前实现说明
1. `/admin/api/v1/audit/contents` 是统一待审内容列表入口；`type=ppv` 时会返回 PPV 素材的简表数据。
2. `/admin/api/v1/audit/contents/:contentId/approve|reject` 当前仅支持帖子审核，`contentId` 必须是 `post.id` 的 UUID。
3. PPV 素材审核动作需走独立接口 `/admin/api/v1/audit/ppv-materials/:materialId/review`，其中 `materialId` 为数字 ID。
4. 当前服务端逻辑在 RBAC 权限校验之外，还额外调用了 `RequireSuper`；因此测试环境现状只有超级管理员可调用本模块接口。若后续放开到审核员角色，应以 `audit:*` 权限口径为准。
---
#### AUDIT-01 获取待审核内容列表
@ -46,8 +53,8 @@
| 项目 | 说明 |
|------|------|
| 接口路径 | GET /admin/api/v1/audit/contents |
| 接口用途 | 获取所有待审核的内容（帖子/PPV素材） |
| 权限要求 | 内容审核员 |
| 接口用途 | 获取待审核内容列表；默认返回帖子，`type=ppv` 时返回 PPV 素材简表 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | post, ppv_material, media, user |
**接口逻辑：**
@ -55,17 +62,18 @@
2. 根据 type 参数区分查询：
- type=post → 查询 `post` 表（status=1 待审核，按 created_at 正序）（读）
- type=ppv → 查询 `ppv_material` 表（status=1 待审核，按 created_at 正序）（读）
- type 不传 → 合并查询两者
- type 不传 → 默认走帖子待审列表
3. 关联 `user` 表 获取创作者信息（读）
4. 关联 `media` 表 获取媒体预览（读）
4. post 路径关联 `media` 表 获取媒体预览；ppv 路径返回统一简表（读）
5. 支持分页
6. 当返回项 `type=ppv` 时，后续审核动作需走 `AUDIT-PPV-02`，不能走 `AUDIT-02 / AUDIT-03`
**请求参数（Query）：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| type | string | 否 | 类型筛选：post/ppv，不传为全部 |
| visibility | string | 否 | 可见性档位筛选：free/junior/basic/senior/supreme，不传为全部（仅 type=post 时生效） |
| type | string | 否 | 类型筛选：post/ppv；不传默认 `post` |
| visibility | string | 否 | 可见性档位筛选：free/junior/basic/senior/supreme，仅 `type=post` 时生效 |
| page | number | 否 | 页码，默认1 |
| pageSize | number | 否 | 每页条数，默认20 |
@ -74,11 +82,11 @@
| 字段 | 类型 | 说明 |
|------|------|------|
| list | array | 待审核内容列表 |
| list[].contentId | string | 内容ID（post._id 或 ppv_material._id） |
| list[].contentId | string | 内容ID；`type=post` 时为帖子 UUID，`type=ppv` 时为 PPV 素材数字 ID 的字符串形式 |
| list[].type | string | 类型：post/ppv |
| list[].title | string | 标题/描述 |
| list[].visibility | string | 可见性档位：free/junior/basic/senior/supreme（post 类型返回） |
| list[].mediaPreview | array | 媒体预览列表（缩略图URL） |
| list[].visibility | string | 可见性档位：free/junior/basic/senior/supreme（仅 post 类型返回） |
| list[].mediaPreview | array | 媒体预览列表（缩略图URL；ppv 简表当前为空数组） |
| list[].mediaType | string | 媒体类型：image/video |
| list[].creator | object | 创作者信息 |
| list[].creator.userId | string | 创作者ID |
@ -89,90 +97,166 @@
---
#### AUDIT-02 审核通过内容
#### AUDIT-02 审核通过帖子内容
| 项目 | 说明 |
|------|------|
| 接口路径 | POST /admin/api/v1/audit/contents/:contentId/approve |
| 接口用途 | 审核员通过某条内容 |
| 权限要求 | 内容审核员 |
| 涉及表 | post, ppv_material, admin_operation_log |
| 接口用途 | 审核员通过某条帖子内容 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | post, admin_operation_log |
**接口逻辑：**
1. 校验管理员权限（permission_key: `audit:content:review`）
2. 根据 type 参数确定操作目标：
- type=post → 读 `post`，校验 status=1（待审核）（读）
- type=ppv → 读 `ppv_material`，校验 status=1（读）
3. 更新 status=2（已通过/已上架），设置 reviewed_by = 当前 admin_id，reviewed_at = 当前时间（更新）
4. 帖子审核通过时，设置 published_at = 当前时间
5. 写入 `admin_operation_log`（action: approve_content）（写）
2. 校验 `contentId` 为帖子 UUID，读取 `post` 并校验 status=1（待审核）（读）
3. 更新 status=2（published），并设置 `published_at = NOW()`（更新）
4. 写入 `admin_operation_log`（action: content_approve，target_type=post）（写）
5. 当前实现不支持用该接口审核 PPV 素材；如传 `type=ppv` 会报错
**路径参数：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| contentId | string | 是 | 内容ID |
| contentId | string | 是 | 帖子 UUID |
**请求参数（Body）：**
**请求参数：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| type | string | 是 | 类型：post/ppv |
无。当前实现无需请求体；如携带 `type`，仅兼容 `post`。
**响应数据：**
| 字段 | 类型 | 说明 |
|------|------|------|
| contentId | string | 内容ID |
| status | string | 更新后状态：published（post）/ approved（ppv） |
| contentId | string | 帖子 UUID |
| status | string | 更新后状态：published |
---
#### AUDIT-03 审核拒绝内容
#### AUDIT-03 审核拒绝帖子内容
| 项目 | 说明 |
|------|------|
| 接口路径 | POST /admin/api/v1/audit/contents/:contentId/reject |
| 接口用途 | 审核员拒绝某条内容 |
| 权限要求 | 内容审核员 |
| 涉及表 | post, ppv_material, notification, admin_operation_log |
| 接口用途 | 审核员拒绝某条帖子内容 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | post, notification, admin_operation_log |
**接口逻辑：**
1. 校验管理员权限（permission_key: `audit:content:review`）
2. 根据 type 参数确定操作目标，校验 status=1（待审核）（读）
3. 更新 status=3（已拒绝），设置 reject_reason、reviewed_by、reviewed_at（更新）
2. 校验 `contentId` 为帖子 UUID，读取 `post` 并校验 status=1（待审核）（读）
3. 更新 status=3（rejected），设置 reject_reason（更新）
4. 写入 `notification` 表 通知创作者（type=system，content="内容审核未通过：{reject_reason}"）（写）
5. 写入 `admin_operation_log`（action: reject_content）（写）
5. 写入 `admin_operation_log`（action: content_reject，target_type=post）（写）
6. 当前实现不支持用该接口审核 PPV 素材；如传 `type=ppv` 会报错
**路径参数：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| contentId | string | 是 | 内容ID |
| contentId | string | 是 | 帖子 UUID |
**请求参数（Body）：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| type | string | 是 | 类型：post/ppv |
| rejectReason | string | 是 | 拒绝原因 |
**响应数据：**
| 字段 | 类型 | 说明 |
|------|------|------|
| contentId | string | 内容ID |
| contentId | string | 帖子 UUID |
| status | string | 更新后状态：rejected |
---
#### AUDIT-PPV-01 获取待审核 PPV 素材列表
| 项目 | 说明 |
|------|------|
| 接口路径 | GET /admin/api/v1/audit/ppv-materials |
| 接口用途 | 获取 PPV 素材审核列表 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | ppv_material, user |
**接口逻辑：**
1. 校验管理员权限
2. 按 `status` 查询 `ppv_material`；不传时返回全部状态，传入时支持 `reviewing/approved/rejected`
3. 关联创作者信息并返回素材主信息
4. 支持分页
**请求参数（Query）：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| status | string | 否 | 状态筛选：reviewing/approved/rejected |
| page | number | 否 | 页码，默认1 |
| pageSize | number | 否 | 每页条数，默认20 |
**响应数据：**
| 字段 | 类型 | 说明 |
|------|------|------|
| list | array | PPV 素材列表 |
| list[].materialId | string | PPV 素材 ID（数字字符串） |
| list[].creatorId | string | 创作者 ID |
| list[].title | string | 素材标题 |
| list[].type | string | 素材类型：image/video/gallery |
| list[].status | string | 状态：reviewing/approved/rejected |
| list[].mediaIds | array | 关联媒体 ID 列表 |
| list[].price | number | 售价 |
| list[].rejectReason | string | 拒绝原因 |
| list[].creator | object | 创作者信息 |
| list[].createdAt | timestamp | 提交时间 |
| pagination | object | 分页信息 |
---
#### AUDIT-PPV-02 审核 PPV 素材（通过/拒绝）
| 项目 | 说明 |
|------|------|
| 接口路径 | POST /admin/api/v1/audit/ppv-materials/:materialId/review |
| 接口用途 | 审核 PPV 素材，通过和拒绝共用同一路由 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | ppv_material |
**接口逻辑：**
1. 校验管理员权限
2. 校验 `materialId` 为正整数，读取 `ppv_material` 并校验状态可审核
3. `approve=true` 时更新状态为 `approved`
4. `approve=false` 时要求 `rejectReason` 必填，并更新状态为 `rejected`
5. 返回素材 ID 与更新后状态
**路径参数：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| materialId | string | 是 | PPV 素材数字 ID |
**请求参数（Body）：**
| 字段 | 类型 | 必选 | 说明 |
|------|------|------|------|
| approve | boolean | 是 | `true` 表示通过，`false` 表示拒绝 |
| rejectReason | string | 条件必选 | 拒绝原因；`approve=false` 时必填 |
**响应数据：**
| 字段 | 类型 | 说明 |
|------|------|------|
| materialId | string | PPV 素材数字 ID |
| status | string | 更新后状态：approved/rejected |
---
#### AUDIT-04 获取待审核 Banner/头像列表
| 项目 | 说明 |
|------|------|
| 接口路径 | GET /admin/api/v1/audit/avatars |
| 接口用途 | 获取创作者 Banner 和用户头像的审核队列 |
| 权限要求 | 内容审核员 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | user, creator_profile |
**接口逻辑：**
@ -213,7 +297,7 @@
|------|------|
| 接口路径 | POST /admin/api/v1/audit/avatars/:id/review |
| 接口用途 | 通过或拒绝 Banner/头像 |
| 权限要求 | 内容审核员 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | user, creator_profile, notification, admin_operation_log |
**接口逻辑：**
@ -259,7 +343,7 @@
|------|------|
| 接口路径 | GET /admin/api/v1/audit/creator-applications |
| 接口用途 | 获取普通用户申请成为创作者的审核队列 |
| 权限要求 | 内容审核员 |
| 权限要求 | 内容审核员（当前实现额外限制为超级管理员） |
| 涉及表 | creator_application, creator_application_tag, tag, user |
**接口逻辑：**
@ -314,7 +398,7 @@
|------|------|
| 接口路径 | POST /admin/api/v1/audit/creator-applications/:id/approve |
| 接口用途 | 通过创作者申请 |
| 权限要求 | 内容审核员 |
| 权限要求 | 超级管理员 |
| 涉及表 | creator_application, creator_application_tag, user, creator_profile, subscription_tier, notification, admin_operation_log |
**接口逻辑（步骤全程同一事务）：**
@ -357,7 +441,7 @@
|------|------|
| 接口路径 | POST /admin/api/v1/audit/creator-applications/:id/reject |
| 接口用途 | 拒绝创作者申请 |
| 权限要求 | 内容审核员 |
| 权限要求 | 超级管理员 |
| 涉及表 | creator_application, notification, admin_operation_log |
**接口逻辑：**

17
docs/dev/admin-api/README.md
View File

@ -3,7 +3,7 @@
> **版本：** v1.0
> **基于文档：** API-运营后台接口文档-产品视角.md
> **拆分日期：** 2026-03-31
> **接口总数：** 64 个
> **接口总数：** 68 个
---
@ -53,7 +53,7 @@
| # | 模块 | 接口数 | 文件 |
|---|------|--------|------|
| 01 | [登录与权限](ADMIN-API-01-登录与权限.md) | 10 | ADMIN-AUTH-01~05, ADMIN-ROLE-01~05 |
| 02 | [内容审核](ADMIN-API-02-内容审核.md) | 7 | AUDIT-01~07 |
| 02 | [内容审核](ADMIN-API-02-内容审核.md) | 10 | AUDIT-01~07、AUDIT-PPV-01~02 |
| 03 | [举报处理](ADMIN-API-03-举报处理.md) | 2 | REPORT-A01~02 |
| 04 | [用户管理](ADMIN-API-04-用户管理.md) | 6 | USER-A01~06 |
| 05 | [财务管理](ADMIN-API-05-财务管理.md) | 9 | FIN-01~09 |
@ -80,14 +80,17 @@
- ADMIN-ROLE-04 编辑角色 — `PUT /admin/api/v1/roles/:roleId`
- ADMIN-ROLE-05 删除角色 — `DELETE /admin/api/v1/roles/:roleId`
### 02 内容审核（7个）
### 02 内容审核（10个）
- AUDIT-01 获取待审核内容列表 — `GET /admin/api/v1/audit/contents`
- AUDIT-02 审核通过内容 — `POST /admin/api/v1/audit/contents/:contentId/approve`
- AUDIT-03 审核拒绝内容 — `POST /admin/api/v1/audit/contents/:contentId/reject`
- AUDIT-02 审核通过帖子内容 — `POST /admin/api/v1/audit/contents/:contentId/approve`
- AUDIT-03 审核拒绝帖子内容 — `POST /admin/api/v1/audit/contents/:contentId/reject`
- AUDIT-PPV-01 获取待审核 PPV 素材列表 — `GET /admin/api/v1/audit/ppv-materials`
- AUDIT-PPV-02 审核 PPV 素材 — `POST /admin/api/v1/audit/ppv-materials/:materialId/review`
- AUDIT-04 获取待审核Banner/头像列表 — `GET /admin/api/v1/audit/avatars`
- AUDIT-05 审核Banner/头像 — `POST /admin/api/v1/audit/avatars/:id/review`
- AUDIT-06 获取待审核创作者申请列表 — `GET /admin/api/v1/audit/creator-applications`
- AUDIT-07 创作者申请审核 — `POST /admin/api/v1/audit/creator-applications/:applicationId/review`
- AUDIT-07a 创作者申请审核-通过 — `POST /admin/api/v1/audit/creator-applications/:id/approve`
- AUDIT-07b 创作者申请审核-拒绝 — `POST /admin/api/v1/audit/creator-applications/:id/reject`
### 03 举报处理（2个）
- REPORT-A01 获取举报列表 — `GET /admin/api/v1/reports`
@ -229,7 +232,7 @@
| 2 | 创作者被封禁后，其内容和订阅用户如何处理？ | USER-A03 |
| 3 | 手动发放代币是否需要双人审批？ | CS-03 |
| 4 | 提现是否需要T+7冻结期？ | FIN-01/02 |
| 5 | 内容审核是否接入第三方AI审核？ | AUDIT-01/02/03 |
| 5 | 内容审核是否接入第三方AI审核？ | AUDIT-01/02/03/AUDIT-PPV-01/02 |
| 6 | 数据注水是否需要审批流程？ | BOOST-01/03 |
| 7 | 退款是否需要多级审批？ | FIN-05 |
| 8 | 运营后台是独立部署还是共用后端？ | 全部 |