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