# 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：将问题整理为本改造计划，按阶段拆分，并确定先做状态一致性与运行稳定性。