ai/docs/work-sync/02_架构设计/SYSTEM_ARCHITECTURE_V1.md

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

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

1. 架构目标

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

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

2. 系统边界

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 内容生产

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

6.2 AI 调用

业务请求
-> 用户/项目模型偏好
-> 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 扩展为平台级入口。
• 前端路由或应用边界发生结构性变化。
• 安全边界、租户模型或支付模式改变。