336 lines
7.0 KiB
Markdown
336 lines
7.0 KiB
Markdown
# 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 文件
|