# 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 归并后面再完善，用户也已经能在前端完整处理问题。