# Phase 9: 智能自动剪辑与内容增强设计

> 状态：规划中  
> 前置：Phase 8 模板编排引擎上线并通过公网 smoke  
> 原则：能力逐项真实接入，未接入能力不得在 UI 中假装可用

## 一、目标

Phase 9 的目标是把 Phase 8 的规则模板自动剪辑，升级为带字幕、配音、BGM、转场和内容理解的智能自动剪辑 2.0。

一句话：用户输入剪辑目标或脚本，系统自动理解素材、生成剪辑计划、补字幕/配音/BGM，并输出可下载成片。

## 二、不做范围

- 不做无门禁的外部 AI 大模型调用。
- 不做真实支付前的计费扣费闭环。
- 不做未经审核的公网模板市场。
- 不把“实验能力”包装为稳定生产功能。

## 三、核心能力

1. 字幕能力
   - ASR 转写音频。
   - 生成 SRT/VTT。
   - FFmpeg 烧录字幕或输出外挂字幕。

2. 配音能力
   - TTS 生成配音音频。
   - 音频与视频时长对齐。
   - SMTP 仍保持独立，不与 TTS 混用配置。

3. BGM 与音频混合
   - BGM 资源库。
   - 自动音量 ducking。
   - 视频原声、配音、BGM 三轨混合。

4. 转场与包装
   - 基础转场：淡入淡出、交叉溶解、硬切。
   - 片头/片尾占位。
   - Logo/水印可配置。

5. 智能脚本到剪辑计划
   - 用户输入脚本/主题。
   - 系统提取段落、关键词、时长目标。
   - 匹配素材分类与标签。
   - 生成 `EditPlan`。

## 四、架构设计

### Domain

- `Transcript`
- `SubtitleTrack`
- `VoiceoverTrack`
- `MusicTrack`
- `AudioMixPlan`
- `ScriptBrief`
- `ContentIntent`

### Ports

- `SpeechToTextService`
- `TextToSpeechService`
- `MusicRepository`
- `ContentUnderstandingService`
- `SubtitleRenderer`
- `AudioMixer`

### Application Use Cases

- `CreateTranscriptUseCase`
- `GenerateSubtitleUseCase`
- `CreateVoiceoverUseCase`
- `CreateAudioMixPlanUseCase`
- `CreateEditPlanFromScriptUseCase`
- `RenderEnhancedVideoUseCase`

### Adapters

- ASR/TTS 适配器必须配置驱动。
- 缺少凭证时只能返回明确未配置错误，不 fallback 假数据。
- FFmpeg audio/video renderer 负责真实合成。

### API

- `POST /api/v1/transcripts`
- `GET /api/v1/transcripts/{id}`
- `POST /api/v1/subtitles`
- `POST /api/v1/voiceovers`
- `POST /api/v1/audio-mix-plans`
- `POST /api/v1/edit-plans/from-script`

## 五、配置与环境

- 新增外部服务配置必须进入 `.env.example`、`docs/CONFIGURATION.md`、release env validation。
- CI 不依赖真实外部 ASR/TTS 凭证。
- 真实外部 smoke 仅在配置完整的 staging/production 上运行。
- 生产仍使用独立 production DB/Redis/Generated 路径。

## 六、数据与任务

- 长任务全部走 Celery Worker。
- 每个增强步骤必须有可查询状态和错误信息。
- 任务状态禁止只靠前端轮询猜测。
- 生成文件必须持久化到 OSS 或 production generated 路径。

## 七、前端页面

- 生成页增加“智能生成”模式。
- 新增脚本输入区域。
- 新增字幕/配音/BGM 开关。
- 未配置能力显示“服务未配置/暂未开放”。
- 结果页显示字幕、配音、BGM、转场使用情况。

## 八、安全与权限

- 所有 workspace/project/media/generation/enhancement API 必须校验 workspace 权限。
- 上传和生成需限制文件大小、类型和任务频率。
- 外部 AI 请求不得记录用户原文到公开日志。
- 不打印密钥，只显示 configured/missing 状态。

## 九、测试与验收

### 单元测试

- ASR/TTS adapter 配置缺失行为。
- 字幕时间轴生成。
- 音频混合计划。
- 脚本到 edit plan 的确定性规则。

### 集成测试

- 上传视频 → 生成 transcript → 字幕 → edit plan → enhanced generation。

### 公网 smoke

- 使用一段小视频和短脚本。
- 输出 MP4。
- 验证 `video/mp4`、文件头、生成任务 completed、字幕/音轨 metadata。

## 十、发布门禁

- 所有新增能力必须有 feature flag 或配置门禁。
- 没配置外部服务时 UI 显示未配置，不显示假成功。
- Alembic、pytest、前端 type-check/build、公网 smoke 全部通过。
- 生产部署继续禁止生产机前端构建。

## 十一、里程碑

1. Week 1：字幕/ASR 数据模型、任务状态、配置门禁。
2. Week 2：TTS 配音与音频混合计划。
3. Week 3：BGM/转场/水印真实 FFmpeg 合成。
4. Week 4：脚本到剪辑计划、前端智能生成入口。
5. Week 5：公网 smoke、监控、发布。