ai/CURRENT_ARCHITECTURE.md

# 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 回流。