# 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、发布。