feat: professionalize control plane and standalone delivery

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

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