biliup-next/docs/migration-plan.md

Migration Plan

Goal

在不破坏原项目运行的前提下，逐步将能力迁移到 biliup-next。

Migration Principles

• 原项目继续作为生产系统运行
• 新项目只在 ./biliup-next 中演进
• 先文档、后骨架、再迁移功能
• 先控制面，后数据面
• 先兼容旧目录结构，再逐步替换旧入口

Phase 0: Documentation Baseline

目标：

• 明确设计原则
• 明确架构分层
• 明确领域模型
• 明确配置系统和插件系统

产物：

• vision.md
• architecture.md
• domain-model.md
• design-principles.md
• config-system.md
• plugin-system.md
• state-machine.md
• module-contracts.md
• migration-plan.md

Phase 1: Project Skeleton

目标：

• 建立 biliup-next/src 目录结构
• 建立基础 Python 包
• 建立最小配置系统
• 建立 SQLite 存储层
• 建立任务模型和状态模型

不做：

• 不迁移业务逻辑
• 不接管生产入口

Phase 2: Control Plane MVP

目标：

• 提供最小 API
• 提供任务列表和配置读取能力
• 提供最小 CLI
• 提供 health / logs / settings / tasks 查询能力

产物：

• API server
• config service
• task repository
• runtime doctor

Phase 3: Data Plane Adapters

目标：

• 把旧系统依赖的外部能力封装成 adapter

优先顺序：

1. ffmpeg adapter
2. Groq adapter
3. Codex adapter
4. biliup adapter
5. Bili API adapter

理由：

• 先封装外部依赖，后迁移业务模块，能减少后续反复返工

Phase 4: Module Migration

按顺序迁移业务模块。

4.1 Ingest

• 替代 monitor.py 的任务创建部分

4.2 Transcribe

• 替代 video2srt.py

4.3 Song Detect

• 替代 monitorSrt.py

4.4 Split

• 替代 monitorSongs.py

4.5 Publish

• 替代 upload.py

4.6 Comment

• 替代 session_top_comment.py

4.7 Collection

• 替代 add_to_collection.py

Phase 5: Parallel Verification

目标：

• 新旧系统并行验证
• 新系统只处理测试任务
• 对比产物、日志、状态和 B 站结果

重点检查：

• 字幕结果
• 歌曲识别结果
• 切片结果
• 上传结果
• 评论和合集结果

Phase 6: Admin UI

目标：

• 构建本地控制台

第一版包含：

• 配置页
• 任务页
• 模块页
• 日志页
• 手动操作页

Phase 7: Cutover

目标：

• 新系统逐步接管生产入口

顺序建议：

1. 只接管任务可视化
2. 接管配置管理
3. 接管测试任务处理
4. 接管单模块生产流量
5. 最终接管全部生产流量

Risks

Risk 1: 旧系统与新系统语义不一致

缓解：

• 先定义领域模型和状态机
• 迁移前写适配层，不直接照抄旧脚本行为

Risk 2: 边迁移边污染旧项目

缓解：

• 所有新内容只放在 ./biliup-next
• 不改原项目运行入口

Risk 3: UI 先行导致底层不稳

缓解：

• 先做控制面模型和 API
• 最后做 UI

Definition Of Done

迁移完成的标准不是“代码搬完”，而是：

• 新系统可以独立运行
• 配置统一管理
• 状态统一落库
• UI 可以完整观察任务
• 旧脚本不再是主入口