xiaoxia-saas/docs/PHASE8-DESIGN.md

Phase 8: 自动剪辑模板与编排引擎设计

状态：规划中
基线：Phase 7 已完成上传 → 分类 → 生成 → 下载主链路
原则：Clean Architecture、单一环境真源、生产不构建、未实现不假入口

一、目标

Phase 8 的目标是把当前“用户上传素材后手动发起生成”的 MVP，升级为“按模板自动编排素材并生成成片”的自动剪辑 1.0。

一句话：用户选择项目、素材库和剪辑模板，系统自动选素材、排顺序、生成剪辑计划，并交给 FFmpeg Worker 输出成片。

二、不做范围

• 不做复杂 AI 脚本理解。
• 不做数字人、直播切片、自动带货文案生成。
• 不做真实支付/订阅闭环。
• 不做假模板市场或 mock 运营后台。

三、核心能力

1. 剪辑模板管理

   • 内置模板：基础混剪、产品展示、探店短片、口播素材拼接。
   • 模板字段：比例、目标时长、片段数量、片段时长、分类偏好、转场策略、音乐策略。

2. 自动选片

   • 基于素材分类、质量分、时长、类型筛选候选素材。
   • 生成候选片段列表，不直接修改原素材。

3. 剪辑计划

   • 新增 EditPlan 聚合，保存自动编排结果。
   • 新增 EditPlanClip，描述每个片段的素材、入点、出点、顺序、转场。
   • 生成任务从“直接 FFmpeg”升级为“按 EditPlan 执行 FFmpeg”。

4. 前端工作流

   • 项目生成页新增模板选择。
   • 生成前展示剪辑计划预览。
   • 用户确认后创建生成任务。
   • 不支持的模板能力显示“暂未开放”，不得 fake success。

四、架构设计

Domain

• EditTemplate
• EditPlan
• EditPlanClip
• TemplateKind
• ClipSelectionRule

Ports

• EditTemplateRepository
• EditPlanRepository
• ClipSelector
• EditPlanRenderer

Application Use Cases

• ListEditTemplatesUseCase
• PreviewEditPlanUseCase
• CreateEditPlanUseCase
• CreateGenerationTaskFromEditPlanUseCase

Adapters

• SQLAlchemy repositories 保存模板与剪辑计划。
• Rule-based ClipSelector 先实现确定性选片。
• FFmpeg renderer 根据 EditPlan 拼接视频。

API

• GET /api/v1/edit-templates
• POST /api/v1/edit-plans/preview
• POST /api/v1/edit-plans
• GET /api/v1/edit-plans/{id}
• POST /api/v1/generation/from-edit-plan

五、数据库迁移

新增 Alembic migration：

• edit_templates
• edit_plans
• edit_plan_clips

迁移规则：

• Alembic 是唯一迁移真源。
• 禁止生产自动建表。
• 新字段必须进入 schema guard。

六、前端页面

• ProjectGeneration.tsx

  • 模板选择
  • 参数输入
  • 预览剪辑计划
  • 创建生成任务

• 新增 EditPlanPreview.tsx

  • 片段顺序
  • 素材名
  • 分类标签
  • 预计时长
  • 缺素材提示

七、测试与验收

单元测试

• 模板参数校验。
• 自动选片规则。
• 剪辑计划生成。
• FFmpeg 命令计划生成。

集成测试

• 创建模板 → 上传素材 → 分类 → 预览计划 → 创建计划 → 生成任务。

公网 smoke

• 注册登录。
• 创建工作空间/项目/素材库。
• 上传小视频。
• 创建 edit plan。
• 生成 MP4。
• 下载验证 Content-Type: video/mp4。

八、发布门禁

• npm run type-check
• npm run build
• pytest 覆盖新增 use case/repository/API。
• Alembic preflight 通过。
• 公网 smoke 通过。
• 生产部署继续 artifact/image 模式，生产机器不做前端构建。

九、里程碑

1. Week 1：领域模型、迁移、repository、模板列表 API。
2. Week 2：自动选片与剪辑计划 preview。
3. Week 3：FFmpeg 按 EditPlan 拼接。
4. Week 4：前端生成页接入、smoke、发布。