docs(admin-api): add creator ppv material endpoint

docs/dev/admin-api/ADMIN-API-12-创作者代运营.md

@@ -1,11 +1,11 @@
 # ADMIN-API-12 创作者代运营
 
-> 当前共 6 个接口：OPS-01 ~ OPS-06  
+> 当前共 7 个接口：OPS-01 ~ OPS-07
 > 本文档用于定义“后台直建创作者”“后台为创作者上传媒体”“后台为创作者代发动态”的正式后台能力。  
 > 本模块不再复用客户端申请/发布接口，不依赖目标用户或创作者 token。
 >
-> **2026-04-11 联调结论：**
-> 1. `OPS-01 ~ OPS-06` 已完成本地真实 HTTP 冒烟验证；
+> **2026-04-16 联调结论：**
+> 1. `OPS-01 ~ OPS-07` 已完成本地真实 HTTP 冒烟验证；
 > 2. 视频上传链路在测试环境实测 `mp4` 可正常上传并完成转码；
 > 3. `webm` 是否可用取决于第三方媒体库实际支持，测试环境曾返回“不支持的文件类型”，联调阶段建议优先使用 `mp4`。
 
@@ -293,8 +293,9 @@
    - highlights 校验
    - 媒体归属与处理状态校验
 5. 校验 `visibility`：
-   - `free / ppv`：`requiredTierLevel` 必须为空
+   - `free`：`requiredTierLevel` 必须为空
    - `subscriber`：`requiredTierLevel` 必填，且必须在 `1~4` 内
+   - `ppv`：直接返回业务错误，提示改走 `POST /admin/api/v1/creators/:creatorId/ppv-materials`
 6. 当 `visibility=subscriber` 时，查询目标创作者订阅档位：
    - 若目标档位不存在或未启用，返回 `42201`
    - 若档位可用，则写入 `post.required_tier_level`
@@ -325,7 +326,7 @@
 | tags | object[] | 否 | 标签列表，支持 `id` / `name` 二选一 |
 | mentions | string[] | 否 | 被 @ 用户列表 |
 | location | object | 否 | 地点信息 |
-| visibility | string | 是 | `free/subscriber/ppv` |
+| visibility | string | 是 | `free/subscriber` |
 | requiredTierLevel | number | 条件必填 | `visibility=subscriber` 时必填，取值 `1/2/3/4` |
 | highlights | array | 否 | 视频章节打点 |
 | submitMode | string | 是 | `draft/reviewing/published` |
@@ -345,13 +346,77 @@
 |------|------|
 | 40001 | 内容参数、封面、highlights、submitMode 非法 |
 | 42201 | `requiredTierLevel` 缺失/非法，或目标订阅档位未启用 |
+| 42201 | `visibility=ppv`，需改走 PPV 素材创建接口 |
 | 40301 | 媒体不属于该创作者 |
 | 40401 | 创作者不存在、媒体不存在、被 @ 用户不存在 |
 | 40901 | 目标用户不是创作者 |
 
 ---
 
-## OPS-06 后台查询创作者订阅档位
+## OPS-06 后台为创作者创建 PPV 素材
+
+| 项目 | 说明 |
+|------|------|
+| 接口路径 | `POST /admin/api/v1/creators/:creatorId/ppv-materials` |
+| 接口用途 | 后台为指定创作者创建 PPV 素材，不再通过发帖接口伪装创建 PPV 帖子 |
+| 权限要求 | `content:create`；若允许直接发布再额外要求 `content:publish:direct`（当前实现建议额外限制为超级管理员） |
+| 涉及表 | `ppv_material`、`media`、`admin_operation_log` |
+
+### 接口逻辑
+
+1. 校验管理员权限
+2. 校验 `creatorId` 存在且角色为创作者
+3. 校验 `type` 仅允许 `image / video / gallery`
+4. 校验 `price > 0`
+5. 校验媒体归属目标创作者且已处理完成
+6. 校验媒体数量规则：
+   - `image`：`mediaIds` 必须恰好 1 个
+   - `video`：`mediaIds` 必须恰好 1 个，且 `coverMediaId` 必填
+   - `gallery`：`mediaIds` 必须为 `1~9` 个
+7. 当 `type=video` 时，`coverMediaId` 对应媒体必须为图片
+8. 根据 `submitMode` 决定初始状态：
+   - `reviewing` -> `ppv_material.status=reviewing`
+   - `published` -> `ppv_material.status=approved`
+9. 写入 `admin_operation_log`
+
+### 路径参数
+
+| 字段 | 类型 | 必选 | 说明 |
+|------|------|------|------|
+| creatorId | string | 是 | 目标创作者 ID |
+
+### 请求参数
+
+| 字段 | 类型 | 必选 | 说明 |
+|------|------|------|------|
+| title | string | 是 | 素材标题 |
+| type | string | 是 | `image / video / gallery` |
+| mediaIds | int64[] | 否 | 主媒体 ID 列表，具体数量按 `type` 校验 |
+| coverMediaId | string | 否 | 显式封面媒体 ID；`type=video` 时必填，且必须是图片媒体 |
+| price | number | 是 | PPV 价格，必须 `> 0` |
+| submitMode | string | 是 | `reviewing / published`；默认 `reviewing` |
+
+### 响应数据
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| materialId | string | 素材 ID |
+| status | string | `reviewing / approved` |
+| submitMode | string | 提交模式回显 |
+| createdAt | timestamp | 创建时间 |
+
+### 错误场景
+
+| code | 场景 |
+|------|------|
+| 40001 | `type` / `price` / `coverMediaId` / `submitMode` 非法 |
+| 40001 | 媒体不可用或数量错误 |
+| 40401 | 创作者不存在 |
+| 40901 | 目标用户不是创作者 |
+
+---
+
+## OPS-07 后台查询创作者订阅档位
 
 | 项目 | 说明 |
 |------|------|
@@ -426,12 +491,20 @@
 2. `reviewing` 内容会进入后台待审核列表
 3. `published` 内容可在详情、创作者作品列表、Feed 中可见
 4. 视频内容的封面图校验必须生效
+5. `visibility=ppv` 不再允许通过本接口创建
 
-### 4. 审计
+### 4. 后台创建 PPV 素材
+
+1. `reviewing` 素材会进入后台 PPV 审核列表
+2. `published` 素材可直接进入客户端素材库
+3. 视频素材的 `coverMediaId` 校验必须生效
+
+### 5. 审计
 
 1. 创建创作者写操作日志
 2. 后台上传媒体写操作日志
 3. 后台新建动态写操作日志
+4. 后台创建 PPV 素材写操作日志
 
 ---
 

docs/dev/admin-api/README.md

@@ -167,12 +167,14 @@
 - POST-A05 编辑帖子可见性 — `PATCH /admin/api/v1/posts/:postId/visibility`
 - POST-A06 后台设置创作者订阅档位 — `PUT /admin/api/v1/creators/:creatorId/subscription/tiers`
 
-### 12 创作者代运营（5个）
+### 12 创作者代运营（7个）
 - OPS-01 后台直建创作者 — `POST /admin/api/v1/creators`
 - OPS-02 后台上传图片 — `POST /admin/api/v1/media/image`
 - OPS-03 后台上传视频 — `POST /admin/api/v1/media/video`
 - OPS-04 后台查询视频处理状态 — `GET /admin/api/v1/media/:mediaId/status`
 - OPS-05 后台为创作者新建动态 — `POST /admin/api/v1/creators/:creatorId/posts`
+- OPS-06 后台为创作者创建 PPV 素材 — `POST /admin/api/v1/creators/:creatorId/ppv-materials`
+- OPS-07 后台查询创作者订阅档位 — `GET /admin/api/v1/creators/:creatorId/subscription/tiers`
 
 ---