xiaoxia-saas/docs/PHASE9-DESIGN.md

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