# AI 内容生产平台架构设计 V1

> 文档状态：当前有效  
> 基线日期：2026-07-15  
> 事实来源：当前源码、Prisma schema、生产配置与 `PROJECT_STATUS_V1.md`  
> 维护原则：记录稳定边界和已确认事实，不复制完整代码。

## 1. 架构目标

平台面向小说、角色/IP 资产、短剧和音视频成品的一体化生产，当前架构要同时满足：

- 长文本生产中的记忆、版本和质量循环。
- 图片、视频、声音等多 Provider 的差异化调用。
- 角色、服装、场景和道具在跨镜头生产中的连续性。
- 耗时任务的异步执行、重试、人工介入和成本追踪。
- 素材私有访问、Range 播放、下载与后期合成。
- 用户端生产工作台和管理端运营审计。

## 2. 系统边界

```mermaid
flowchart TB
  User[用户端 Vue 3 H5] --> Nginx[Nginx]
  Admin[管理端 Vue 3 H5] --> Nginx
  Nginx --> API[NestJS API :3010]
  API --> MySQL[(MySQL)]
  API --> Redis[(Redis / BullMQ)]
  API --> Storage[本地私有存储\nMinIO 可选]
  API --> AI[外部 AI Providers]
  API --> Media[FFmpeg / FFprobe]
  Redis --> Worker[独立 Worker]
  Worker --> Internal[受密钥保护的内部执行接口]
  Internal --> API
```

外部依赖包括文本、图片、视频、语音、音乐、Embedding 和审核模型。平台负责业务编排、资产关系、质量控制和成本记录，不把外部模型的临时任务状态当作最终业务状态。

## 3. 仓库结构

项目采用 npm workspaces 单仓库：

| 目录 | 职责 |
| --- | --- |
| `backend/` | NestJS API、Prisma、业务编排、Provider 与媒体处理 |
| `workers/` | BullMQ 消费，委托后端内部接口执行业务 |
| `user-app/` | Vue 3 + Vite 用户端 H5 |
| `admin/` | Vue 3 + Vite 管理后台 |
| `deploy/` | 开发依赖和 Nginx 示例，生产运维脚本尚不完整 |
| `docs/` | 当前设计、历史设计、经验和同步包 |
| `data/` | 项目内容、剧本、分镜和生产资料 |
| `storage/` | 当前本地私有素材存储 |
| `tmp/` | 临时媒体处理文件 |

## 4. 后端分层

### 4.1 接入层

- HTTP API 统一使用 `/api` 前缀。
- JWT 负责用户身份，管理能力执行角色和 permission 校验。
- 统一响应 envelope、异常过滤、请求 ID 和安全响应头。
- 请求体上限当前为 160 MB。
- 素材接口支持鉴权下载、Range 流和临时签名 URL。

### 4.2 业务域

| 业务域 | 核心模块 |
| --- | --- |
| 身份与计费 | `AuthModule`、`UsersModule`、`BillingModule` |
| 项目与素材 | `ProjectsModule`、`AssetsModule` |
| 小说与世界观 | `NovelsModule`、`StoryBiblesModule`、`MemoriesModule` |
| 角色与 IP | `CharactersModule`、`ImagesModule` |
| 分集与剧本 | `EpisodesModule`、`ScriptsModule` |
| 真人短剧 | `LiveActionModule`、`MediaModule` |
| AI 与任务 | `ProvidersModule`、`ProviderLabModule`、`QueuesModule` |
| 审核与运营 | `ReviewsModule`、`AdminModule` |

`AiRouterModule` 当前服务于真人视频域，尚未成为全平台所有 AI 请求的统一入口。文档和界面不得把它描述成已完成的全局智能路由。

### 4.3 数据层

- Prisma 6 + MySQL。
- 当前 61 个 Model、33 个已部署迁移。
- 业务状态大多为字符串；历史值漂移需要通过状态字典和兼容迁移治理。
- JSON 用于保存 Provider 参数、Prompt 快照、质量报告和扩展元数据。

### 4.4 异步执行层

- Redis + BullMQ，共 14 个队列。
- Worker 并发当前为 2。
- Worker 不重复业务实现，通过受 `WORKER_SECRET` 保护的内部接口委托后端。
- `RenderTask` 保存幂等键、输入哈希、重试、成本与人工介入状态。

当前并非所有声明任务都已完整队列化。长篇记忆、字幕、真人关键帧、真人合并和分析事件存在同步执行或 Worker 映射缺口，详见 `AI_PIPELINE_V1.md`。

### 4.5 媒体层

- FFmpeg 负责归一、拼接、转场、字幕、BGM、SFX、环境音和混音。
- FFprobe 负责媒体元信息探测。
- 视频模型可返回原生音轨；后期策略决定保留、压低或补充外部音频。
- LipSync 已有抽象和策略字段，但真实 Provider 当前均未启用。

## 5. 前端架构现实

### 5.1 用户端

用户端为 Vue 3 + Vite H5。当前核心功能集中在 `pages/index/index.vue`，没有启用 Vue Router。顶级入口包括创作、工具、项目、作品、任务和我的。

独立工具目前只有“人物三视图”正式开放；影视场景、9/16/25 宫格和原创剧本仍为待接入状态。

### 5.2 管理端

管理端是自研 Vue 3 单页后台，并非完整 GeekerAdmin。主要功能集中在 `App.vue`，`router/`、`stores/`、`views/` 仍是占位结构。

### 5.3 结构风险

用户端、管理端和若干后端 Service 已形成超大文件。后续应按稳定业务边界渐进拆分，避免一次性重构影响现有真实生产链路。

## 6. 核心数据流

### 6.1 内容生产

```text
来源/创作 Brief
-> 版权与项目规则
-> 故事/世界观/角色/IP 资产
-> 分集与剧本
-> 动态分镜
-> 关键帧或多图参考
-> 视频候选
-> 自动 QC / 人工选择
-> 字幕、音频、BGM、SFX、转场
-> FFmpeg 成品
-> 审核与作品库
```

### 6.2 AI 调用

```text
业务请求
-> 用户/项目模型偏好
-> Provider 配置与预检
-> 同步调用或异步提交
-> ProviderLog
-> Asset / VideoClip / RenderTask
-> 质量评估、回退或人工介入
```

## 7. 安全与隐私

- API Key 由服务端密钥加密保存，后台不回显明文。
- Worker 内部接口使用 timing-safe 密钥比较。
- 素材默认私有，不依赖可枚举静态 URL。
- Nginx 承担公网 TLS；应用当前未强制 `HTTPS_REQUIRED`。
- 外部 Provider 使用参考图时，应只提交限时、最小权限 URL。
- Work 同步文档禁止包含 `.env`、API Key、JWT、数据库密码、私有素材 URL 和用户个人数据。

## 8. 部署与运行

当前生产事实：

- `ai-backend.service`、`ai-workers.service` 由 systemd 托管。
- Nginx 托管两套前端静态产物并代理 API。
- MySQL、Redis 为本机服务。
- 主存储为本地私有目录，MinIO 仅有代码能力，尚未完整配置。
- 全仓生产构建已通过，但运行进程需受控重启后才会加载最新构建。

当前缺少完整的发布、回滚、备份、日志轮转、监控和恢复演练脚本。这些属于发布基线，不应只保留为历史设计。

## 9. 架构约束

1. 数据库 schema 和迁移是数据结构唯一真相。
2. Provider 调用必须留下实际 Provider、模型、参数快照、成本和回退记录。
3. 角色、场景和道具应通过资产 ID/版本引用，不靠 Prompt 文本隐式继承。
4. 外部模型状态、平台任务状态和素材状态必须分层管理。
5. 付费生成前必须完成参数和参考图预检。
6. 视频质量闭环允许人工确认，不能把模型评分直接等同于发布通过。
7. 历史设计只能解释来路，不能覆盖当前代码事实。

## 10. 当前优先级

### P0

- 备份数据库和素材，固化 Git 基线。
- 修复 35 条后端失败测试。
- 受控重启并验证最新构建。

### P1

- 补齐队列执行覆盖和状态字典。
- 建立本地素材备份与恢复演练。
- 明确 Provider 路由优先级和实际调用展示。
- 补齐外部素材 URL preflight。

### P2

- 渐进拆分超大 Service 和前端单体组件。
- 引入 OpenAPI 契约和关键 E2E。
- 完善生产发布、回滚、监控与告警。

## 11. 更新触发条件

发生以下任一变化时更新本文并提升版本：

- 新增或删除顶层业务模块。
- 数据库、队列、存储或部署拓扑改变。
- AI Router 扩展为平台级入口。
- 前端路由或应用边界发生结构性变化。
- 安全边界、租户模型或支付模式改变。