From b2ae4600b484acfa5778059483432a2b8d9e6516 Mon Sep 17 00:00:00 2001 From: www Date: Mon, 15 Jun 2026 18:13:21 +0800 Subject: [PATCH] Add current architecture document --- CODEX_PROGRESS.md | 27 ++ CURRENT_ARCHITECTURE.md | 933 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 960 insertions(+) create mode 100644 CURRENT_ARCHITECTURE.md diff --git a/CODEX_PROGRESS.md b/CODEX_PROGRESS.md index 7fd08c6..36197c8 100644 --- a/CODEX_PROGRESS.md +++ b/CODEX_PROGRESS.md @@ -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 diff --git a/CURRENT_ARCHITECTURE.md b/CURRENT_ARCHITECTURE.md new file mode 100644 index 0000000..fbfa807 --- /dev/null +++ b/CURRENT_ARCHITECTURE.md @@ -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 回流。