diff --git a/docs/dev/admin-api/ADMIN-API-11-内容管理.md b/docs/dev/admin-api/ADMIN-API-11-内容管理.md index fe5ebd8..c10d01b 100644 --- a/docs/dev/admin-api/ADMIN-API-11-内容管理.md +++ b/docs/dev/admin-api/ADMIN-API-11-内容管理.md @@ -332,7 +332,56 @@ --- -#### POST-A06 后台设置创作者订阅档位 +#### POST-A06 后台查询创作者订阅档位 + +| 项目 | 说明 | +|------|------| +| 接口路径 | GET /admin/api/v1/creators/:creatorId/subscription/tiers | +| 接口用途 | 后台查询创作者当前完整订阅档位配置,供前端进入编辑页时回填 | +| 权限要求 | 超级管理员 / 运营专员(permission_key: `creator:subscription:manage`;当前实现建议额外限制为超级管理员) | +| 涉及表 | user, creator_profile, subscription_tier, user_subscription | + +**接口逻辑:** +1. 校验权限(permission_key: `creator:subscription:manage`) +2. 校验 `creatorId` 存在且角色为创作者,同时 `creator_profile` 处于有效状态 +3. 查询 `subscription_tier` 的完整档位列表(含未启用档位) +4. 若历史数据缺失 `free` 档,则按当前互斥规则补一个内存态 `free` 返回: + - 任一付费档启用时,`free.enabled=false` + - 全部付费档关闭时,`free.enabled=true` +5. 统计各档位订阅人数(`user_subscription` 有效状态) +6. 返回完整档位列表,结构与设置接口保持一致 + +**路径参数:** + +| 字段 | 类型 | 必选 | 说明 | +|------|------|------|------| +| creatorId | string | 是 | 创作者 userId | + +**响应数据:** + +| 字段 | 类型 | 说明 | +|------|------|------| +| creatorId | string | 创作者ID | +| tiers | array | 当前完整档位配置 | +| tiers[].tierId | string | 档位ID;若为内存补位 free 则可能为空字符串 | +| tiers[].tierLevel | number | 档位等级:0~4 | +| tiers[].tierKey | string | free/junior/basic/senior/supreme | +| tiers[].name | string | 档位名称 | +| tiers[].price | number | 档位价格(分) | +| tiers[].description | string | 档位说明 | +| tiers[].enabled | boolean | 是否启用 | +| tiers[].permissions | string[] | 权益配置 | +| tiers[].subscriberCount | number | 当前订阅人数 | +| updatedAt | timestamp | 最近更新时间 | + +**校验返回码:** +- 403:权限不足 +- 404:创作者不存在 +- 409:目标用户不是创作者 / 创作者资料不可用 + +--- + +#### POST-A07 后台设置创作者订阅档位 | 项目 | 说明 | |------|------| @@ -408,7 +457,7 @@ | `post` | 主表。需补字段:`takedown_reason VARCHAR(200)`、`takedown_by UUID`、`takedown_at TIMESTAMPTZ` | | `content_boost` | LEFT JOIN 取注水值;`is_active=1` 时外显值叠加 | | `subscription_tier` | 读取/配置创作者订阅档位;`visibility=subscriber` 时用于回填档位名称与价格 | -| `admin_operation_log` | 写入 takedown 审计;POST-A02 详情读取该帖的全部历史 | +| `admin_operation_log` | 写入 takedown / 订阅档位配置审计;POST-A02 详情读取该帖的全部历史 | | `report` | POST-A02 详情读取该帖举报概要 | | `notification` | POST-A04 通知创作者 | diff --git a/docs/dev/admin-api/ADMIN-API-12-创作者代运营.md b/docs/dev/admin-api/ADMIN-API-12-创作者代运营.md index 8f2f8a8..a50ec21 100644 --- a/docs/dev/admin-api/ADMIN-API-12-创作者代运营.md +++ b/docs/dev/admin-api/ADMIN-API-12-创作者代运营.md @@ -1,11 +1,11 @@ # ADMIN-API-12 创作者代运营 -> 当前共 5 个接口:OPS-01 ~ OPS-05 +> 当前共 6 个接口:OPS-01 ~ OPS-06 > 本文档用于定义“后台直建创作者”“后台为创作者上传媒体”“后台为创作者代发动态”的正式后台能力。 > 本模块不再复用客户端申请/发布接口,不依赖目标用户或创作者 token。 > > **2026-04-11 联调结论:** -> 1. `OPS-01 ~ OPS-05` 已完成本地真实 HTTP 冒烟验证; +> 1. `OPS-01 ~ OPS-06` 已完成本地真实 HTTP 冒烟验证; > 2. 视频上传链路在测试环境实测 `mp4` 可正常上传并完成转码; > 3. `webm` 是否可用取决于第三方媒体库实际支持,测试环境曾返回“不支持的文件类型”,联调阶段建议优先使用 `mp4`。 @@ -344,6 +344,59 @@ --- +## OPS-06 后台查询创作者订阅档位 + +| 项目 | 说明 | +|------|------| +| 接口路径 | `GET /admin/api/v1/creators/:creatorId/subscription/tiers` | +| 接口用途 | 后台查询创作者当前完整订阅档位配置,供前端回填编辑页 | +| 权限要求 | `creator:subscription:manage`(当前实现建议额外限制为超级管理员) | +| 涉及表 | `user`, `creator_profile`, `subscription_tier`, `user_subscription` | + +### 接口逻辑 + +1. 校验管理员权限 +2. 校验 `creatorId` 存在且角色为创作者 +3. 查询创作者完整订阅档位列表(含未启用档位) +4. 若历史数据缺失 `free` 档,则按当前互斥规则补一个内存态 `free` 返回: + - 任一付费档启用时,`free.enabled=false` + - 全部付费档关闭时,`free.enabled=true` +5. 统计各档位当前订阅人数 +6. 返回完整档位列表;结构与 `PUT /admin/api/v1/creators/:creatorId/subscription/tiers` 保持一致 + +### 路径参数 + +| 字段 | 类型 | 必选 | 说明 | +|------|------|------|------| +| creatorId | string | 是 | 目标创作者 ID | + +### 响应数据 + +| 字段 | 类型 | 说明 | +|------|------|------| +| creatorId | string | 创作者 userId | +| tiers | array | 当前完整档位配置 | +| tiers[].tierId | string | 档位 ID;若为内存补位 free 可为空 | +| tiers[].tierLevel | number | 档位等级 0~4 | +| tiers[].tierKey | string | `free/junior/basic/senior/supreme` | +| tiers[].name | string | 档位名称 | +| tiers[].price | number | 月价格(分) | +| tiers[].description | string | 档位说明 | +| tiers[].enabled | boolean | 是否启用 | +| tiers[].permissions | string[] | 权益枚举 | +| tiers[].subscriberCount | number | 当前订阅人数 | +| updatedAt | timestamp | 最近更新时间 | + +### 错误场景 + +| code | 场景 | +|------|------| +| 40001 | `creatorId` 非法 | +| 40401 | 创作者不存在 | +| 40901 | 目标用户不是创作者 / 创作者资料不可用 | + +--- + ## 验收标准 ### 1. 创建创作者