Add current architecture document

2026-06-15 18:13:21 +08:00
parent 7a8191650f
commit b2ae4600b4
2 changed files with 960 additions and 0 deletions
@@ -46,6 +46,7 @@
 - 生产化优化：首条真人短剧一集压测用例整理
 - 生产化优化：首条真人短剧压测项目导入 / Prompt 准备
 - 生产化优化：首条真人短剧 Mock 全链路成片验收
+- 文档梳理：CURRENT_ARCHITECTURE 当前架构快照

 ## 正在进行

@@ -58,6 +59,32 @@

 ## 阶段记录

+### 文档梳理：CURRENT_ARCHITECTURE 当前架构快照
+
+完成时间：2026-06-15 18:13:00 CST
+
+完成内容：
+
+- 扫描后端、用户端、后台端、Worker、Prisma schema 和核心 AI 流水线实现。
+- 生成当前系统整体架构图、核心模块、数据表关系、AI Provider 列表、Router 逻辑、Prompt Builder、Character Library、FFmpeg 流程、已完成功能、待优化功能和关键文件路径。
+- 仅生成文档，不修改业务代码。
+
+修改文件：
+
+- `CODEX_PROGRESS.md`
+
+新增文件：
+
+- `CURRENT_ARCHITECTURE.md`
+
+运行命令：
+
+- 未运行 lint/typecheck/test。本次为文档梳理，不涉及代码逻辑变更。
+
+下一步：
+
+- 继续围绕真人视频生产质量、真实 Provider 准入、角色一致性、BGM/SFX/字幕和队列化失败恢复做验收优化。
+
 ### 阶段 00：读取 docs 并输出开发计划

 完成时间：2026-05-31 17:00:00 CST
@@ -0,0 +1,933 @@
+# Current Architecture
+
+生成时间：2026-06-15  
+扫描范围：`/www/wwwroot/ai` 源码、Prisma schema、前后台入口、Provider/Router/Live Action/Media 实现。
+
+## 1. 系统整体架构图
+
+```text
+用户端 H5 / uni-app
+user-app/src/pages/index/index.vue
+        |
+        | REST API + JWT + 可选加密传输
+        v
+NestJS Backend
+backend/src/app.module.ts
+        |
+        |---------------- Auth / Users / Billing
+        |---------------- Projects / Novels / Story Bible
+        |---------------- Characters / Memories / Episodes
+        |---------------- Scripts / Images / Media
+        |---------------- Live Action / AI Router / Providers
+        |---------------- Reviews / Admin / Queues
+        |
+        v
+MySQL 8
+Prisma schema: backend/prisma/schema.prisma
+        |
+        +--> RenderTask / ProviderLog / OperationLog / Asset
+        |
+        v
+Storage
+local storage: storage/private
+MinIO 预留: backend/src/assets/storage.service.ts
+
+后台管理端
+admin/src/App.vue
+        |
+        | Provider 配置 / Router 审计 / 任务审计 / 用户项目管理
+        v
+NestJS Admin API
+
+Worker 预留
+workers/src/main.ts
+        |
+        | BullMQ 队列 worker 框架
+        v
+Redis / BullMQ
+
+AI Provider 抽象层
+backend/src/providers/providers.service.ts
+        |
+        | mock / OpenAI / DeepSeek / MiniMax / Hailuo / Kling / Runway / Gemini 等
+        v
+第三方 AI 平台
+
+FFmpeg
+        |
+        | 图片/音频/字幕合成 MP4
+        | 真人视频片段拼接、裁切、字幕、BGM、SFX、响度归一
+        v
+最终视频 Asset
+```
+
+## 2. 核心模块
+
+### 后端模块
+
+| 模块 | 主要职责 | 关键文件 |
+|---|---|---|
+| Auth / Users | 注册、登录、JWT、RBAC | `backend/src/auth/*`, `backend/src/users/*` |
+| Projects | 项目创建、状态、输入/输出模式 | `backend/src/projects/*` |
+| Assets / Storage | 上传、下载、私有素材、本地/MinIO 存储 | `backend/src/assets/*` |
+| Novels | AI 原创小说、上传小说解析、章节拆分 | `backend/src/novels/*` |
+| Story Bibles | 故事圣经生成/确认 | `backend/src/story-bibles/*` |
+| Characters | 角色抽取、角色确认、角色锚点、全局角色关联 | `backend/src/characters/*` |
+| Memories | 长篇记忆、剧情线 | `backend/src/memories/*` |
+| Episodes | 分集计划生成/确认 | `backend/src/episodes/*` |
+| Scripts | 单集脚本、分镜脚本 | `backend/src/scripts/*` |
+| Images | 分镜图、角色图 mock/Provider 抽象 | `backend/src/images/*` |
+| Media | 多角色 TTS、字幕、普通 FFmpeg 合成 | `backend/src/media/*` |
+| Live Action | 真人短剧：演员定妆、真人分镜、关键帧、视频片段、质检、合成 | `backend/src/live-action/*` |
+| AI Router | 镜头评分、自动选 Provider、fallback、成本判断 | `backend/src/ai-router/*` |
+| Providers | Provider 配置、执行、日志、成本、bootstrap | `backend/src/providers/*` |
+| Billing | 额度账户、冻结额度、成本预估 | `backend/src/billing/*` |
+| Reviews | 文本/视频审核、公开案例授权 | `backend/src/reviews/*` |
+| Queues | 任务查询、worker task 入口 | `backend/src/queues/*` |
+| Admin | 后台项目、Provider、日志、审计、Router 视图 | `backend/src/admin/*` |
+| Common | API 响应、异常、加密、中间件、HTTPS 检查 | `backend/src/common/*` |
+
+### 前端模块
+
+| 模块 | 主要职责 | 关键文件 |
+|---|---|---|
+| 用户端制作台 | 创建项目、上传/原创、版权、故事、角色、分集、脚本、真人视频、合成、审核、成品 | `user-app/src/pages/index/index.vue` |
+| 用户端 API Client | 用户端 REST API 封装、错误文案、上传下载、真人视频接口 | `user-app/src/api/client.ts` |
+| 用户端工作流 | 状态标签、进度计算、任务类型显示 | `user-app/src/workflow.ts` |
+| 用户端样式 | 深色运营台风格、单列制作流程、响应式 UI | `user-app/src/styles.css` |
+| 后台端 | Provider 配置、AI 平台入口、Router 审计、任务审计、项目管理 | `admin/src/App.vue` |
+
+### Worker 模块
+
+`workers/src/main.ts` 已有 BullMQ worker 框架，队列名包含：
+
+- `novel_queue`
+- `story_queue`
+- `character_queue`
+- `episode_queue`
+- `script_queue`
+- `storyboard_queue`
+- `image_queue`
+- `audio_queue`
+- `subtitle_queue`
+- `video_queue`
+- `review_queue`
+
+当前大量生成动作仍由 API 同步触发并写 `RenderTask`，队列化已有框架和部分后端队列入口，但仍需要继续把重任务全面迁移到 worker。
+
+## 3. 数据表关系
+
+### 主业务链路
+
+```text
+users
+  └─ projects
+       ├─ novel_sources
+       │    └─ novel_chapters
+       ├─ copyright_records
+       ├─ story_bibles
+       ├─ world_bibles
+       ├─ characters
+       │    ├─ character_images
+       │    └─ character_memories
+       ├─ plot_memories
+       ├─ plot_threads
+       ├─ episodes
+       │    ├─ episode_scripts
+       │    ├─ storyboard_shots
+       │    │    ├─ shot_images
+       │    │    └─ video_clips
+       │    └─ render_tasks
+       ├─ assets
+       ├─ content_reviews
+       ├─ case_showcases
+       ├─ project_creative_patterns
+       └─ analytics_events
+```
+
+### AI/任务/审计链路
+
+```text
+provider_configs
+  ├─ provider_logs
+  └─ render_tasks.provider_id
+
+render_tasks
+  ├─ assets(output_asset_id)
+  ├─ provider_logs(task_id)
+  └─ quota_logs(task_id)
+
+operation_logs
+  └─ target_type + target_id 记录用户/后台/Router 操作轨迹
+
+system_configs
+  └─ ai.router.v1 / security.api_crypto_enabled / current_stage
+```
+
+### 角色库链路
+
+```text
+global_characters
+  └─ global_character_assets
+
+projects
+  └─ characters.global_character_id
+       ├─ character_images
+       └─ actor_profiles
+```
+
+### 爆款诊断 / 模式库
+
+```text
+hit_analysis_cases
+  └─ hit_analysis_segments
+       └─ creative_patterns
+            └─ project_creative_patterns
+```
+
+### 关键表说明
+
+| 表 | 作用 |
+|---|---|
+| `users` | 用户和管理员账号 |
+| `projects` | 项目主表，区分 `ai_original/upload` 和 `image_manga/motion_comic/live_action_ai` |
+| `novel_sources`, `novel_chapters` | 原创/上传小说源和章节 |
+| `story_bibles`, `world_bibles` | 故事圣经、世界观设定 |
+| `characters`, `global_characters` | 项目角色和全局角色库 |
+| `character_images`, `actor_profiles` | 角色锚点图、真人演员定妆 |
+| `episodes`, `episode_scripts`, `storyboard_shots` | 分集、脚本、分镜 |
+| `shot_images` | 分镜图/关键帧 |
+| `video_clips` | 真人视频片段 |
+| `assets` | 私有/公开素材，包括小说、图片、音频、字幕、视频 |
+| `render_tasks` | 生成任务、输入 JSON、成本、错误、输出素材 |
+| `provider_configs` | AI Provider 配置 |
+| `provider_logs` | Provider 调用日志、请求/响应摘要、成本 |
+| `content_reviews` | 文本/视频审核 |
+| `quota_accounts`, `quota_logs` | 用户额度 |
+| `system_configs` | 系统配置，包括 Router 配置 |
+| `operation_logs` | 操作日志和审计时间线 |
+
+## 4. AI Provider 列表
+
+Provider 默认模板来源：
+
+- `backend/src/providers/provider.types.ts`
+- `backend/prisma/seed.ts`
+- `backend/prisma/migrations/20260602130000_domestic_video_providers/migration.sql`
+
+### Mock Provider
+
+| Provider Code | 类型 |
+|---|---|
+| `mock-text` | TextProvider |
+| `mock-novel` | NovelProvider |
+| `mock-image` | ImageProvider |
+| `mock-video` | VideoProvider |
+| `mock-voice` | VoiceProvider |
+| `mock-lipsync` | LipSyncProvider，默认禁用 |
+| `mock-moderation` | ModerationProvider |
+| `mock-qc` | QualityCheckProvider |
+| `mock-file-parse` | FileParseProvider |
+| `mock-embedding` | EmbeddingProvider |
+
+### OpenAI
+
+| Provider Code | 类型 | 默认模型 |
+|---|---|---|
+| `openai-responses-text` | TextProvider | `gpt-5.5` |
+| `openai-responses-novel` | NovelProvider | `gpt-5.5` |
+| `openai-moderation` | ModerationProvider | `omni-moderation-latest` |
+| `openai-embedding` | EmbeddingProvider | `text-embedding-3-small` |
+| `openai-image` | ImageProvider | `gpt-image-2` |
+| `openai-video` | VideoProvider | `sora-2` |
+| `openai-tts` | VoiceProvider | `gpt-4o-mini-tts` |
+
+### 视频 Provider
+
+| Provider Code | 平台/模型 | 默认状态 |
+|---|---|---|
+| `minimax_hailuo_23_fast` | MiniMax Hailuo 2.3 Fast 图生视频 | 默认禁用，当前服务器已启用过 |
+| `minimax_hailuo_23` | MiniMax Hailuo 2.3 图生视频 | 默认禁用 |
+| `alibaba_wan26_i2v_flash` | 阿里 Wan2.6 I2V Flash | 默认禁用 |
+| `alibaba_wan26_i2v` | 阿里 Wan2.6 I2V 标准 | 默认禁用 |
+| `vidu_q3_turbo_reference` | Vidu Q3 Turbo 参考图生视频 | 默认禁用 |
+| `vidu_q3_pro` | Vidu Q3 Pro 参考图生视频 | 默认禁用 |
+| `jimeng_seedance` | 即梦/Seedance 图生视频 | 默认禁用 |
+| `runway-image-to-video` | Runway Image-to-Video | 默认禁用 |
+| `kling-image-to-video` | Kling Image-to-Video | 默认禁用 |
+| `google-veo-video` | Google Veo Video | 默认禁用 |
+| `replicate-video` | Replicate Video | 默认禁用 |
+| `fal-video` | fal.ai Video | 默认禁用 |
+| `luma-ray-video` | Luma Ray Video | 默认禁用 |
+| `pika-video` | Pika Video | 默认禁用 |
+
+### 文本/小说 Provider
+
+| Provider Code | 平台 |
+|---|---|
+| `google-gemini-text`, `google-gemini-novel` | Google Gemini |
+| `anthropic-claude-text`, `anthropic-claude-novel` | Anthropic Claude |
+| `deepseek-text`, `deepseek-novel` | DeepSeek |
+| `qwen-text`, `qwen-novel` | Alibaba Qwen |
+| `kimi-text`, `kimi-novel` | Moonshot Kimi |
+| `zhipu-glm-text`, `zhipu-glm-novel` | 智谱 GLM |
+| `baidu-qianfan-text` | 百度千帆 |
+| `tencent-hunyuan-text` | 腾讯混元 |
+| `iflytek-spark-text` | 讯飞星火 |
+| `volcengine-doubao-text`, `volcengine-doubao-novel` | 火山/豆包 |
+| `minimax-text` | MiniMax |
+| `baichuan-text` | 百川 |
+| `stepfun-text` | 阶跃星辰 |
+| `sensenova-text` | 商汤日日新 |
+| `ai360-text` | 360 AI |
+| `mistral-text` | Mistral |
+| `cohere-command-text` | Cohere |
+| `xai-grok-text` | xAI Grok |
+| `openrouter-text` | OpenRouter |
+| `together-llama-text` | Together |
+| `fireworks-llama-text` | Fireworks |
+| `perplexity-sonar-text` | Perplexity |
+| `azure-openai-text` | Azure OpenAI |
+| `aws-bedrock-openai-compatible-text` | AWS Bedrock OpenAI-compatible |
+
+### 图片 Provider
+
+| Provider Code | 平台 |
+|---|---|
+| `google-gemini-image` | Google Gemini Image |
+| `stability-image` | Stability AI |
+| `replicate-flux-image` | Replicate Flux |
+| `fal-flux-image` | fal.ai Flux |
+| `ideogram-image` | Ideogram |
+| `leonardo-image` | Leonardo |
+| `openai-image` | OpenAI Image |
+| `mock-image` | Mock |
+
+### 语音 Provider
+
+| Provider Code | 平台 |
+|---|---|
+| `openai-tts` | OpenAI TTS |
+| `elevenlabs-tts` | ElevenLabs |
+| `minimax-tts` | MiniMax TTS |
+| `volcengine-tts` | 火山 TTS |
+| `mock-voice` | Mock |
+
+### Lip Sync Provider
+
+| Provider Code | 状态 |
+|---|---|
+| `mock-lipsync` | Mock，占位 |
+| `minimax-lipsync` | 占位，需确认公开 API |
+| `alibaba-videoretalk-lipsync` | 阿里 VideoRetalk，要求公网 `video_url/audio_url` |
+| `heygen-lipsync` | 默认禁用 |
+| `sync-labs-lipsync` | 默认禁用 |
+| `fal-veed-lipsync` | 默认禁用 |
+| `volcengine-doubao-lipsync` | 占位，需确认公开 API |
+| `generic-lipsync` | 通用适配器 |
+
+## 5. Router 逻辑
+
+实现文件：
+
+- `backend/src/ai-router/ai-router.service.ts`
+- `backend/src/ai-router/ai-router.types.ts`
+- 真人视频调用入口：`backend/src/live-action/live-action.service.ts`
+
+### 默认配置
+
+`system_configs.config_key = ai.router.v1`
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "default_language": "zh-CN",
+  "daily_budget": 500,
+  "live_action_video": {
+    "zh-CN": {
+      "thresholds": {
+        "premium_importance_gt": 7,
+        "premium_action_gt": 5
+      },
+      "normal": {
+        "provider_code": "minimax_hailuo_23_fast",
+        "fallback_chain": ["minimax_hailuo_23_fast", "jimeng_seedance", "mock-video"]
+      },
+      "premium": {
+        "provider_code": "kling-image-to-video",
+        "fallback_chain": ["kling-image-to-video", "minimax_hailuo_23_fast", "jimeng_seedance", "mock-video"]
+      }
+    }
+  }
+}
+```
+
+### 评分字段
+
+`StoryboardShot` 上已落库：
+
+- `scene_type`
+- `importance_score`
+- `emotion_score`
+- `action_score`
+- `route_tier`
+
+### 决策流程
+
+```text
+StoryboardShot
+  -> scoreLiveActionShot()
+       scene_type / importance / emotion / action / route_tier
+  -> resolveLiveActionVideoRoute()
+       如果后台传 provider_code 且允许 override：走人工 Provider
+       否则读取 ai.router.v1
+  -> fallback_chain
+       normal: Hailuo -> Jimeng -> Mock
+       premium: Kling -> Hailuo -> Jimeng -> Mock
+  -> Provider 可用性检查
+       provider 存在
+       is_enabled=true
+       单片段成本不超过 max_cost_per_clip
+       当日预算不超过 daily_budget
+  -> 输出 AiRouteDecision
+       provider_code
+       fallback_chain
+       candidates
+       estimated_cost
+       decision_reason
+       scores
+```
+
+### 已实现能力
+
+- 没传 `provider_code` 时自动走 Router。
+- 后台/管理员可人工 override。
+- 任务 `input_json` 记录 `router_decision`。
+- 支持 fallback 链、禁用 Provider 跳过、成本上限跳过、日预算跳过。
+- Router 审计数据可从 `RenderTask.input_json`、`ProviderLog`、`OperationLog` 读取。
+
+### 待优化
+
+- Router 当前重点服务真人视频片段，文本/图片/TTS 多 Provider Router 仍可继续统一。
+- 日预算目前基于 ProviderLog 聚合，缺少更强的账户级预算锁。
+- Premium 阈值配置存在，但 `routeTierForScores` 的细节还可进一步后台可视化。
+- Router 决策的人工可解释 UI 还可继续增强。
+
+## 6. Prompt Builder 实现情况
+
+实现文件：
+
+- `backend/src/live-action/prompt-builder.service.ts`
+- 调用点：`backend/src/live-action/live-action.service.ts`
+
+### 已实现
+
+`LiveActionPromptBuilderService` 已实现真人视频 Prompt Engine V1：
+
+- Provider profile：
+  - `generic`
+  - `hailuo`
+  - `kling`
+  - `mock`
+- 结构化输入：
+  - 项目/集/镜头编号
+  - Provider Code
+  - scene type / route tier
+  - duration
+  - characters
+  - actor consistency rules
+  - location
+  - action
+  - visual description
+  - camera motion / camera instruction
+  - performance instruction
+  - dialogue / narration
+  - effect type
+  - scores
+  - lip-sync policy
+  - director plan
+- 输出：
+  - `prompt`
+  - `negative_prompt`
+  - `components`
+  - `prompt_version`
+  - `provider_profile`
+
+### 场景模板
+
+Prompt Builder 内置 scene template，用于决定：
+
+- camera shot
+- camera move
+- lighting
+- performance
+- vfx cue
+- sound cue
+- negative motion
+
+### Hailuo 专项
+
+Hailuo profile 会输出中文短剧 Prompt，包含：
+
+- 真人短剧竖屏 9:16
+- 项目/集/镜头信息
+- 场景、人物、演员一致性
+- 主动作
+- Motion Director
+- Director Plan
+- 镜头、表演、光线、特效、后期音效提示
+- lip-sync fallback 约束
+- “只完成一个主要动作，不要突然切场景”
+- Hailuo 负面词中包含避免“一条 clip 塞长多动作”
+
+### Lip Sync 策略
+
+当没有稳定 lip-sync Provider 或镜头不适合正脸说话时，策略会落为：
+
+- `post_tts_subtitle_light_mouth`
+
+Prompt 会要求：
+
+- 避免正脸嘴部特写
+- 台词后期由 TTS 和字幕处理
+- 演员只做轻微口型/反应/表情
+
+### Motion Director / Director Plan
+
+Live Action Service 会补充：
+
+- `director_plan`
+  - scene group
+  - shot role
+  - shot size
+  - continuity in/out
+  - edit intent
+  - sound bridge
+- `motion_director`
+  - time beats
+  - camera rhythm
+  - vfx timing
+  - sound hits
+  - negative motion
+
+### 待优化
+
+- Prompt Library/题材套路库已经有数据表，但与 Prompt Builder 的深度联动还不完整。
+- 爆款拉片沉淀的 `creative_patterns` 还未全面驱动真人视频 Prompt。
+- 专业音效/BGM 的剧情化选择已部分在 Live Action 后期里实现，但还缺可运营素材库。
+- 多 Provider 差异化 Prompt 可继续细分，如 Kling/Runway/Veo 专用结构。
+
+## 7. Character Library 实现情况
+
+实现文件：
+
+- `backend/src/characters/characters.service.ts`
+- `backend/src/live-action/live-action.service.ts`
+- 数据表：`characters`, `global_characters`, `global_character_assets`, `character_images`, `actor_profiles`
+
+### 项目角色
+
+已实现：
+
+- 从故事圣经和章节抽取角色。
+- 角色字段包含：
+  - name / aliases / role_type
+  - gender / age / identity
+  - appearance / face / hair / eye / body
+  - costume / props
+  - personality / speech / relationship / arc
+  - negative_rules
+  - anchor_asset_id
+  - voice provider/model/id/style
+  - performance_style
+- 角色确认后锁定关键字段。
+- 锁定后只允许有限字段变更，避免破坏一致性。
+- 角色锚点图生成、重生成、切换锚点。
+
+### 全局角色库
+
+已实现数据结构：
+
+- `global_characters`
+- `global_character_assets`
+- 项目角色可通过 `global_character_id` 关联全局角色。
+
+当前定位：
+
+- 已具备全局角色库基础表和后台入口。
+- 更偏“生产系统预留 + 初步可用”，还不是完整运营级角色资产市场。
+
+### 真人 Actor Profile
+
+Live Action 已实现：
+
+- `actor_profiles`
+- 每个项目角色生成演员定妆。
+- 字段包含：
+  - actor_desc
+  - appearance_rules
+  - wardrobe_rules
+  - performance_style
+  - voice_style
+  - reference_asset_ids
+  - anchor_asset_id
+
+### Actor Lock V1
+
+已实现：
+
+- 生成每个真人视频镜头时，只把该镜头出现的角色 ActorProfile 注入 Provider Prompt。
+- 记录：
+  - `actor_lock.character_names`
+  - `actor_lock.actor_hints`
+  - `reference_asset_ids`
+  - `provider_character_reference_enabled`
+  - `actor_lock.audit`
+- 防止“全项目角色混入一个镜头”。
+- 任务 `input_json.actor_lock` 可审计。
+
+### 待优化
+
+- 多角色同镜头的脸部一致性仍依赖 Provider 能力。
+- 角色参考图/定妆图生成质量还需要更多真实 Provider 对比。
+- 全局角色复用、授权、商用范围、声音样本绑定仍需完善运营闭环。
+
+## 8. FFmpeg 流程
+
+### 普通漫剧/图片视频流程
+
+实现文件：
+
+- `backend/src/media/media.service.ts`
+
+流程：
+
+```text
+confirmed storyboard shots
+  -> shot_images
+  -> generateEpisodeAudio()
+       多角色 TTS
+       同文本 + 同 voice 缓存复用
+       segment files 落盘
+       timeline warnings
+  -> generateEpisodeSubtitle()
+       dialogue-level SRT
+       shot-level SRT 可选
+  -> renderEpisodeVideo()
+       prefer_ffmpeg=true 时走本地 FFmpeg
+       图片转视频
+       音频/字幕合成
+       输出 MP4 Asset
+```
+
+FFmpeg 能力：
+
+- 检查 ffmpeg 是否存在。
+- 分镜图写入临时目录。
+- 音频/字幕素材写入临时目录。
+- SRT 转 ASS 字幕。
+- 图片生成视频轨。
+- 音频混合。
+- 输出 `video/mp4`。
+- 失败时写 `RenderTask.error_code/error_message`。
+
+### 真人短剧流程
+
+实现文件：
+
+- `backend/src/live-action/live-action.service.ts`
+
+片段生成：
+
+```text
+StoryboardShot + keyframe
+  -> Router 选 Provider
+  -> Prompt Builder
+  -> Provider 生成 6s/10s clip
+  -> action_beat_mode 可拆成 2-3 段
+  -> 多段之间可提取上一段末帧作为下一段关键帧
+  -> concat + trim 到目标时长
+  -> VideoClip + Asset
+```
+
+整集合成：
+
+```text
+VideoClip assets
+  -> normalizeLiveActionClipForRender()
+       ffprobe 探测源时长
+       超出目标时长则自动裁切
+       记录 clip_normalization
+  -> concatVideoClips()
+  -> prepareLiveActionPostProductionAssets()
+       TTS 对白
+       SRT/ASS 字幕
+       BGM
+       SFX
+       可选 lip-sync
+  -> finalizeLiveActionRenderWithPostProduction()
+       视频调色/暗角/字幕
+       dialogue + bgm + sfx 混音
+       loudnorm / limiter
+       输出 episode-final.mp4
+```
+
+真人后期 FFmpeg 参数特点：
+
+- `libx264`
+- `-preset veryfast`
+- `-crf 20`
+- `yuv420p`
+- `+faststart`
+- 音频 `aac 160k 44100 stereo`
+- BGM fade in/out
+- SFX limiter
+- dialogue loudnorm
+- 混音 `amix normalize=0`
+- 字幕走 ASS/FFmpeg subtitles filter
+
+### 已记录审计
+
+- `renderTask.input_json.clip_normalization`
+- 是否裁切、源时长、目标时长、最终时长、裁切策略、trim start。
+- 最终成片状态：
+  - 全 mock clip -> asset `mock`
+  - 任一真实 clip -> asset `active`
+
+## 9. 当前已完成功能
+
+### 系统 A 基础 MVP
+
+- 用户注册登录。
+- 项目创建。
+- AI 原创小说 mock 流程。
+- 上传小说、解析、章节拆分。
+- 版权确认。
+- 故事圣经生成/确认。
+- 角色抽取/确认。
+- 角色锚点图。
+- 长篇记忆。
+- 分集计划。
+- 单集脚本。
+- 分镜脚本。
+- 图片生成 mock/Provider 抽象。
+- 多角色 TTS。
+- 字幕生成。
+- FFmpeg 合成 MP4。
+- 用户端查看进度、预览、下载。
+- 后台项目管理、任务管理、Provider 管理。
+- 内容审核。
+- 公开案例授权。
+- 额度账户和冻结额度。
+
+### AI Provider
+
+- Provider 抽象层。
+- Mock Provider。
+- OpenAI Provider 模板。
+- 国内外主流文本/图片/视频/TTS/lip-sync Provider 模板。
+- Provider 日志。
+- Provider 成本摘要。
+- 后台统一保存同公司 Key 的体验优化。
+- MiniMax TTS 实测修复：
+  - voice_id 映射
+  - 空音频错误识别
+  - Provider 拒绝错误透出。
+
+### 真人短剧
+
+- `live_action_ai` 输出模式。
+- 演员定妆 ActorProfile。
+- 真人分镜改写。
+- 关键帧生成/上传绑定。
+- 视频片段生成：
+  - Hailuo / Kling / Jimeng / Mock 路由
+  - preflight
+  - 成本预估
+  - 单片段成本上限
+  - 真实费用确认
+  - action beat 拆段
+  - candidate_count 支持
+- Router 质检闭环：
+  - 质检
+  - 低分自动重试
+  - fallback Provider
+  - manual_required
+  - 人工通过/驳回
+- 片段重试。
+- 小样测试台。
+- 真人整集合成。
+- TTS/BGM/SFX/字幕后期合成。
+- clip normalization 自动裁切。
+- actor lock 审计。
+
+### 前端/后台体验
+
+- 用户端制作页已改为单列纵向流程。
+- 每步完成后自动滚动到下一步。
+- 用户端真人视频面板已同步 action beat 控制。
+- 后台深色运营台风格。
+- 后台 AI 平台入口和配置。
+- Router/质检审计视图和操作闭环已有实现。
+
+## 10. 待优化功能
+
+### 生产级队列化
+
+- 当前 BullMQ/worker 框架已存在，但重型生成流程仍有大量 API 同步执行。
+- 需要把：
+  - 重新质检
+  - 自动修复
+  - 指定 Provider 重试
+  - 真人视频生成
+  - FFmpeg 合成
+  全部任务化，形成可暂停、恢复、重跑、精确计费的队列闭环。
+
+### 真人视频质量
+
+- Hailuo 对复杂动作、翻滚、结印、法相天地等高复杂特效表现不稳定。
+- 需要更多 Provider 准入测试：
+  - Kling
+  - Runway
+  - Vidu
+  - Veo
+  - 阿里 Wan
+  - 即梦/Seedance
+- 都市短剧可继续用 Hailuo 主力；修仙/特效/复杂动作需要更强模型。
+
+### Lip Sync
+
+- 已有 lip-sync 抽象和多个 Provider 占位。
+- 稳定公开 API 仍需逐个平台实测。
+- MiniMax/豆包 lip-sync 目前标为占位，不能假定已稳定可用。
+- 阿里 VideoRetalk 需要公网 `video_url/audio_url`，素材公网桥接已设计但仍需生产验证。
+
+### Prompt Engine
+
+- 真人 Prompt Builder V1 已落地。
+- Prompt Library / CreativePattern 与实际脚本、分镜、真人 Prompt 的联动还需加强。
+- 需要题材模板：
+  - 都市逆袭
+  - 霸总打脸
+  - 修仙法相
+  - 聊斋志异
+  - 次元壁
+- 需要把拉片分析的镜头语言、音效、BGM、剪辑节奏转为可复用模板。
+
+### Character Library
+
+- 全局角色表已存在。
+- 还需要：
+  - 前台化角色资产库
+  - 商用授权状态
+  - 角色复用统计
+  - voice sample 管理
+  - 多项目角色一致性验证
+
+### 成本/ROI
+
+- Provider 成本估算和日志已有。
+- 还需接真实账单回填、播放数据、完播率、收益，形成 ROI：
+  - 每题材 ROI
+  - 每 Provider 成本/成功率
+  - 每镜头类型失败率
+  - 每集成本和收益
+
+### 数据清理/生产隔离
+
+- 当前服务器数据库包含大量测试项目、任务、素材和 ProviderLog。
+- Git 只提交源码，不提交数据库和 storage。
+- 上线前建议：
+  - 分测试库/生产库
+  - 测试素材定期清理
+  - ProviderLog 按时间归档
+  - storage 生命周期策略
+
+## 11. 关键文件路径
+
+### 根目录
+
+| 文件 | 作用 |
+|---|---|
+| `README.md` | 项目说明 |
+| `OPERATION_GUIDE.md` | 操作说明 |
+| `AGENTS.md` | Codex 开发约束 |
+| `.env.example` | 环境变量模板 |
+| `.gitignore` | Git 忽略规则 |
+| `CODEX_PROGRESS.md` | 阶段进度记录 |
+| `AI_VIDEO_TEST_LESSONS.md` | 真人视频测试经验记录 |
+| `CURRENT_ARCHITECTURE.md` | 当前架构文档 |
+
+### 后端
+
+| 文件 | 作用 |
+|---|---|
+| `backend/src/app.module.ts` | Nest 模块总入口 |
+| `backend/src/main.ts` | 后端启动入口 |
+| `backend/prisma/schema.prisma` | 数据库 schema |
+| `backend/prisma/migrations/*/migration.sql` | 数据库迁移 |
+| `backend/prisma/seed.ts` | 初始 mock Provider、Router、管理员 |
+| `backend/src/providers/provider.types.ts` | Provider 默认模板和成本摘要 |
+| `backend/src/providers/providers.service.ts` | Provider bootstrap、执行、日志、配置 |
+| `backend/src/ai-router/ai-router.service.ts` | Router 决策 |
+| `backend/src/ai-router/ai-router.types.ts` | Router 默认配置和类型 |
+| `backend/src/live-action/live-action.service.ts` | 真人短剧核心流程 |
+| `backend/src/live-action/prompt-builder.service.ts` | 真人 Prompt Builder |
+| `backend/src/media/media.service.ts` | TTS、字幕、普通 FFmpeg 合成 |
+| `backend/src/assets/storage.service.ts` | 存储抽象 |
+| `backend/src/admin/admin.service.ts` | 后台审计和管理 |
+
+### 用户端
+
+| 文件 | 作用 |
+|---|---|
+| `user-app/src/pages/index/index.vue` | 用户端主制作台 |
+| `user-app/src/api/client.ts` | 用户端 API 封装 |
+| `user-app/src/workflow.ts` | 工作流标签和进度 |
+| `user-app/src/styles.css` | 用户端样式 |
+
+### 后台端
+
+| 文件 | 作用 |
+|---|---|
+| `admin/src/App.vue` | 后台管理主界面 |
+| `admin/src/api/client.ts` | 后台 API 封装 |
+| `admin/src/styles.css` | 后台样式 |
+
+### Worker
+
+| 文件 | 作用 |
+|---|---|
+| `workers/src/main.ts` | BullMQ worker 入口 |
+
+### 运维
+
+| 文件 | 作用 |
+|---|---|
+| `deploy/docker-compose.dev.yml` | 开发依赖服务 |
+| `deploy/nginx.https.example.conf` | Nginx HTTPS 示例 |
+| `deploy/README.md` | 部署说明 |
+
+## 12. 当前架构判断
+
+当前系统已经从“普通 AI 漫剧 MVP”扩展到“AI 真人短剧生产流水线雏形”：
+
+- 基础项目/小说/故事/角色/分集/脚本/分镜/合成已跑通。
+- Provider 抽象、Router、质检、成本、审计已经具备生产系统骨架。
+- 真人短剧的关键难点已经开始落地：
+  - 角色定妆
+  - Actor Lock
+  - 专业 Prompt Builder
+  - 真实 Provider 小样
+  - 片段质检
+  - 后期音频/BGM/SFX/字幕
+  - FFmpeg 裁切/拼接/混音
+
+下一阶段最重要的不是继续堆 Provider，而是把真人视频生产质量和任务稳定性打磨成可重复流水线：
+
+1. 真实 Provider 准入矩阵。
+2. 队列化/失败恢复。
+3. Prompt Library 与拉片模式库联动。
+4. 角色库运营化。
+5. 真实成本/ROI 回流。