feat: professionalize control plane and standalone delivery

2026-04-07 10:46:30 +08:00
parent d0cf1fd0df
commit 862db502b0
100 changed files with 8313 additions and 1483 deletions
--- a/docs/todo-2026-04-06.md
+++ b/docs/todo-2026-04-06.md
@ -0,0 +1,196 @@
+# biliup-next Todo - 2026-04-06
+
+## 今日待办
+
+### P0
+
+- 修正任务级 `running` 状态缺失问题。
+  - 当前 step 会进入 `running`，但 task 不会进入 `running`，导致控制台“处理中”筛选、优先级判断和注意力状态失真。
+  - 相关位置：
+    - `src/biliup_next/app/task_engine.py`
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/modules/*/service.py`
+
+- 收敛 `full_video_bvid` 的单一事实源。
+  - 当前 `task_contexts`、`session_bindings`、`session/full_video_bvid.txt` 三处状态可能不一致。
+  - `rebind_session_full_video_action()` 没有同步更新 `session_bindings`，后续新任务 ingest 仍可能继承旧 BV。
+  - 相关位置：
+    - `src/biliup_next/app/task_actions.py`
+    - `src/biliup_next/modules/ingest/service.py`
+    - `src/biliup_next/infra/task_repository.py`
+
+- 补强 SQLite 并发配置。
+  - 当前 API 与 worker 可并行运行，但数据库连接仍是最基础配置，缺少 `busy_timeout`、`WAL`、`foreign_keys=ON` 等保护。
+  - 后续任务量或并发操作增加时，容易出现 `database is locked` 一类问题。
+  - 相关位置：
+    - `src/biliup_next/infra/db.py`
+
+### P1
+
+- 消除 API 路径上的重复初始化。
+  - `ensure_initialized()` 目前会重复执行配置加载、DB 初始化、插件扫描和 provider 实例化。
+  - API 每次请求都可能再次触发整套装配，后续会拖慢控制面并增加维护成本。
+  - 相关位置：
+    - `src/biliup_next/app/bootstrap.py`
+    - `src/biliup_next/app/api_server.py`
+
+- 优化 `/tasks` 的全量扫描和 N+1 查询。
+  - 当前 `attention/delivery` 过滤会先拉最多 5000 条任务，再逐条补 task payload、step、context 和文件系统状态。
+  - 任务规模上来后会明显拖慢列表页和筛选体验。
+  - 相关位置：
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/infra/task_repository.py`
+
+- 收敛文档状态机与代码实现。
+  - 文档中存在 `ingested`、`completed`、`cancelled`，并声明不再依赖 flag 文件作为权威状态。
+  - 实际实现中这些状态并未完整落地，评论/合集完成态仍依赖多个 flag 文件。
+  - 需要统一“文档模型”和“代码真实状态机”，避免后续继续漂移。
+  - 相关位置：
+    - `docs/state-machine.md`
+    - `src/biliup_next/app/api_server.py`
+    - `src/biliup_next/modules/comment/providers/bilibili_top_comment.py`
+    - `src/biliup_next/modules/collection/providers/bilibili_collection.py`
+
+### P2
+
+- 为状态机、重试和手工干预流程补测试。
+  - 当前仓库没有看到 `tests/` 或自动化回归覆盖。
+  - 优先覆盖：
+    - `task_engine`
+    - `task_policies`
+    - `task_actions`
+    - `retry_meta`
+    - `task_reset`
+
+- 明确两套控制台的维护策略。
+  - 当前 React 控制台和 classic 控制台并存。
+  - 需要决定 classic 是长期保留、冻结维护，还是逐步退役。
+
+## 备注
+
+- 以上问题来自 2026-04-06 对 `biliup-next` 当前重构实现的代码审查。
+- 优先顺序按“状态一致性 / 数据一致性 / 运行稳定性 / 控制面性能 / 可维护性”排列。
+
+## 过程记录
+
+- 2026-04-06：完成首轮代码审查，确认当前优先问题。
+- 2026-04-06：基于问题清单拆出分阶段改造计划，见 `docs/refactor-plan-2026-04-06.md`。
+- 2026-04-06：确定首批执行范围为 task `running` 状态落地、`full_video_bvid` 写路径统一、SQLite 连接加固。
+- 2026-04-06：已完成首轮代码改造。
+  - task 在 step 被 claim 后会进入 `running`。
+  - `bind/rebind/webhook` 已统一复用 `full_video_bvid` 持久化路径。
+  - SQLite 连接已增加 `foreign_keys`、`busy_timeout`、`WAL`、`synchronous=NORMAL`。
+  - 已执行 `python -m compileall biliup-next/src/biliup_next` 验证语法通过。
+- 2026-04-06：已完成第二轮控制面改造。
+  - `ensure_initialized()` 已改为进程内复用，避免 API 请求重复装配全套应用状态。
+  - `PUT /settings` 后会主动失效并重建缓存状态，避免新旧配置混用。
+  - `/tasks` 列表已改为批量预取 task context 和 steps，减少列表页 N+1 查询。
+  - 已再次执行 `python -m compileall biliup-next/src/biliup_next` 验证语法通过。
+- 2026-04-06：已完成状态机文档对齐。
+  - `state-machine.md` 与 `architecture.md` 已改成当前代码真实状态集合：`created/running/transcribed/songs_detected/split_done/published/commented/collection_synced/failed_*`。
+  - 已明确 `ingested/completed/cancelled` 当前未落地，不再作为现阶段实现口径。
+  - 已明确工作区 flag 仅表示交付副作用和产物标记，不作为 task 主状态事实源。
+- 2026-04-06：已补最小回归测试集。
+  - 新增 `tests/test_task_engine.py`
+  - 新增 `tests/test_retry_meta.py`
+  - 新增 `tests/test_task_actions.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 7 个测试全部通过。
+- 2026-04-06：已继续收口 `task_actions` 的写路径。
+  - `rebind_session_full_video_action()` 不再重复 upsert session binding。
+  - `merge_session_action()` 在继承 `full_video_bvid` 时已复用统一持久化路径。
+  - 已补对应测试，当前测试数为 8，全部通过。
+- 2026-04-06：已补第二层状态流转测试。
+  - 新增 `tests/test_task_policies.py`
+  - 新增 `tests/test_task_runner.py`
+  - 已覆盖 disabled step fallback、publish 重试调度、reset 后回退状态、step claim 后 task 进入 `running`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 12 个测试全部通过。
+- 2026-04-06：已完成一轮 API 代码清理。
+  - `api_server.py` 新增批量 task payload 组装 helper。
+  - `/tasks` 与 `/sessions/:session_key` 已复用同一套 task payload 预取与组装逻辑。
+  - 已重新执行测试，当前 12 个测试全部通过。
+- 2026-04-06：已整理专业化路线图。
+  - 新增 `docs/professionalization-roadmap-2026-04-06.md`
+  - 按平台边界、领域模型、接口契约、测试体系、运维成熟度五个维度拆解后续改进方向。
+  - 已明确下一批优先项为 adapter 边界、session/delivery 领域服务收敛、serializer 层、SQLite/API 测试与 OpenAPI 对齐。
+- 2026-04-06：已开始落最小 adapter 边界。
+  - 新增 `infra/adapters/codex_cli.py`
+  - 新增 `infra/adapters/biliup_cli.py`
+  - 新增 `infra/adapters/bilibili_api.py`
+  - `codex`、`biliup_cli`、`bilibili_top_comment`、`bilibili_collection` provider 已改为依赖 adapter
+  - 已执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已开始落 serializer 层。
+  - 新增 `app/serializers.py`
+  - task list / task detail / session detail 的 payload 组装已从 `api_server.py` 抽到 `ControlPlaneSerializer`
+  - `api_server.py` 进一步收敛为路由、鉴权和响应控制
+  - 已执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已继续收口 serializer 层。
+  - task timeline 的组装逻辑已从 `api_server.py` 抽到 `ControlPlaneSerializer.timeline_payload()`
+  - `api_server.py` 中 task 详情相关展示逻辑继续变薄
+  - 已重新执行 unittest 与 `python -m compileall biliup-next/src/biliup_next`，当前验证通过。
+- 2026-04-06：已补 serializer 层测试。
+  - 新增 `tests/test_serializers.py`
+  - 已覆盖 task payload、session payload、timeline payload 的控制面展示契约
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 15 个测试全部通过。
+- 2026-04-06：已补 repository 的 SQLite 集成测试。
+  - 新增 `tests/test_task_repository_sqlite.py`
+  - 已覆盖 `query_tasks`、批量 context/steps 查询、`session_bindings` upsert 与 fallback 读取
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 18 个测试全部通过。
+- 2026-04-06：已补 API 行为测试。
+  - 扩展 `tests/test_api_server.py`
+  - 已覆盖 `GET /tasks`、`GET /tasks/:id/timeline`、`GET /sessions/:session_key`、`PUT /settings`
+  - 已覆盖 control token 鉴权分支
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+- 2026-04-06：已继续补执行面 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /tasks`、`POST /tasks/:id/actions/run`、`POST /tasks/:id/actions/retry-step`、`POST /tasks/:id/actions/reset-to-step`
+  - 已覆盖写操作成功分支与 `missing step_name` 参数校验
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 28 个测试全部通过。
+- 2026-04-06：已补人工干预相关 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /tasks/:id/bind-full-video`、`POST /sessions/:session_key/rebind`、`POST /sessions/:session_key/merge`、`POST /webhooks/full-video-uploaded`
+  - 已覆盖成功分支、参数校验，以及 `TASK_NOT_FOUND/SESSION_NOT_FOUND` 的状态码映射
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 37 个测试全部通过。
+- 2026-04-06：已补运行面 API 行为测试。
+  - `tests/test_api_server.py` 已新增 `POST /worker/run-once`、`POST /scheduler/run-once`、`POST /runtime/services/:name/:action`、`POST /stage/import`
+  - 已覆盖 action record 落库、副作用返回值、`invalid action` 和 `missing source_path` 错误分支
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 43 个测试全部通过。
+- 2026-04-06：已补剩余控制面 GET 与上传接口测试。
+  - `tests/test_api_server.py` 已新增 `GET /history`、`GET /modules`、`GET /scheduler/preview`、`GET /settings/schema`、`POST /stage/upload`
+  - `stage/upload` 成功分支已通过 patch `cgi.FieldStorage` 固定最小 handler 契约，避免 multipart 解析细节导致测试脆弱
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 49 个测试全部通过。
+- 2026-04-06：已开始收口 session / delivery 领域服务。
+  - 新增 `app/session_delivery_service.py`，承接 `bind/rebind/merge/webhook` 的核心规则与持久化路径
+  - `app/task_actions.py` 已改为薄封装，仅保留 `ensure_initialized()`、审计记录与 service 调用
+  - 新增 `tests/test_session_delivery_service.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 51 个测试全部通过。
+- 2026-04-06：已继续收口 task control 领域服务。
+  - 新增 `app/task_control_service.py`，承接 `run/retry/reset` 编排
+  - `app/task_actions.py` 已进一步变薄，`run_task_action/retry_step_action/reset_to_step_action` 改为纯 service 封装 + 审计
+  - 新增 `tests/test_task_control_service.py`
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 54 个测试全部通过。
+- 2026-04-06：已将 POST 路径分发从 API handler 中下沉。
+  - 新增 `app/control_plane_post_dispatcher.py`，统一承接 POST 路径的用例分发、状态码映射和运行面 action record
+  - `app/api_server.py` 的 `do_POST()` 已收敛为请求解析、dispatcher 调用和响应写出
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 54 个测试全部通过。
+- 2026-04-06：已补 dispatcher 直测。
+  - 新增 `tests/test_control_plane_get_dispatcher.py`
+  - 新增 `tests/test_control_plane_post_dispatcher.py`
+  - 已覆盖 dispatcher 层的状态码映射、过滤逻辑、运行面 action record 与创建任务冲突映射
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 62 个测试全部通过。
+- 2026-04-06：已开始做可迁移交付清理。
+  - `config/settings.json` 与 `config/settings.staged.json` 已替换为 standalone 默认模板，不再携带本机绝对路径和真实密钥
+  - `runtime/cookies.json` 与 `runtime/upload_config.json` 已替换为可分发模板
+  - 新增 `docs/cold-start-checklist.md`
+  - `README.md` 已补充冷启动入口说明
+  - 已执行 `PYTHONPATH=biliup-next/src python -m unittest discover -s biliup-next/tests -v`
+  - 当前 63 个测试全部通过。