xiaoxia-saas/docs/SAAS-UPGRADE-EXECUTION-CHECKLIST.md

# 小虾 SaaS 升级执行检查清单

> 对应路线图：`docs/SAAS-FUNCTION-UPGRADE-ROADMAP.md`  
> 状态：生效中  
> 制定时间：2026-06-23  

---

## 1. 通用开工检查

每个开发包开工前必须完成：

- [ ] 已读取核心规则文档和当前路线图。
- [ ] 已确认当前工作属于哪个阶段、哪个模块。
- [ ] 已确认不会偏离 Clean Architecture。
- [ ] 已确认是否涉及数据库迁移。
- [ ] 已确认是否涉及生产发布。
- [ ] 已确认是否涉及权限边界。
- [ ] 已确认未实现功能不会在 UI 中假装可用。

---

## 2. 每个开发包的标准交付物

### 2.1 需求

- [ ] 写清楚用户是谁。
- [ ] 写清楚用户要完成什么任务。
- [ ] 写清楚当前痛点。
- [ ] 写清楚本开发包不做什么。
- [ ] 写清楚验收标准。

### 2.2 架构

- [ ] 明确 Domain 对象。
- [ ] 明确 Application Use Case。
- [ ] 明确 Ports 接口。
- [ ] 明确 Adapters 实现。
- [ ] 明确 API 路由。
- [ ] 明确 Worker 任务，如适用。

### 2.3 数据

- [ ] 明确新增表或字段。
- [ ] 明确字段归属 workspace/project/library/asset/task/result。
- [ ] 明确索引。
- [ ] 明确迁移脚本。
- [ ] 明确回滚或兼容策略。

### 2.4 API

- [ ] 明确请求方法和路径。
- [ ] 明确请求参数。
- [ ] 明确响应结构。
- [ ] 明确错误码。
- [ ] 明确鉴权要求。
- [ ] 明确 workspace/project/member 权限校验。

### 2.5 前端

- [ ] 明确页面入口。
- [ ] 明确主要状态。
- [ ] 明确加载中、空状态、失败状态。
- [ ] 明确按钮可用/禁用条件。
- [ ] 明确错误文案必须说人话。
- [ ] 明确直接 URL/刷新后的上下文恢复方式。

### 2.6 测试

- [ ] 单元测试覆盖核心 Use Case。
- [ ] 集成测试覆盖 API 正常路径。
- [ ] 集成测试覆盖权限边界。
- [ ] 前端 type-check 通过。
- [ ] 前端 build 通过。
- [ ] 生产 smoke 覆盖用户主链路。

### 2.7 发布

- [ ] develop 分支干净。
- [ ] CI 通过。
- [ ] tag 发布触发。
- [ ] runtime-builder 构建成功。
- [ ] 生产 API/Worker/Web 健康。
- [ ] 公开域名 smoke 通过。
- [ ] 记录版本号和回滚点。

---

## 3. 开发包 1：生产 UAT 问题清零与能力冻结

- [x] 浏览器登录（公网自动 auth smoke 已通过，人工浏览器待老大确认）。
- [x] 创建或进入工作空间（公网自动 smoke 已通过）。
- [x] 创建或进入项目（公网自动 smoke 已通过）。
- [x] 创建素材库（公网自动 smoke 已通过）。
- [x] 批量上传素材（公网 batch/upload smoke 已通过）。
- [x] 查看上传结果（公网 ingest smoke 已通过）。
- [x] 发起生成任务（公网 generation smoke 已通过）。
- [x] 查看生成进度（公网 generation smoke 已通过）。
- [x] 下载成片（公网 MP4 下载 smoke 已通过）。
- [ ] 截图记录所有异常（人工浏览器 UAT 时执行）。
- [x] 查询对应 API 响应。
- [x] 查询对应 Worker/API 日志。
- [x] 更新当前发布表面文档。

验收：真实用户可以完整完成一次生成并下载。

---

## 4. 开发包 2：素材智能视图与缺口诊断

- [x] 设计素材分类字段。
- [x] 设计风险分和质量分字段。
- [x] 设计使用次数和最近使用字段。
- [x] 设计复核状态字段。
- [x] 增加分类 Worker 流程。
- [x] 增加智能视图 API。
- [x] 增加素材诊断 API。
- [x] 前端素材页增加筛选标签。
- [x] 前端素材页增加统计摘要。
- [x] 前端增加素材诊断面板。
- [x] 生成页接入素材诊断与 critical 缺口拦截。
- [x] API 创建生成任务拦截无 ready 视频素材库。
- [x] 测试分类、筛选、诊断、权限边界。
- [x] 生产浏览器 E2E 验证上传诊断与生成下载。
- [x] 生产 API 负向 smoke 验证空视频库生成返回 422。

当前生产基线：`v0.1.39`。开发包 2 自动化主链路已闭环；人工 UAT 可继续验证真实业务素材效果。

验收：系统能回答“素材够不够、缺什么、哪些推荐、哪些慎用”。

---

## 5. 开发包 3：标题库

- [x] 设计标题数据模型。
- [x] 增加标题迁移脚本。
- [x] 增加标题 CRUD API。
- [x] 增加搜索和分类筛选。
- [x] 增加常用标题。
- [x] 增加自动选标题。
- [x] 生成页接入标题库。
- [x] 生成成功后更新使用次数。
- [x] 测试标题权限边界。

验收：用户可以维护标题资产，生成时可手选或自动选择。生产基线：`v0.1.42`，标题库/上传/生成三条浏览器门禁通过。

---

## 6. 开发包 4：成片中心

- [x] 设计成片状态。
- [x] 保存生成参数。
- [x] 生成封面或首帧预览。
- [x] 成片页展示列表。
- [x] 成片页支持预览。
- [x] 成片页支持下载和批量下载。
- [x] 成片页显示失败原因。
- [x] 支持标记可发布或需复核。
- [x] 测试成片权限边界。

验收：用户能管理历史成片并判断是否可发布。生产基线：`v0.1.45`，标题库/上传/成片中心三条浏览器门禁通过。

---

## 7. 开发包 5：任务中心

- [x] 统一任务模型。
- [x] 统一任务状态。
- [x] 保存进度和当前步骤。
- [x] 保存失败类型和原始错误。
- [x] 保存用户可读错误提示。
- [x] 前端增加任务中心。
- [x] 失败任务支持重试。
- [x] 测试任务权限边界。

验收：任何失败都能解释并可按规则重试。生产基线：`v0.1.48`，标题库/上传/生成/任务中心三条浏览器门禁通过。

---

## 8. 开发包 6：模板与剪辑计划

- [x] 设计模板模型。
- [x] 设计 EditPlan。
- [x] 设计 EditPlanClip。
- [x] 实现自动选片。
- [x] 前端增加剪辑计划预览。
- [x] 用户确认后执行生成。
- [x] 生成结果绑定模板和计划。
- [x] 测试模板权限边界。

验收：用户能看到系统准备怎么剪，再确认生成。生产基线：`v0.1.50`，标题库/上传/剪辑计划/生成/成片中心浏览器门禁通过。

---

## 9. 开发包 7：智能增强

- [ ] ASR 字幕能力设计。
- [ ] TTS 配音能力设计。
- [ ] BGM 混音能力设计。
- [ ] 转场包装能力设计。
- [ ] 脚本到剪辑计划能力设计。
- [ ] 未配置外部能力时 UI 禁用或显示暂未开放。
- [ ] 测试外部服务缺失时的降级行为。

验收：智能能力真实可用，不配置时不假装可用。

---

## 10. 开发包 8：权限、安全与商业化底座

- [ ] 扫素材列表权限。
- [ ] 扫成片下载权限。
- [ ] 扫生成任务权限。
- [ ] 扫标题库权限。
- [ ] 扫任务日志权限。
- [ ] 细化 workspace 成员角色。
- [ ] 增加操作审计。
- [ ] 设计配额体系。
- [ ] 订阅和账单继续保持暂未开放，直到后端完整。

验收：多人使用不越权，资源可计量。

---

## 11. 收口规则

每个开发包结束前必须回答：

1. 用户能完成什么新能力？
2. 哪些入口仍然暂未开放？
3. 哪些 API 加了权限边界？
4. 哪些失败提示已经变成人话？
5. 哪些测试和 smoke 已通过？
6. 当前生产版本是多少？
7. 回滚目标是什么？