theshy/biliup-next
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
862db502b08418ebbcf3234d5393393a54750c0c
biliup-next/docs/frontend-product-integration.md

7.9 KiB
Raw Blame History

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. 设置页

可选扩展页：

  1. 日志页
  2. 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 提供上下文。

返回建议：

{
  "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。

请求：

{
  "full_video_bvid": "BV1uH9wBsELC"
}

POST /sessions/<session_key>/merge

用途：把多个任务手工归并到同一个 session。

请求：

{
  "task_ids": ["why-2205", "why-2306"]
}

POST /sessions/<session_key>/rebind

用途：修改 session 级完整版 BV。

请求：

{
  "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 建议返回：

{
  "run": true,
  "retry_step": true,
  "reset_to_step": true,
  "bind_full_video": true,
  "merge_session": true
}

Delivery State Contract

任务列表和详情页都依赖统一的交付状态模型。

建议结构：

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