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

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 模型
• 规范日志和审计字段

备注

• 这份路线图描述的是“距离专业化还有哪些结构性工作”，不是说当前系统不可用。
• 当前项目已经具备正确方向；接下来的重点是把设计哲学继续固化为代码边界、测试制度和运维约束。