179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
# 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 模型
|
||
- 规范日志和审计字段
|
||
|
||
## 备注
|
||
|
||
- 这份路线图描述的是“距离专业化还有哪些结构性工作”，不是说当前系统不可用。
|
||
- 当前项目已经具备正确方向；接下来的重点是把设计哲学继续固化为代码边界、测试制度和运维约束。
|