biliup-next/docs/refactor-plan-2026-04-06.md

biliup-next Refactor Plan - 2026-04-06

目标

围绕当前重构项目已暴露出的状态一致性、数据一致性、运行稳定性和控制面性能问题，分阶段推进改造，优先修复会影响真实运行结果的问题，再收敛模型和技术债。

改造原则

• 先修正单一事实源，再优化展示层。
• 先修正状态机真实行为，再修正文档和 UI 映射。
• 先处理运行稳定性，再处理性能和结构整理。
• 每一阶段都要求有可验证的验收结果，避免只做“结构看起来更好”。

阶段划分

Phase 1: 状态与事实源收敛

目标：

• 让 task 具备真实可用的 running 语义。
• 让 full_video_bvid 只有一套权威写入路径。
• 消除“数据库状态”和“工作区文件状态”互相覆盖的问题。

任务：

• 在 step 开始执行时同步更新 task 运行态。
• 明确 task 完成后 task 状态如何从 running 返回业务态。
• 统一 bind/rebind/webhook/ingest 对 full_video_bvid 的读写入口。
• 明确 task_contexts、session_bindings、full_video_bvid.txt 的职责。

验收标准：

• 控制台能正确筛选和显示运行中的任务。
• 手工绑定、session 重绑、webhook 注入后，新旧任务读取到相同 BV。
• 不再出现新任务 ingest 继承旧 BV 的情况。

Phase 2: 运行稳定性加固

目标：

• 让 API 与 worker 并行运行时的 SQLite 行为可控。
• 降低锁冲突、脏状态和半成功写入风险。

任务：

• 为 SQLite 连接增加 busy_timeout、WAL、foreign_keys=ON。
• 检查高频 repo 写入点，减少不必要的小事务。
• 梳理关键写路径是否需要合并成原子操作。

验收标准：

• API 和 worker 并行运行时，不再轻易触发数据库锁错误。
• 关键任务状态写入具备基本原子性，不出现“步骤更新了、任务没更新”一类半状态。

Phase 3: 控制面装配与查询优化

目标：

• 去掉 API 请求路径上的重复初始化。
• 解决 /tasks 列表的全量扫描和 N+1 查询问题。

任务：

• 将 ensure_initialized() 从“每次请求即装配”改为更稳定的应用级初始化方式。
• 收敛 provider/registry 生命周期，避免每次请求重复扫描 manifest 和实例化 provider。
• 优化任务列表接口，把可下推的过滤逻辑下推到 repository 或持久化层。
• 减少列表查询时对工作区文件的逐条读取。

验收标准：

• 常规 API 请求不再重复做全量装配。
• 大量任务下的列表页和筛选页响应明显改善。

Phase 4: 状态机与文档对齐

目标：

• 让文档状态机、代码状态机、控制面展示口径一致。

任务：

• 决定是否保留 ingested、completed、cancelled。
• 明确 flag 文件在系统中的角色。
• 如果数据库是任务状态唯一来源，则把 delivery flag 降级为产物或外部副作用标记。
• 更新状态机文档、控制面展示文案和开发约束。

验收标准：

• 文档中的状态集合与代码中的状态集合一致。
• UI 不再依赖不存在或含义不稳定的 task 状态。

Phase 5: 回归测试与维护收尾

目标：

• 为核心编排逻辑补回归保护。
• 降低后续重构再次引入状态漂移的概率。

任务：

• 新增 tests/。
• 优先覆盖：
  • task_engine
  • task_policies
  • task_actions
  • retry_meta
  • task_reset
• 决定 classic 控制台的保留策略。

验收标准：

• 核心状态流转具备最小自动化回归覆盖。
• 控制台维护策略明确，不再长期双线漂移。

推荐执行顺序

1. Phase 1
2. Phase 2
3. Phase 3
4. Phase 4
5. Phase 5

本轮起步范围

本轮先从以下子项开始：

• Phase 1.1: task running 状态落地
• Phase 1.2: full_video_bvid 写路径统一
• Phase 2.1: SQLite 连接配置加固

过程记录

• 2026-04-06：完成代码审查，确认当前优先问题集中在 task 运行态缺失、full_video_bvid 多源不一致、SQLite 并发配置不足、重复初始化、列表查询 N+1、状态机文档与实现漂移、测试缺失。
• 2026-04-06：将问题整理为本改造计划，按阶段拆分，并确定先做状态一致性与运行稳定性。