# 小虾 SaaS 功能升级优化路线图

> 状态：生效中  
> 基线版本：v0.1.14  
> 制定时间：2026-06-23  
> 负责人：小虾 🦐  

---

## 1. 背景

旧版桌面剪辑软件已经形成了一套以“剪辑工作台”为核心的本地自动剪辑经验：素材库、智能分类、素材缺口诊断、标题库、批量生成、成片历史、错误诊断与自动修复。

SaaS 版目前已经打通 MVP 主链路：登录、工作空间、项目、素材上传、异步处理、真实 FFmpeg 生成、成片下载、生产发布与基础权限边界。下一阶段的重点不是继续临时堆功能，而是把旧版软件中真正有价值的剪辑经验，按标准化、模块化方式迁移到 SaaS。

---

## 2. 总目标

把小虾 SaaS 从“能上传素材并生成 MP4 的 MVP”升级为“具备素材诊断、标题资产、成片管理、任务追踪、模板编排和智能增强能力的自动剪辑平台”。

核心原则：

1. 文档先行，开发前明确需求、接口、页面、测试、验收、发布。
2. 模块隔离，素材、标题、生成、成片、任务、权限分别设计和验收。
3. 不做假入口，未实现能力必须显示“暂未开放”或禁用。
4. 长任务必须异步，必须有状态、进度、失败原因和重试策略。
5. 每次上线必须通过本地测试、CI、生产 smoke 和真实用户主链路验收。
6. 生产机不得承担构建任务，生产发布必须使用预构建产物和镜像。

---

## 3. 当前基线

### 3.1 已验证生产能力

- 账号注册、登录、登录态清理。
- 工作空间与项目管理。
- 项目级素材库。
- 单文件与批量上传。
- 上传后异步 ingest job。
- 真实 FFmpeg 生成 MP4。
- 成片下载。
- 基础权限边界：匿名、非成员访问项目/素材/上传会被拦截。
- 生产发布链路：runtime-builder 构建，生产机加载镜像和产物。
- 未开放功能显式“暂未开放”。

### 3.2 旧版核心能力差距

- 缺少素材智能视图：推荐、慎用、高风险、未使用、最近使用、待复核。
- 缺少素材准备度和缺口诊断。
- 缺少完整标题库：分类、常用、使用次数、自动选标题。
- 缺少成熟成片历史、封面预览、复核流和批量下载。
- 缺少统一任务中心：上传、分类、生成、下载任务状态与日志。
- 缺少速度/均衡/质量优先、多候选生成和筛选策略。
- 缺少模板驱动的剪辑计划预览。
- 缺少 ASR 字幕、TTS 配音、BGM 混音、转场包装和脚本到剪辑计划。

---

## 4. 阶段路线

### 阶段 0：生产稳定与现状冻结

目标：确认当前 SaaS MVP 稳定可用，避免后续升级带着旧问题滚雪球。

步骤：

1. 固定当前生产基线版本和能力清单。
2. 真实浏览器跑通：登录 → 工作空间 → 项目 → 批量上传 → 生成 → 下载。
3. 收集所有截图、错误文案、卡顿、失败提示。
4. 按账号、项目、素材、任务四个维度定位根因。
5. 更新当前发布表面文档，明确可用和不可用功能。

验收标准：主链路真实用户可完成一次完整生成并下载 MP4。

---

### 阶段 1：旧版功能拆解成 SaaS 模块

目标：把旧版桌面软件能力拆成 SaaS 可开发模块，禁止散落开发。

模块划分：

1. 素材中心：视频素材库、配音素材库、批量上传、素材分类、智能视图、缺口诊断。
2. 标题中心：标题库、标题分类、常用标题、使用次数、自动选标题。
3. 剪辑生成中心：生成模式、生成数量、生成质量、多候选生成、进度、停止、重试。
4. 成片中心：成片列表、封面预览、下载、批量下载、复核状态、生成参数回放。
5. 任务中心：上传任务、分类任务、生成任务、失败原因、日志追踪、可重试。
6. 权限与审计：工作空间成员权限、素材权限、成片权限、任务权限、操作记录。

验收标准：每个旧版功能都有明确 SaaS 模块归属、数据对象、页面入口和验收标准。

---

### 阶段 2：素材中心升级

目标：优先迁移旧版“素材智能诊断”，这是区别普通剪辑工具的核心能力。

步骤：

1. 设计素材扩展字段：素材类型、分类、风险分、质量分、使用次数、最近使用时间、复核状态。
2. 明确分类结果属于 project、asset_library、asset 三层中的哪一层。
3. Worker 上传后自动分类：口播、场景、待复核。
4. 增加智能视图接口：全部、口播、场景、待复核、推荐、慎用、高风险、未使用、最近使用。
5. 前端素材页增加筛选标签、统计摘要和复核状态。
6. 增加素材缺口诊断接口，输出准备度分数、问题、建议。
7. 前端增加“素材诊断”面板。

验收标准：用户上传一批素材后，系统能告诉用户“够不够剪、缺什么、哪些素材慎用、哪些素材推荐使用”。

---

### 阶段 3：标题库升级

目标：把旧版标题库迁移成团队和项目可复用的内容资产。

步骤：

1. 设计标题表：workspace_id、project_id、title、category、favorite、use_count。
2. 后端实现标题增删改查。
3. 实现标题搜索、分类筛选、常用标题。
4. 实现“自动选一个”逻辑：优先常用、低使用次数、匹配项目分类。
5. 生成页接入标题库选择。
6. 生成成功后更新标题使用次数。

验收标准：用户可以维护标题资产，生成时可手选或自动选择标题，不需要每次手填。

---

### 阶段 4：成片中心升级

目标：让生成结果可管理，而不是只生成一个下载链接。

步骤：

1. 设计成片状态：生成中、成功、失败、待复核、可发布。
2. 保存生成参数：素材库、标题、模式、数量、模板、时间。
3. 生成结果增加封面图或首帧预览。
4. 前端成片页展示列表、预览、下载、失败原因。
5. 增加批量下载。
6. 增加“标记为可发布/需复核”。

验收标准：用户能回看历史成片，知道每条视频怎么生成、能不能发布，并可批量处理结果。

---

### 阶段 5：任务中心与错误追踪

目标：所有长任务都可追踪、可解释、可重试。

步骤：

1. 统一任务模型：upload、classify、generate、download/export。
2. 统一状态：queued、running、completed、failed、cancelled。
3. 每个任务保存进度、当前步骤、失败类型、原始错误、用户提示。
4. 前端增加任务中心入口。
5. 失败任务支持重试。
6. 所有用户可见错误都必须映射成人话提示。

验收标准：任何失败都能回答四句话：哪一步失败、为什么失败、能不能重试、用户该怎么办。

---

### 阶段 6：Phase 8 模板与编排引擎

目标：从“黑盒生成视频”升级为“模板驱动的剪辑计划”。

步骤：

1. 设计模板模型：模板名称、场景结构、素材要求、时长规则、标题规则。
2. 设计 EditPlan：一次生成前先形成剪辑计划。
3. 设计 EditPlanClip：每个片段对应素材、开始时间、持续时间、转场、音频。
4. 自动选片：根据素材分类、风险、质量、使用次数选择素材。
5. 前端增加剪辑计划预览。
6. 用户确认后再执行 FFmpeg 生成。
7. 生成结果绑定模板和剪辑计划。

验收标准：用户能看到“系统准备怎么剪”，确认后再生成，而不是黑盒随机生成。

---

### 阶段 7：Phase 9 智能增强

目标：补齐真正智能剪辑能力。

步骤：

1. ASR 字幕：识别配音或视频语音，生成字幕。
2. TTS 配音：文本生成配音，未配置服务时 UI 不开放。
3. BGM 混音：背景音乐、音量 ducking、淡入淡出。
4. 转场包装：片段间转场、片头片尾、水印。
5. 脚本到剪辑计划：输入脚本，生成素材需求和剪辑结构。
6. 智能推荐：根据素材库情况推荐模板和生成策略。

验收标准：小虾从“视频生成工具”升级成“智能剪辑助理”。

---

### 阶段 8：权限、安全与商业化准备

目标：为正式商业 SaaS 做底座。

步骤：

1. 扫权限边界：素材列表、成片下载、生成任务、标题库、任务日志。
2. 工作空间成员权限细化：owner、admin、member、viewer。
3. 操作审计：上传、删除、生成、下载、邀请成员。
4. 配额体系：素材容量、生成次数、并发任务、存储周期。
5. 订阅和账单继续保持“暂未开放”，等后端完整后再启用。

验收标准：多人使用不会越权，资源可计量，后续可接商业化。

---

## 5. 开发包顺序

1. 生产 UAT 问题清零与当前能力冻结。
2. 素材智能视图与素材缺口诊断。
3. 标题库。
4. 成片中心。
5. 任务中心。
6. 模板与剪辑计划。
7. ASR、TTS、BGM、转场智能增强。
8. 权限、审计、配额、商业化底座。

---

## 6. 每个开发包必须交付的内容

每个开发包必须包含：

1. 需求说明。
2. 数据模型设计。
3. API 设计。
4. 前端页面设计。
5. Worker/异步任务设计，如适用。
6. 权限边界说明。
7. 错误提示与失败处理说明。
8. 单元测试和集成测试。
9. 前端 type-check 和 build。
10. 生产 smoke 或手工验收记录。
11. 发布说明和回滚点。

---

## 7. 禁止事项

1. 禁止未设计数据模型就直接写页面。
2. 禁止后端未实现时前端假成功。
3. 禁止把长任务做成同步阻塞接口。
4. 禁止跳过 workspace/project/member 权限校验。
5. 禁止生产机承担 Web/API/Worker 构建。
6. 禁止未经 smoke 就说生产完成。
7. 禁止把旧版功能散落迁移，必须归入模块和开发包。

---

## 8. 最近下一步

立即执行：

1. 完成生产 UAT：登录 → 工作空间 → 项目 → 批量上传 → 生成 → 下载。
2. 记录所有真实问题。
3. 补充 `docs/SAAS-UPGRADE-EXECUTION-CHECKLIST.md`。
4. 开始第一个正式开发包：生产 UAT 问题清零与当前能力冻结。