init biliup-next

docs/migration-plan.md

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