up

2026-10-18 21:08:54 +08:00
parent 1253c159f5
commit 1d440b2916
9 changed files with 901 additions and 167 deletions
@@ -1,7 +1,7 @@
 # 短视频应用接口文档

- 版本：v1.0
- 日期：2026-10-14
+- 版本：v1.1
+- 日期：2026-10-18
 - Base URL：`https://api.example.com/api/v1`

 > 注意：App 不硬编码 Base URL。启动时优先解析 `txt.256kb.top` 的 DNS TXT 记录获取真实 API 域名；解析失败时按 `md5(yyyyMM) + "_jsnbhh.vip"` 计算兜底域名（详见《01-开发文档》5.5 节）。本文示例域名仅为占位。
@@ -90,7 +90,7 @@
 | 13 | 用户 | POST | /users/me/deactivate | 注销账号（7天冻结期） | 是 |
 | 14 | 用户 | GET | /users/{user_id} | 用户公开主页 | 否 |
 | 15 | 用户 | GET | /users/{user_id}/videos | 他人作品列表 | 否 |
-| 16 | 视频 | GET | /videos/feed | 推荐视频流（支持 recommend/latest/hot） | 否 |
+| 16 | 视频 | GET | /videos/feed | 视频流（recommend/latest/hot/liked/viewed） | 否 |
 | 17 | 视频 | GET | /videos/{video_id} | 视频详情（登录返回续播进度） | 否 |
 | 18 | 视频 | POST | /videos/{video_id}/watch | 观看上报（计费，可带播放进度） | 否 |
 | 19 | 视频 | POST | /videos/{video_id}/watch/complete | 完整观看上报（创作收益计数） | 否 |
@@ -133,7 +133,10 @@
 | 56 | 消息 | GET | /notifications/unread_count | 未读数 | 是 |
 | 57 | 消息 | POST | /notifications/read | 标记已读 | 是 |
 | 58 | 通用 | POST | /reports | 提交举报 | 是 |
-| 59~90 | 后台管理 | * | /admin/** | 登录、看板、审核、视频/评论管理、用户、积分、订单、补单、套餐、赠送、提现审核、推荐风控、举报处理、敏感词、平台配置、日志，见第 11 章 | 管理员 |
+| 59 | 视频 | GET | /videos/series/{series_id} | 系列详情 + 全部集数列表 | 否 |
+| 60 | 视频 | GET | /videos/{video_id}/series | 当前视频所属系列 + 上下集 | 否 |
+| 61 | 通用 | GET | /m3u8/proxy | m3u8 播放列表代理（回源拉取，TS 分片不经过服务器） | 否 |
+| 62~105 | 后台管理 | * | /admin/** | 登录、看板、审核、视频/系列/评论管理、用户（含重置密码）、积分、订单、补单/退款、套餐、赠送、提现审核、推荐风控、举报处理、敏感词、平台配置、采集源/采集同步、分类、标签、日志，见第 11 章 | 管理员 |

 ---

@@ -160,7 +163,7 @@
 { "code": 0, "message": "ok", "data": { "expire_seconds": 300, "retry_after": 60 } }
 ```

-**限制**：同号码 60 秒 1 条，同号码每天 10 条；注册场景下已注册号码返回错误码 1001（"该手机号已注册"）。
+**限制**：同号码 60 秒 1 条，同号码每天 10 条，同 IP 每小时 5 条；注册场景下已注册号码返回错误码 1001（"该账号已注册"），login/reset 场景下未注册号码同样返回 1001。未配置短信通道时（开发环境）响应额外返回 `dev_code` 并仅记日志。

 ### 3.2 发送邮箱验证码 `POST /auth/email/send`

@@ -169,7 +172,7 @@
 | email | string | 是 | 邮箱地址 |
 | scene | string | 是 | `register` / `login` / `reset` |

-响应同 3.1，`expire_seconds=600`。
+验证码由服务端通过 SMTP 真实发送（STARTTLS），并写入 Redis（`email:code:{scene}:{email}`，10 分钟有效，验证通过即删除）。响应结构同 3.1，`expire_seconds=600`；限流规则同 3.1（同邮箱 60 秒 1 条、每天 10 条、同 IP 每小时 5 条）。未配置 SMTP 时按开发模式处理：响应额外返回 `dev_code` 并仅记日志。

 ### 3.3 注册 `POST /auth/register`

@@ -223,6 +226,7 @@
 | email | string | 邮箱方式必填 | |
 | password | string | 密码方式必填 | |
 | code | string | 验证码方式必填 | |
+| revoke | bool | 否 | 注销冻结期内确认撤销注销（默认 false，见 4.6） |

 **请求示例**

@@ -230,7 +234,9 @@
 { "type": "phone_password", "phone": "13800138000", "password": "abc12345" }
 ```

-**响应**：同 3.3。连续失败 5 次锁定 15 分钟（错误码 1005）。
+**响应**：同 3.3。连续失败 5 次锁定 15 分钟（错误码 1005，按 IP 维度计数）。
+
+> 登录账号仅支持**手机号或邮箱**（按 type 使用对应字段），不支持昵称登录。冻结期内账号登录返回 1009 且 `data.can_revoke=true`；确认撤销后带 `"revoke": true` 重试即恢复账号并正常签发 Token。

 ### 3.5 刷新令牌 `POST /auth/token/refresh`

@@ -240,6 +246,8 @@

 **响应**：同 3.3 的 token 部分；refresh_token 旋转（旧值立即失效）。

+> Token 体系：access_token 有效期 2 小时，refresh_token 30 天（Redis 白名单 Set，支持多端同时在线）。服务端按用户维护令牌纪元 `auth:epoch:{user_id}`，签发时写入 Token 的 `ep` 声明，每次请求都校验：修改/重置密码、后台重置密码（11.34）后纪元递增并清空 refresh 白名单，该用户所有旧 Token（含未过期的 access）立即失效。
+
 ### 3.6 退出登录 `POST /auth/logout`（需登录）

 无参数。响应 `{ "code": 0 }`。服务端将 access_token 的 jti 加入黑名单并删除 refresh 白名单。
@@ -401,7 +409,7 @@
 | cursor | string | 否 | 上一页返回的 next_cursor |
 | limit | int | 否 | 默认 10，最大 20 |
 | category_id | int | 否 | 分类筛选 |
-| type | string | 否 | 策略：`recommend`（默认，个性化）/ `latest` / `hot` |
+| type | string | 否 | 策略：`recommend`（默认，个性化）/ `latest`（最新发布）/ `hot`（热度）/ `liked`（口碑，按点赞量倒序）/ `viewed`（热播，按播放量倒序） |

 **响应示例**

@@ -434,6 +442,11 @@
 > `is_liked/is_favorited` 仅登录用户返回真实值，游客恒为 false。
 >
 > **recommend 策略**：以"当天日期 + 用户/设备"为随机种子每日重排（同一用户每天的推荐顺序不同、同一天内多次刷新顺序稳定）；当日已观看的视频尽量不再出现（候选不足时放开过滤兜底）；个性化基于近 7 天观看/点赞/收藏视频的标签偏好加权，游客及新用户退化为热度排序。
+>
+> **游标格式**（均为 base64url 编码的 JSON，客户端无需解析，原样回传即可）：
+> - `liked` / `viewed`：「值,id」双键游标 `{"n": 末条点赞数/播放数, "i": 末条 video_id}`，按"值 DESC, id DESC"严格翻页，点赞/播放数变化不影响已翻过的页
+> - `latest`：`{"p": 末条发布时间戳, "i": 末条 video_id}`
+> - `recommend` / `hot`：当日种子下的偏移游标

 ### 5.2 视频详情 `GET /videos/{video_id}`（游客可）

@@ -651,6 +664,30 @@

 **错误码**：2107 无权操作（非作者本人）；2003 视频不存在。

+### 5.14 系列详情 `GET /videos/series/{series_id}`（游客可）
+
+返回系列信息 + 全部已发布集数（按 `episode_no` 升序），用于短剧播放页选集。
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "data": {
+    "series": { "id": 12, "title": "霸道总裁", "cover_url": "https://...", "description": "...", "total_episodes": 80 },
+    "episodes": [
+      { "video_id": 88001, "episode_no": 1, "title": "第1集", "cover_url": "https://...", "duration": 95, "video_url": "https://.../index.m3u8" }
+    ]
+  }
+}
+```
+
+**错误码**：1006 系列不存在或已隐藏。
+
+### 5.15 当前视频所属系列 `GET /videos/{video_id}/series`（游客可）
+
+用于 PlayerScreen 系列抽屉入口。视频不属于任何系列（或未发布）时返回 `{ "has_series": false }`；否则返回系列信息、全部集数（字段同 5.14）及 `current_episode_no` / `prev_video_id` / `next_video_id`（无上下集时为 null）。
+
 ---

 ## 6. 互动模块
@@ -1197,6 +1234,20 @@ App 我的页消息入口红点依赖本接口（直接读 Redis `notif:unread:{

 **错误码**：2106 请勿重复举报（同一用户对同一对象仅一次有效举报，唯一索引 `uk_user_target` 保证）；限流 10 次/天。

+### 10.6 m3u8 播放列表代理 `GET /m3u8/proxy`（游客可）
+
+采集内容源站的 m3u8 内 TS 链接带时效签名，需经服务端每次回源拉取新鲜播放列表；**TS 分片不经过本服务器**，由客户端按播放列表中的源站地址直连下载。
+
+**查询参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| path | string | 是 | 源站播放列表的相对资源路径（防 SSRF：仅允许字母数字及 `/._-`，禁止 `..`），1-300 字 |
+
+**响应**：非统一 JSON 包装，直接返回 m3u8 文本（`Content-Type: application/vnd.apple.mpegurl`，`Cache-Control: no-cache`，`Access-Control-Allow-Origin: *`）。
+
+**错误码**：1001 非法路径；1006 播放列表获取失败（源站非 200 或内容非 m3u8）。
+
 ---

 ## 11. 管理后台接口
@@ -1204,7 +1255,7 @@ App 我的页消息入口红点依赖本接口（直接读 Redis `notif:unread:{
 通用约定：
 - 前缀 `/api/v1/admin`，统一响应结构同 App 接口
 - 认证：`Authorization: Bearer <admin_token>`（Token payload `type="admin"`，有效期 12h，与 App 用户体系互不相通）
- 角色：`super`（全部）/ `reviewer`（仅审核）/ `operator`（套餐、活动、看板）；越权返回 4001
+- 角色：`super`（全部）/ `reviewer`（仅审核）/ `operator`（套餐、活动、看板、采集源/采集同步、系列/分类/标签查询）；越权返回 4001
 - 所有写操作记录操作日志；标注【敏感】的接口 `reason` 必填，缺失返回 4002

 ### 11.1 管理员登录 `POST /admin/auth/login`
@@ -1466,6 +1517,120 @@ App 我的页消息入口红点依赖本接口（直接读 Redis `notif:unread:{

 响应 `{ "code": 0 }`，同样触发词库缓存重建。

+### 11.33 重置用户密码 `PUT /admin/users/{user_id}/password`【敏感】（仅 super）
+
+客服场景下由后台直接重置某个 App 用户的登录密码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| new_password | string | 是 | 新密码，6-100 位（bcrypt 入库，不校验字母数字组合） |
+| reason | string | 是 | 操作原因（写入 admin_logs，action=`user_password_reset`） |
+
+```json
+// 请求
+{ "new_password": "newpass123", "reason": "用户申诉核实通过" }
+// 响应
+{ "code": 0 }
+```
+
+重置后该用户**全端 Token 立即失效**：服务端递增 `auth:epoch:{user_id}` 并删除 refresh 白名单（机制见 3.5），用户需用新密码重新登录。
+
+**错误码**：1006 用户不存在；1001 账号已注销不可操作。
+
+### 11.34 退款登记 `POST /admin/orders/{order_no}/refund`【敏感】（仅 super）
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| reason | string | 是 | 退款原因 |
+
+### 11.35 修改管理员密码 `PUT /admin/auth/password`（仅 super）
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| old_password | string | 是 | 当前密码 |
+| new_password | string | 是 | 新密码，6-100 位 |
+
+响应 `{ "code": 0 }`。
+
+### 11.36 后台新增视频 `POST /admin/videos`（仅 super）
+
+两种模式二选一：
+- **upload_token 模式**：先调 `POST /admin/videos/upload` 拿凭证 → `POST /admin/videos/upload/file` 上传 mp4/mov/mkv/avi（multipart，字段 `file` + query `token`）→ 拿到 `upload_token` 后调本接口（服务端自动转码）
+- **video_url 模式**：直接填已转码的 m3u8 地址（外站/CDN 资源）
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| title | string | 是 | 1-100 字 |
+| description | string | 否 | ≤500 字 |
+| category_id | int | 是 | 分类 ID |
+| tag_names | array[string] | 否 | 标签 |
+| upload_token | string | 模式A必填 | upload/file 返回的凭证（封面可选 cover_upload_token） |
+| video_url | string | 模式B必填 | m3u8 地址 |
+| cover_url | string | 模式B可选 | 封面 |
+| duration | int | 否 | 时长（秒），1-36000 |
+| status | int | 否 | 1待审核（默认）/ 2直接发布 |
+
+配套接口：
+- `POST /admin/videos/upload`：获取 admin 上传凭证，返回 `{ upload_url, method, token, expire_seconds: 3600 }`
+- `POST /admin/videos/upload/file?token=xxx`：接收文件落盘 server/uploads，返回 `{ upload_token, object_key, file_size }`（凭证一次性，upload_token 24h 内有效）
+- `POST /admin/upload/image`：通用图片上传（封面/头像/系列图，jpg/jpeg/png/webp/gif），返回可直接访问的完整 URL `{ url, file_size }`
+
+### 11.37 后台编辑视频 `PUT /admin/videos/{video_id}`（仅 super）
+
+均可选，传哪个改哪个：`title`（1-100）/ `description` / `cover_url` / `video_url` / `category_id` / `series_id` / `episode_no`（≥1）/ `status`（0-5）。`series_id` 显式传 `null` 表示移出系列（同时清空 episode_no）。响应 `{ "code": 0, "data": { "video_id": 88001 } }`。
+
+### 11.38 后台删除视频 `DELETE /admin/videos/{video_id}`（仅 super）
+
+**物理删除**：先解绑系列，再级联删除标签/点赞/收藏/评论/观看记录/收益/举报等全部关联数据。响应 `{ "code": 0, "data": { "video_id": 88001, "deleted": true } }`。
+
+### 11.39 系列管理
+
+| 方法 | 路径 | 角色 | 说明 |
+|---|---|---|---|
+| GET | /admin/series | operator | 系列分页列表（keyword 按标题模糊），含 `source_id`（采集来源标记，供"同步更新"按钮） |
+| POST | /admin/series | super | 新建系列：`title`（1-100 必填）、`cover_url`、`description`、`category_id` |
+| PUT | /admin/series/{series_id} | super | 改 `title` / `cover_url` / `description` / `category_id` / `status`（0隐藏 1正常） |
+| DELETE | /admin/series/{series_id} | super | 删除系列（集数视频的 series_id 需先解绑） |
+| POST | /admin/videos/{video_id}/series | super | 绑定视频到系列：`{ "series_id": 12, "episode_no": 3 }`，自动重算 series.total_episodes（仅计已发布） |
+
+### 11.40 短剧采集同步（operator）
+
+- `POST /admin/collection/sync/{series_id}`：手动同步单部采集短剧（补充源站新出的集数）；非采集内容返回 1006。响应为同步统计 `{新增集数等}`，写 admin_logs（action=`collection_sync`）
+- `POST /admin/collection/sync-all`：触发内置短剧源增量同步，**后台异步执行，立即返回** `{ "started": true, "pages": 2 }`。入参 `pages`（1-20，默认 2）为增量同步的列表页数；已有任务进行中返回 1005
+
+### 11.41 采集源管理（单视频类，自助添加）
+
+采集源 = "分类名 + 列表页 URL 模板"，URL 必须包含 `{{page}}` 页码占位符；创建/改名时按名称自动建/找分类。
+
+| 方法 | 路径 | 角色 | 说明 |
+|---|---|---|---|
+| GET | /admin/collection/sources | operator | 全部源列表（id/name/list_url/category_id/status/last_sync_at/created_at） |
+| POST | /admin/collection/sources | operator | 新增源：`name`（1-50）、`list_url`（须含 `{{page}}`，否则 1001） |
+| PUT | /admin/collection/sources/{source_id} | operator | 改 `name` / `list_url` / `status`（0停用 1启用） |
+| DELETE | /admin/collection/sources/{source_id} | super | 删除源 |
+| POST | /admin/collection/sources/batch | operator | 批量添加：body `{ "text": "分类名 URL\n..." }` 每行一条（URL 可带反引号）；返回 `created/skipped/failed` 清单，新建源自动触发后台采集 |
+| POST | /admin/collection/sources/{source_id}/sync | operator | 同步单个源（后台异步）：入参 `max_pages`（0=不限，增量自动提前停止，上限 200）；该源同步中返回 1005 |
+| POST | /admin/collection/sources/sync-all | operator | 同步全部启用源（后台异步），返回 `{ "started": [...], "skipped_running": [...] }` |
+
+### 11.42 分类管理
+
+| 方法 | 路径 | 角色 | 说明 |
+|---|---|---|---|
+| GET | /admin/categories | operator | 全部启用分类（不分页，供下拉框）：`[{id, name}]` |
+| GET | /admin/categories/admin | operator | 分页列表（keyword 模糊），含 `sort` / `status` / 实时统计的 `video_count` |
+| POST | /admin/categories | super | 新建：`name`、`sort`（默认0）、`status`（默认1）；重名返回错误 |
+| PUT | /admin/categories/{cid} | super | 改 `name` / `sort` / `status` |
+| DELETE | /admin/categories/{cid} | super | 删除；分类下仍有视频时拒绝并提示数量 |
+
+### 11.43 标签管理
+
+| 方法 | 路径 | 角色 | 说明 |
+|---|---|---|---|
+| GET | /admin/tags | operator | 分页列表（keyword 模糊，page_size 默认 50 最大 200），`video_count` 由 video_tags 实时统计 |
+| POST | /admin/tags | super | 新建：`name`（去空格，空名报错）；已存在返回错误 |
+| PUT | /admin/tags/{tid} | super | 改名 |
+| DELETE | /admin/tags/{tid} | super | 删除标签并清理全部视频关联 |
+
 ---

 ## 12. App 端关键调用时序