# 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 可以完整观察任务
- 旧脚本不再是主入口