# 本地化 AI 短剧/漫剧平台架构

## 产品模块

### 三类产品面

- **创作空间**：我的工作台、项目工厂、剧本拆解、Series Bible、资产与选角、Continuity Ledger、导演工作台、生成任务、审片和交付。
- **管理员后台**：管理概览、组织与工作区、用户与权限、模型与 Runner、队列与任务、用量与成本、审计与合规。
- **系统设置**：系统健康、部署模式、存储、队列并发、单画面策略、真实末帧策略、固定声线、QA 门、通知、API 客户端和功能开关。

三类产品面共享同一套上下文选择器，但权限边界不同。组织管理员治理租户内资源；系统管理员治理本地部署实例和平台级策略。

- 前端生产台：生产总控、剧本拆解、资产选角、导演工作台、生成队列、审片中心、交付运营。
- 数据核心：series bible、character locks、location locks、prop locks、shot list、voice lines、continuity ledger、generation jobs、QA results。
- 生成适配器：默认对接用户自有模型平台；支持自定义 HTTP JSON、OpenAI-compatible 本地网关和 NewAPI 音频中转；ComfyUI 为可选适配器。
- 质检门：一图一画面、连续性、IndexTTS-2.5 固定配音、paraformer-zh-long 声音/字幕/ASR 对齐、片段衔接。
- 交付目录：prompt pack、配音台词表、剪辑合成清单、QA 结果和最终视频工程目录。

## 系统治理数据

- `system_settings`：部署和生成策略的持久化键值，支持类型化编辑和审计。
- `feature_flags`：系统范围功能开关，默认关闭外部云连接器和非必要适配器。
- `notification_channels`：本地事件日志和可选 Webhook。
- `api_clients`：本地 Runner/企业集成客户端及 scope。
- `service_health`：本地 API、SQLite 和各类 Runner 的健康、延迟、队列深度。
- `system_admins`：独立于组织角色的系统管理员身份。

## 本地执行层

API 进程启动时自动初始化 `server/worker.mjs`，Worker 通过数据库租约领取可执行任务，并把执行状态、attempt、错误、用量和审计事件写回 SQLite。领取条件由服务端强制执行：任务必须是 `queued`，前置依赖必须完成，连接器必须 `ready` 且 `cost_mode=local`。因此管理员可以在队列页看到真实的在线状态、并发、队列深度、最近心跳和失败原因，而不会把云端任务伪装成本地自动执行。

Worker 运营层还维护租约超时回收、最大尝试次数、指数退避、队列最老等待时长和心跳失效判断。管理员可通过 `/api/admin/queue/batch` 批量重试/取消，并通过 `/api/system/worker` 读取告警状态；这部分状态不是前端计算，而是由本地 Worker 和数据库共同写回。

商业运营数据按组织保存账单周期、配额预警阈值、账单变更历史和成本中心。系统管理员用户治理与组织管理员成员治理分开：系统管理员可以创建全局账号、重置密码/MFA、调整组织/工作区/项目归属；所有动作都经过后端 session、scope 和 role 校验并写入审计。

模型执行请求统一经过 `server/execution.mjs` 的协议层：自定义 HTTP JSON 发送生产合同，OpenAI-compatible 按操作映射标准路由，ComfyUI 只负责 optional workflow bridge。认证信息通过 `authEnv` 指向进程环境变量，数据库和导出包不保存密钥。

## 推荐流水线

1. 写 series bible 和 episode card。
2. 锁定角色、服装、声音、场景、道具、天气和固定机位。
3. 生成每个镜头的一张完整单画面关键帧，输出数量必须等于 1。
4. 后续镜头优先用上一段视频的实际末帧作为首帧；大跨度场景先插入过渡镜头。
5. 台词先走 NewAPI/IndexTTS-2.5 固定 TTS 声线，使用 `prompt_speech` 参考音频锁定角色；无法口型同步时使用侧脸、背影、低头、远景、反应镜头、环境插入镜头。
6. 音频生成后走 NewAPI/paraformer-zh-long 的 `verbose_json` 识别，用 ASR 文本校验台词准确性，用词级时间戳生成字幕时间轴。
7. 视频片段通过 QA 后进入剪辑合成。

生成任务在进入 Worker 前还会经过单画面、连续性、成本策略和外部连接审批门；图片响应中 `data`、`images`、`outputs` 任一数组都必须恰好有一项。

## 旧资产复用

- `/Users/xz/Documents/daima/ai短剧/codex_qu_2026-08-15/work/rebuild_no_narration_v1.py`：单画面正负约束、Qwen Image、QwenEdit、H3 首尾帧桥接、输出数量检查。
- `/Users/xz/Documents/daima/ai短剧/generate_thunderstorm_drama_locked_midshot_v3_cn_dialogue.py`：雷暴样片的角色锁、场景锁、对白、实际末帧串联。
- `/Users/xz/Documents/daima/ai短剧/outputs/voice_lock_strategy/voice_lock_plan.md`：固定 TTS 声音加规避嘴形的声音策略。
- `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/docs/NEWAPI_AUDIO_WORKFLOW.md`：NewAPI 中转 `IndexTTS-2.5` 和 `paraformer-zh-long` 的音频请求格式。

## 禁止默认行为

- 不默认使用付费或云端节点。
- 不在配置、导出文件或日志里保存 NewAPI 密钥；需要认证时只读取环境变量。
- 不把 MiniMax H3 每次随机采样的原生声音当角色最终声线。
- 不把 storyboard、contact sheet、collage、九宫格、边界表作为生成输入。
- 不让同一张生成图出现多个地点、多个时间点、多个机位或多个连续动作。