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-implementation-checklist.md
+++ b/docs/frontend-implementation-checklist.md
@ -0,0 +1,335 @@
+# Frontend Implementation Checklist
+
+## Goal
+
+把当前 `biliup-next` 已有的后端能力，整理成前端可直接开发的任务清单。
+
+这份清单面向前端开发，不讨论后端架构，只回答 3 个问题：
+
+1. 先做哪些页面最值钱
+2. 每个页面要拆哪些组件
+3. 每个组件依赖哪些接口和字段
+
+## Priority
+
+建议按这个顺序推进：
+
+1. 任务列表页状态升级
+2. 任务详情页
+3. 手工绑定完整版 BV
+4. Session 合并 / 重绑
+5. 设置页常用配置强化
+
+## Milestone 1: 任务列表页状态升级
+
+目标：
+
+- 用户一眼看懂任务是在运行、等待、失败还是完成
+- 不需要理解内部状态机字段
+
+### 页面任务
+
+- 把当前任务列表中的内部状态替换成用户态状态
+- 在任务列表中增加“当前步骤”列
+- 在任务列表中增加“下次重试时间”列
+- 在任务列表中增加“分P BV / 完整版 BV”列
+- 在任务列表中增加“评论 / 合集 / 清理”状态列
+
+### 组件任务
+
+- `TaskStatusBadge`
+  - 输入：`task.status`, `task.retry_state`, `steps`
+  - 输出：`已接收 / 上传中 / 等待B站可见 / 需人工处理 / 已完成`
+- `TaskStepBadge`
+  - 输入：`steps`
+  - 输出当前步骤文案
+- `TaskDeliverySummary`
+  - 输入：`delivery_state`, `session_context`
+  - 输出：
+    - 分P BV
+    - 完整版 BV
+    - 评论状态
+    - 合集状态
+    - 清理状态
+
+### 接口依赖
+
+- `GET /tasks`
+
+### 建议后端字段
+
+- 现有可直接使用：
+  - `status`
+  - `retry_state`
+  - `delivery_state`
+  - `session_context`
+- 建议前端先本地派生：
+  - `display_status`
+  - `current_step`
+
+## Milestone 2: 任务详情页
+
+目标：
+
+- 用户不看日志也能知道这个任务发生了什么
+- 用户能在单任务页完成最常见修复动作
+
+### 页面任务
+
+- 新建任务详情页 Hero 区
+- 新建步骤时间线
+- 新建交付结果卡片
+- 新建 Session 信息卡片
+- 新建产物列表卡片
+- 新建历史动作卡片
+- 新建错误说明卡片
+
+### 组件任务
+
+- `TaskHero`
+  - 标题
+  - 用户态状态
+  - 当前步骤
+  - 下次重试时间
+- `TaskTimeline`
+  - ingest -> collection_b 全步骤
+- `TaskDeliveryPanel`
+  - 分P `BV`
+  - 完整版 `BV`
+  - 分P链接
+  - 完整版链接
+  - 合集状态
+- `TaskSessionPanel`
+  - `session_key`
+  - `streamer`
+  - `room_id`
+  - `segment_started_at`
+  - `segment_duration_seconds`
+  - `context_source`
+- `TaskArtifactsPanel`
+  - source_video
+  - subtitle_srt
+  - songs.json
+  - songs.txt
+  - clip_video
+- `TaskActionsPanel`
+  - 运行
+  - 重试
+  - 重置
+  - 绑定完整版 BV
+
+### 接口依赖
+
+- `GET /tasks/<id>`
+- `GET /tasks/<id>/steps`
+- `GET /tasks/<id>/artifacts`
+- `GET /tasks/<id>/history`
+- `GET /tasks/<id>/timeline`
+- `GET /tasks/<id>/context`
+
+### 操作接口依赖
+
+- `POST /tasks/<id>/actions/run`
+- `POST /tasks/<id>/actions/retry-step`
+- `POST /tasks/<id>/actions/reset-to-step`
+
+## Milestone 3: 手工绑定完整版 BV
+
+目标：
+
+- 用户在前端直接补 `full_video_bvid`
+- 不需要再手工写 `full_video_bvid.txt`
+
+### 页面任务
+
+- 在任务详情页增加“绑定完整版 BV”表单
+- 显示当前已绑定 BV
+- 显示绑定来源：
+  - fallback
+  - task_context
+  - meta_sidecar
+  - webhook
+
+### 组件任务
+
+- `BindFullVideoForm`
+  - 输入框：`BV...`
+  - 提交按钮
+  - 成功反馈
+  - 错误反馈
+
+### 接口依赖
+
+- `POST /tasks/<id>/bind-full-video`
+
+### 交互要求
+
+- 提交前本地校验 `BV[0-9A-Za-z]+`
+- 成功后刷新：
+  - `GET /tasks/<id>`
+  - `GET /tasks/<id>/context`
+
+## Milestone 4: Session 合并 / 重绑
+
+目标：
+
+- 用户能处理“同一场多个断流片段”
+- 用户能统一给整个 session 重绑完整版 BV
+
+### 页面任务
+
+- 在任务详情页显示当前任务所属 session
+- 增加“查看同 session 任务”入口
+- 增加“合并到现有 session”弹窗
+- 增加“整个 session 重绑完整版 BV”表单
+
+### 组件任务
+
+- `SessionSummaryCard`
+  - `session_key`
+  - task count
+  - 当前 `full_video_bvid`
+- `SessionTaskList`
+  - 列出该 session 下所有任务
+- `MergeSessionDialog`
+  - 输入目标 `session_key`
+  - 选择任务
+- `RebindSessionForm`
+  - 输入新的完整版 `BV`
+
+### 接口依赖
+
+- `GET /sessions/<session_key>`
+- `POST /sessions/<session_key>/merge`
+- `POST /sessions/<session_key>/rebind`
+
+### 交互要求
+
+- 合并成功后刷新：
+  - 当前任务详情
+  - session 详情
+  - 任务列表
+- 如果目标 session 已有 `full_video_bvid`
+  - 前端提示“合并后会继承该完整版 BV”
+
+## Milestone 5: 设置页常用配置强化
+
+目标：
+
+- 用户无需直接改 JSON 就能调优常用行为
+
+### 页面任务
+
+- 在设置页高亮常用 ingest/session 配置
+- 在设置页高亮 comment 重试配置
+- 在设置页高亮 cleanup 配置
+
+### 应优先暴露的配置
+
+- `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`
+
+### 接口依赖
+
+- `GET /settings`
+- `GET /settings/schema`
+- `PUT /settings`
+
+## Common UX Rules
+
+### 状态文案
+
+- `failed_retryable` 不显示“失败”
+- 优先显示：
+  - `等待自动重试`
+  - `等待B站可见`
+  - `正在处理中`
+  - `需人工处理`
+
+### 错误提示
+
+错误提示统一分成 2 行：
+
+- 原因
+- 建议动作
+
+例如：
+
+- 原因：视频刚上传，B站暂未可见
+- 建议：系统会自动重试，无需人工处理
+
+### 操作反馈
+
+所有写操作都要有：
+
+- loading 态
+- 成功 toast
+- 错误 toast
+
+### 刷新策略
+
+这些动作成功后必须自动刷新详情数据：
+
+- `retry-step`
+- `reset-to-step`
+- `bind-full-video`
+- `session merge`
+- `session rebind`
+
+## Suggested Frontend Types
+
+建议前端统一定义这些类型：
+
+```ts
+type TaskDisplayStatus =
+  | "accepted"
+  | "processing"
+  | "waiting_retry"
+  | "waiting_visibility"
+  | "manual_action"
+  | "done";
+
+type TaskSessionContext = {
+  task_id: string;
+  session_key: string | null;
+  streamer: string | null;
+  room_id: string | null;
+  source_title: string | null;
+  segment_started_at: string | null;
+  segment_duration_seconds: number | null;
+  full_video_bvid: string | null;
+  split_bvid: string | null;
+  context_source: string;
+  video_links: {
+    split_video_url: string | null;
+    full_video_url: string | null;
+  };
+};
+```
+
+## Suggested Build Order Inside Frontend Repo
+
+建议按这个顺序拆 PR：
+
+1. 状态映射工具函数
+2. 任务列表页文案升级
+3. 任务详情页 Session/Delivery 面板
+4. 绑定完整版 BV 表单
+5. Session 合并 / 重绑弹窗
+6. 设置页常用配置高亮
+
+## Definition Of Done
+
+这一轮前端完成的标准建议是：
+
+- 用户可以在任务列表页看懂所有任务当前状态
+- 用户可以在任务详情页看到分P/完整版 BV 和链接
+- 用户可以手工绑定完整版 BV
+- 用户可以把多个任务合并为同一个 session
+- 用户可以给整个 session 重绑完整版 BV
+- 用户不需要 ssh 登录机器改 txt 文件