feat: professionalize control plane and standalone delivery

docs/professionalization-roadmap-2026-04-06.md

@@ -0,0 +1,178 @@
+# biliup-next Professionalization Roadmap - 2026-04-06
+
+## 目标
+
+把 `biliup-next` 从“方向正确的重构工程”推进到“边界清晰、契约稳定、可持续演进的专业级本地控制面系统”。
+
+本路线图以当前仓库中已经明确吸收的 OpenClaw 设计哲学为参照：
+
+- modular monolith
+- control-plane first
+- schema-first
+- manifest-first
+- registry over direct coupling
+- single source of truth
+
+重点不是重复这些口号，而是把它们继续落实到真实代码和工程制度中。
+
+## 维度一：平台边界
+
+### 当前差距
+
+- provider 内仍大量直接调用 `subprocess` 和 `requests`
+- adapter / provider / module service 的边界还不够硬
+- 外部依赖的超时、重试、错误翻译和观测没有统一制度
+
+### 目标状态
+
+- 外部命令和外部 HTTP 都通过稳定 adapter 层进入系统
+- provider 只消费标准化 adapter 能力和统一错误语义
+- 超时、重试、限流、日志和诊断在 adapter 层具备统一约束
+
+### 改进事项
+
+- 为 `ffmpeg`、`codex`、`biliup`、Bili API、Groq 定义统一 adapter 接口
+- 将 provider 中的直接 `subprocess.run()` 和 `requests` 逐步下沉到 adapter
+- 统一 adapter 错误模型，减少 provider 自己拼接临时错误码
+- 为 adapter 增加可观测上下文，例如 command name、target、duration、attempt
+
+### 完成标志
+
+- 业务模块不再直接拼 shell/http 调用
+- adapter 成为唯一外部依赖入口
+
+## 维度二：领域模型
+
+### 当前差距
+
+- 核心规则分散在 `task_engine`、`task_policies`、`task_actions`、provider 和部分工作区文件
+- 文档已有 domain model，但还没有形成更稳定的应用服务/领域服务边界
+- `task`、`session`、`full_video_bvid` 这类跨模块关系仍有隐式规则
+
+### 目标状态
+
+- task lifecycle、retry policy、session binding、delivery side effects 都有清晰归属
+- 领域规则主要存在于少数稳定模块，而不是散落在控制器和 provider 中
+- “谁负责写什么状态”有明确制度
+
+### 改进事项
+
+- 明确 `Task`、`TaskContext`、`SessionBinding` 的边界和 ownership
+- 把 `full_video_bvid`、session 归并、评论/合集副作用收敛成独立领域服务
+- 评估是否引入显式 domain event 或最小事件记录层
+- 为状态迁移建立更显式的 transition table 或 policy object
+
+### 完成标志
+
+- 关键规则不再分散在多个入口函数中重复实现
+- task/session/delivery 的事实源和写入职责稳定
+
+## 维度三：接口契约
+
+### 当前差距
+
+- API handler 仍承担较多 payload 组装和视图拼接工作
+- OpenAPI 与真实控制面细节还不够同步
+- 内部领域模型与外部 API 视图没有充分分层
+
+### 目标状态
+
+- API 对外暴露稳定 DTO，而不是直接拼内部模型
+- handler 更薄，组装逻辑集中在 service / presenter / serializer 层
+- 契约变更可追踪、可校验
+
+### 改进事项
+
+- 为 task detail、task list、session detail、timeline 建立稳定 serializer
+- 清理 API handler 中的重复组装逻辑
+- 更新 `docs/api/openapi.yaml`，让其覆盖真实控制面接口
+- 明确哪些字段属于内部实现细节，不直接暴露给前端
+
+### 完成标志
+
+- handler 只做路由、鉴权、输入解析和响应返回
+- API 文档与真实返回结构保持同步
+
+## 维度四：测试体系
+
+### 当前差距
+
+- 已有最小回归测试，但仍偏重纯逻辑
+- repository、API、provider 契约、端到端场景覆盖不足
+
+### 目标状态
+
+- 核心编排、存储、API、adapter 都有分层测试
+- 关键重构不需要依赖手工回归
+
+### 改进事项
+
+- 新增 repository 的 SQLite 集成测试
+- 为 API handler 增加最小接口行为测试
+- 为 adapter/provider 增加契约测试和失败场景测试
+- 保留现有纯逻辑 unittest，继续增加 smoke 回归脚本
+
+### 完成标志
+
+- 至少形成：
+  - 逻辑单元测试
+  - SQLite 集成测试
+  - API 行为测试
+  - smoke / regression 流程
+
+## 维度五：运维成熟度
+
+### 当前差距
+
+- 已有 doctor、logs、systemd 控制和 workspace 隔离
+- 但健康度、指标、审计、恢复机制还不够体系化
+
+### 目标状态
+
+- 控制面不仅能“看到状态”，还能帮助判断风险和恢复问题
+- 运行问题可以靠结构化信号而不是人工翻日志定位
+
+### 改进事项
+
+- 区分 health / readiness / degraded
+- 规范结构化日志字段
+- 为 task/step 增加最小指标视图
+- 完善审计事件分类
+- 明确数据库/配置变更/运行资产的迁移与回滚流程
+
+### 完成标志
+
+- 常见运行问题可以靠控制面和标准日志定位
+- 关键操作具备审计和回滚说明
+
+## 推荐优先顺序
+
+1. 平台边界
+2. 领域模型
+3. 接口契约
+4. 测试体系
+5. 运维成熟度
+
+## 下一批优先项
+
+### Priority A
+
+- 为 `biliup`、Bili API 和 `codex` 建立统一 adapter 边界
+- 把 `task_actions` 中与 session/delivery 相关的规则继续抽成稳定服务
+- 为 task list / task detail / session detail 提供 serializer 层
+
+### Priority B
+
+- 新增 repository SQLite 集成测试
+- 新增 API 行为测试
+- 更新 OpenAPI 契约
+
+### Priority C
+
+- 设计 health/readiness/degraded 模型
+- 规范日志和审计字段
+
+## 备注
+
+- 这份路线图描述的是“距离专业化还有哪些结构性工作”，不是说当前系统不可用。
+- 当前项目已经具备正确方向；接下来的重点是把设计哲学继续固化为代码边界、测试制度和运维约束。