# 11 · 实施路线图与里程碑

## 0. 总原则

- **单人/小团队起步**: 前 2 个月目标是把 MVP 跑通,而不是造全部功能
- **端到端优先**: 每个里程碑都要有可演示的用户价值,而不是只补基础设施
- **吸收 > 重造**: 有现成开源代码/提示词/skill 的地方直接搬,不要重新发明
- **前端保留原型**: `doc/html` 作为 UI 底稿,只做必要的接入层改造(加 TanStack Query + Zustand),不重写 UI

## 1. 里程碑总览

| 阶段 | 周期 | 目标 | 产出 |
|------|------|------|------|
| **M0 · 基建** | 第 1~2 周 | 工程骨架跑通 | 空 API + Swagger + Docker |
| **M1 · 认证与项目 CRUD** | 第 3~4 周 | 用户能登录、建项目 | Dashboard + NewProject 可用 |
| **M2 · 剧本解析流水线** | 第 5~7 周 | 上传剧本 → 出角色/分集 | 四步导入 UI + 异步任务 |
| **M3 · 资产生成** | 第 8~10 周 | 角色四视图 + 场景 + 道具 | Character/Scene/Props 可用 |
| **M4 · 分镜工作台** | 第 11~13 周 | AI 生成分镜 + 手动编辑 | StoryboardWorkspace 可用 |
| **M5 · 视觉生成** | 第 14~16 周 | 首尾帧 + 视频生成 | 单镜头视频可生成 |
| **M6 · 合成与导出** | 第 17~18 周 | FFmpeg 拼成完整集 | 可下载完整 MP4 |
| **M7 · 计费与 SaaS** | 第 19~21 周 | 余额、订阅、支付 | 真正 SaaS 化 |
| **M8 · 团队协作** | 第 22~24 周 | 多人协作、资产库、权限 | 企业功能 |
| **M9 · 上线与优化** | 第 25~26 周 | 压测、监控、灰度 | 生产发布 |

**总计约 6 个月**(1~2 名后端 + 1 名前端,MVP 可提前到 3 个月但砍 M7~M9)。

## 2. 阶段详解

### M0 · 基建(第 1~2 周)

**交付清单**:
- [ ] Maven 多模块骨架(按 05-后端架构设计.md 的模块划分)
- [ ] Spring Boot 3 + Spring AI Alibaba 依赖跑通
- [ ] Flyway 初始化 + 空表结构
- [ ] Docker Compose 一键启动(mysql + redis-stack + rabbitmq;对象存储直连开发环境 OSS Bucket)
- [ ] Actuator + Prometheus endpoint
- [ ] Swagger / OpenAPI 自动文档
- [ ] 统一异常处理 + ApiResponse<T> 包装
- [ ] Logback JSON + MDC(requestId)
- [ ] GitHub Actions: PR 跑 test + build
- [ ] 前端 `doc/html` 接入 TanStack Query + Zustand + API client

**完成标准**: `docker compose up` 后能访问 Swagger UI 并看到 1 个 `/ping` 接口。

### M1 · 认证与项目 CRUD(第 3~4 周)

- [ ] Sa-Token 1.39+(`sa-token-spring-boot3-starter` + `sa-token-redis-jackson`),Token 存 Redis
- [ ] `/auth/*` 全套(注册/登录/刷新/登出/me)
- [ ] IP 登录限流(Bucket4j + Redis)
- [ ] Tenant 自动创建(注册即建个人租户)
- [ ] `TenantContextFilter` + MyBatis-Plus `TenantLineInnerInterceptor`
- [ ] Projects 表 + CRUD API
- [ ] `/projects/stats` 统计接口
- [ ] 前端 Dashboard + NewProject 真实接入(去 mock)
- [ ] 前端 Auth Guard

**完成标准**: 用户注册→登录→创建一个空项目→在 Dashboard 看到它。

### M2 · 剧本解析流水线(第 5~7 周)

- [ ] 文件上传 + 阿里云 OSS / 火山引擎 TOS 接入(`StorageProvider` 抽象接口,MinIO 作为未来 TODO 备选)+ MediaObject 表
- [ ] 文本抽取(POI + PDFBox,支持 txt/doc/docx/pdf/md)
- [ ] RabbitMQ 接入 + Task 表 + TaskService + 通用 Worker 模板
- [ ] Spring AI Alibaba 通义千问接入(chat/embedding)
- [ ] `SkillLoader` + 从 Toonflow 拷贝的 `script_execution_skeleton.md`
- [ ] 实现 Executor: `ScriptParseExecutor` + `CharacterExtractExecutor` + `EpisodeSplitExecutor`
- [ ] 四步导入 API + SSE 进度
- [ ] 前端 NewProject 的四步向导(借鉴 AIComicBuilder UX)
- [ ] Character/Scene/Props 表 + 基础 CRUD

**完成标准**: 上传一篇 5000 字的小说,能自动出角色列表和分集列表,全程 SSE 推进度。

### M3 · 资产生成(第 8~10 周)

- [ ] `AiProvider` 接口 + `WanxImageProvider`(通义万相文生图)
- [ ] 兜底 Provider: OpenAI DALL-E 或 Gemini Imagen(可配置)
- [ ] 从 Toonflow 拷 `art_skills/2d_anime/` 全套艺术手册
- [ ] `CharacterTurnaroundExecutor`(四视图,借鉴 AIComicBuilder)
- [ ] `SceneImageExecutor` / `PropImageExecutor`
- [ ] `shot_assets` 表 + 资产版本管理
- [ ] 前端 CharacterGeneration / SceneGeneration / PropsGeneration 页接入
- [ ] 参考图上传 + 注入到生成请求
- [ ] 初级计费(SOFT 模式)

**完成标准**: 项目里每个角色都能一键生成四视图,前端能看到并支持重新生成。

### M4 · 分镜工作台(第 11~13 周)

- [ ] `Storyboard` 表完整字段(参考 AIComicBuilder shot 结构)
- [ ] `DirectorPlanExecutor`(借鉴 Toonflow 导演手册)
- [ ] `StoryboardSplitExecutor`(借鉴 AIComicBuilder shot-split.ts)
- [ ] `SupervisionAgent` 雏形(可选开关)
- [ ] Storyboard CRUD + 批量生成 + 排序 + 复制
- [ ] 前端 StoryboardWorkspace 完整接入
- [ ] 拖拽排序 API(批量 sequence 更新)
- [ ] AI 合规检查 API(调 LLM 做敏感词+内容审核)

**完成标准**: 某集的全部分镜可一键 AI 生成,然后用户可手动编辑每个镜头。

### M5 · 视觉生成(第 14~16 周)

- [ ] `FrameGenerateExecutor`(首尾帧,参考图注入)
- [ ] `VideoProvider` 接口 + `WanxVideoProvider`
- [ ] 备选: SeedanceProvider / KlingProvider
- [ ] `VideoGenerateExecutor`(异步提交 + 轮询)
- [ ] 任务心跳机制上线
- [ ] 失败重试 + Provider fallback
- [ ] 前端 StoryboardWorkspace 右侧预览接入
- [ ] 前端 VideoGeneration 页面接入(分镜网格状态)

**完成标准**: 选中一个分镜,点"生成视频",10 分钟内能看到 5~8 秒短视频,参考图约束生效(角色相对一致)。

### M6 · 合成与导出(第 17~18 周)

- [ ] FFmpeg 调度封装(`FfmpegService`)
- [ ] `AssembleExecutor`:拼接 + 转场 + 字幕 + BGM
- [ ] TTS 接入(Qwen-TTS):`VoiceTtsExecutor`
- [ ] 全集合成 API + 下载链接签名
- [ ] 水印烧录(全局设置)

**完成标准**: 一集的所有分镜生成完成后,点"合成",得到一个带字幕、配音、BGM 的完整 MP4。

### M7 · 计费与 SaaS(第 19~21 周)

- [ ] `user_balances` / `balance_freezes` / `balance_transactions` 三表上线
- [ ] `BillingService`(prepare/settle/rollback)集成到所有任务
- [ ] BILLING_MODE=STRICT 切换
- [ ] 订阅表 + 套餐定义
- [ ] 支付宝 + 微信支付接入(Webhook)
- [ ] Stripe(海外)
- [ ] 充值页面 + 订阅页面
- [ ] `/usage/*` 统计 API
- [ ] 前端 UsageManagement 接入
- [ ] 定时任务:过期冻结清理、订阅续费

**完成标准**: 用户能充值、消费会扣积分、余额不足被拦截、流水可查。

### M8 · 团队协作与资产库(第 22~24 周)

- [ ] 项目成员邀请 + RBAC 4 角色
- [ ] 企业员工/小组(`/team` 页)
- [ ] 资产库:个人 + 团队(`global_assets` 表)
- [ ] 资产收藏、复用到项目
- [ ] 通知系统(`notifications` 表 + WebPush 可选)
- [ ] 审计日志(`audit_logs` + `@Audited` 切面)
- [ ] 前端 TeamManagement / AssetsManagement 接入
- [ ] 提示词模板的项目级覆盖 UI

**完成标准**: 团队成员可被邀请到项目,权限隔离正确,资产能跨项目复用。

### M9 · 上线与优化(第 25~26 周)

- [ ] 压测(JMeter/k6)
- [ ] 性能优化(慢 SQL、N+1、缓存)
- [ ] Prometheus + Grafana 监控面板
- [ ] SkyWalking 链路追踪
- [ ] 告警接入钉钉
- [ ] K8s Helm chart
- [ ] 灰度发布方案
- [ ] 运营后台基础(用户/订单查询)
- [ ] 用户文档、API 文档
- [ ] 上线!

## 3. 风险与缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| 通义万相/视频模型配额不足 | 阻塞 M5 | 并行接入 2 家 Provider,签商务合同 |
| 角色一致性效果不达标 | 用户体验差 | 四视图 + 强制命名 + 必要时引入 LoRA 微调 |
| 视频生成单价过高 | 毛利低 | 精确计费、短视频优先、非关键镜头降级 |
| FFmpeg 性能瓶颈 | 合成慢 | Worker 独立扩容 + GPU 编码 |
| 多租户数据泄漏 | 法律风险 | 代码卫士强制 Filter + 自动化测试 |
| Agent 幻觉导致低质产出 | 用户不满 | 监督层 + 用户最终审核 |

## 4. 后续(v2+)想做的事

- 移动端 App(React Native)
- 实时协作编辑分镜(CRDT / Yjs + WebSocket)
- 模型市场(用户上传 LoRA)
- 资产市场(付费分享角色/场景)
- AI 审核合规自动化(全量扫敏感内容)
- 多语言配音(英日韩)
- 真人参考视频驱动(动作迁移)
- 导出到剪映/PR 的 XML 工程
- 开放 API(面向开发者)
