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