biliup-next/docs/frontend-implementation-checklist.md

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

建议前端统一定义这些类型：

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 文件