feat: professionalize control plane and standalone delivery

2026-04-07 10:46:30 +08:00
parent d0cf1fd0df
commit 862db502b0
100 changed files with 8313 additions and 1483 deletions
--- a/docs/frontend-product-integration.md
+++ b/docs/frontend-product-integration.md
@ -0,0 +1,383 @@
+# Frontend Product Integration
+
+## Goal
+
+从用户视角，把当前 `biliup-next` 的任务状态机包装成可操作、可理解的控制面。
+
+这份文档面向前端与后端联调，目标不是描述内部实现，而是明确：
+
+- 前端应该有哪些页面
+- 每个页面需要哪些字段
+- 当前后端已经提供了哪些接口
+- 哪些字段/接口还需要补
+
+## User Goals
+
+用户最关心的不是数据库状态，而是这 6 件事：
+
+1. 视频有没有被接收
+2. 现在卡在哪一步
+3. 这是自动等待还是需要人工处理
+4. 上传后的分P BV 和完整版 BV 是什么
+5. 评论和合集有没有完成
+6. 失败后应该点哪里恢复
+
+因此，前端不应该直接暴露 `created/transcribed/failed_retryable` 这类内部状态，而应该提供一层用户可理解的派生展示。
+
+## Information Architecture
+
+建议前端固定成 4 个一级页面：
+
+1. 总览页
+2. 任务列表页
+3. 任务详情页
+4. 设置页
+
+可选扩展页：
+
+5. 日志页
+6. Webhook / Sidecar 调试页
+
+## Page Spec
+
+### 1. 总览页
+
+目标：让用户在 10 秒内知道系统是否正常、当前队列是否卡住。
+
+核心模块：
+
+- 任务摘要卡片
+  - 运行中
+  - 等待自动重试
+  - 需人工处理
+  - 已完成
+- 最近 10 个任务
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+- 运行时摘要
+  - API 服务状态
+  - Worker 服务状态
+  - stage 目录文件数
+  - 最近一次调度结果
+- 风险提示
+  - cookies 缺失
+  - 磁盘空间不足
+  - Groq/Codex/Biliup 不可用
+
+现有接口可复用：
+
+- `GET /health`
+- `GET /doctor`
+- `GET /tasks?limit=100`
+- `GET /runtime/services`
+- `GET /scheduler`
+
+### 2. 任务列表页
+
+目标：批量查看任务，快速定位失败或等待中的任务。
+
+表格建议字段：
+
+- 任务标题
+- 用户态状态
+- 当前步骤
+- 完成进度
+- 下次重试时间
+- 分P BV
+- 完整版 BV
+- 评论状态
+- 合集状态
+- 清理状态
+- 最近更新时间
+
+筛选项建议：
+
+- 全部
+- 运行中
+- 等待自动重试
+- 需人工处理
+- 已完成
+- 仅显示未完成评论
+- 仅显示未完成合集
+- 仅显示未清理文件
+
+现有接口可复用：
+
+- `GET /tasks`
+
+建议新增的派生字段：
+
+- `display_status`
+- `current_step`
+- `progress_percent`
+- `split_bvid`
+- `full_video_bvid`
+- `session_key`
+- `session_binding_state`
+
+### 3. 任务详情页
+
+目标：让用户不看日志也能处理单个任务。
+
+建议布局：
+
+- Hero 区
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+  - 主要操作按钮
+- 步骤时间线
+  - ingest
+  - transcribe
+  - song_detect
+  - split
+  - publish
+  - comment
+  - collection_a
+  - collection_b
+- 交付结果区
+  - 分P BV
+  - 完整版 BV
+  - 分P 链接
+  - 完整版链接
+  - 合集 A / B 链接
+- Session 信息区
+  - session_key
+  - streamer
+  - room_id
+  - segment_started_at
+  - segment_duration_seconds
+  - 是否由 sidecar 提供
+  - 是否由时间连续性自动归并
+- 文件与产物区
+  - source_video
+  - subtitle_srt
+  - songs.json
+  - songs.txt
+  - clip_video
+- 历史动作区
+  - run
+  - retry-step
+  - reset-to-step
+- 错误与建议区
+  - 错误码
+  - 错误摘要
+  - 系统建议动作
+
+现有接口可复用：
+
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+
+建议新增接口：
+
+- `GET /tasks/<id>/context`
+
+### 4. 设置页
+
+目标：把常用配置变成可理解、可搜索、可修改的产品设置，而不是裸 JSON。
+
+优先展示的用户级配置：
+
+- `ingest.session_gap_minutes`
+- `ingest.meta_sidecar_enabled`
+- `ingest.meta_sidecar_suffix`
+- `comment.max_retries`
+- `comment.base_delay_seconds`
+- `cleanup.delete_source_video_after_collection_synced`
+- `cleanup.delete_split_videos_after_collection_synced`
+- `collection.season_id_a`
+- `collection.season_id_b`
+
+现有接口可复用：
+
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+
+## User-Facing Status Mapping
+
+前端必须提供一层用户态状态，不要直接显示内部状态。
+
+建议映射：
+
+- `created` -> `已接收`
+- `transcribed` -> `已转录`
+- `songs_detected` -> `已识歌`
+- `split_done` -> `已切片`
+- `published` -> `已上传`
+- `commented` -> `评论完成`
+- `collection_synced` -> `已完成`
+- `failed_retryable` + `step=comment` -> `等待B站可见`
+- `failed_retryable` 其他 -> `等待自动重试`
+- `failed_manual` -> `需人工处理`
+- 任一步 `running` -> `<步骤名>处理中`
+
+建议步骤名展示：
+
+- `ingest` -> `接收视频`
+- `transcribe` -> `转录字幕`
+- `song_detect` -> `识别歌曲`
+- `split` -> `切分分P`
+- `publish` -> `上传分P`
+- `comment` -> `发布评论`
+- `collection_a` -> `加入完整版合集`
+- `collection_b` -> `加入分P合集`
+
+## API Integration
+
+### Existing APIs That Frontend Should Reuse
+
+- `GET /tasks`
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+- `GET /runtime/services`
+- `POST /runtime/services/<service>/<action>`
+- `POST /worker/run-once`
+
+### Recommended New APIs
+
+#### `GET /tasks/<id>/context`
+
+用途：给任务详情页和 session 归并 UI 提供上下文。
+
+返回建议：
+
+```json
+{
+  "task_id": "xxx",
+  "session_key": "王海颖:20260402T2203",
+  "streamer": "王海颖",
+  "room_id": "581192190066",
+  "source_title": "王海颖唱歌录播 04月02日 22时03分",
+  "segment_started_at": "2026-04-02T22:03:00+08:00",
+  "segment_duration_seconds": 4076.443,
+  "full_video_bvid": "BV1uH9wBsELC",
+  "binding_source": "meta_sidecar"
+}
+```
+
+#### `POST /tasks/<id>/bind-full-video`
+
+用途：用户在前端手工补绑完整版 BV。
+
+请求：
+
+```json
+{
+  "full_video_bvid": "BV1uH9wBsELC"
+}
+```
+
+#### `POST /sessions/<session_key>/merge`
+
+用途：把多个任务手工归并到同一个 session。
+
+请求：
+
+```json
+{
+  "task_ids": ["why-2205", "why-2306"]
+}
+```
+
+#### `POST /sessions/<session_key>/rebind`
+
+用途：修改 session 级完整版 BV。
+
+请求：
+
+```json
+{
+  "full_video_bvid": "BV1uH9wBsELC"
+}
+```
+
+## Derived Fields For UI
+
+后端最好直接给前端这些派生字段，减少前端自行拼状态：
+
+- `display_status`
+- `display_step`
+- `progress_percent`
+- `split_bvid`
+- `full_video_bvid`
+- `video_links`
+- `delivery_state`
+- `retry_state`
+- `session_context`
+- `actions_available`
+
+其中 `actions_available` 建议返回：
+
+```json
+{
+  "run": true,
+  "retry_step": true,
+  "reset_to_step": true,
+  "bind_full_video": true,
+  "merge_session": true
+}
+```
+
+## Delivery State Contract
+
+任务列表和详情页都依赖统一的交付状态模型。
+
+建议结构：
+
+```json
+{
+  "split_bvid": "BV1GoDPBtEUg",
+  "full_video_bvid": "BV1uH9wBsELC",
+  "split_video_url": "https://www.bilibili.com/video/BV1GoDPBtEUg",
+  "full_video_url": "https://www.bilibili.com/video/BV1uH9wBsELC",
+  "comment_split_done": false,
+  "comment_full_done": false,
+  "collection_a_done": false,
+  "collection_b_done": false,
+  "source_video_present": true,
+  "split_videos_present": true
+}
+```
+
+## Suggested Frontend Build Order
+
+按实际价值排序：
+
+1. 任务列表页状态文案升级
+2. 任务详情页增加交付结果和重试说明
+3. 详情页增加 session/context 区块
+4. 设置页增加 session 归并相关配置
+5. 增加“手工绑定完整版 BV”操作
+6. 增加“合并 session”操作
+
+## MVP Scope
+
+如果只做一轮最小交付，建议先完成：
+
+- 用户态状态映射
+- 单任务详情页
+- `GET /tasks/<id>/context`
+- 手工绑定 `full_video_bvid`
+- 前端重试/重置按钮统一化
+
+这样即使 webhook 和自动 session 归并后面再完善，用户也已经能在前端完整处理问题。