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

## 备注

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