ai/PROJECT_STATUS_V1.md

# AI 内容生产平台项目现状 V1

> 文档类型：项目状态回灌 / 技术审计快照  
> 审计时间：2026-07-15（Europe/Berlin）  
> 审计对象：`/www/wwwroot/ai` 当前工作区、当前 MySQL 数据库、当前 systemd 运行服务  
> 文档用途：作为 Work 的“代码现实”基线，不替代产品设计文档，也不替代 Git 版本记录。

## 0. 审计口径

本文件按以下优先级判断项目真实状态：

1. 当前工作区源码与配置结构。
2. Prisma schema、迁移记录和数据库只读统计。
3. 当前 systemd、Nginx、MySQL、Redis 运行状态。
4. 构建与自动测试结果。
5. `README.md`、`CURRENT_ARCHITECTURE.md`、`CODEX_PROGRESS.md` 与 `docs/system_a`、`docs/system_b` 等历史文档。

状态标记：

| 标记 | 含义 |
| --- | --- |
| 已实现且验证 | 代码存在，当前可构建，并有运行数据、测试或实际调用记录佐证 |
| 已实现但验证不足 | 主体代码已存在，但自动测试、运行配置或完整 E2E 尚未达到发布基线 |
| 部分接入 | 只有部分入口、部分 Provider 或部分流程可用 |
| 仅设计/预留 | 有文档、数据结构或界面占位，但未形成完整可用链路 |

注意：本文中的 V1 是“状态文档版本”，不是 npm 包版本。当前各 workspace 的代码版本仍为 `0.1.0`，不应仅凭功能变多就直接对外宣布产品 V5.0。

## 1. 执行摘要

### 1.1 当前项目真实定位

当前系统已经不再只是“AI 小说系统”或“AI 漫剧系统”，实际代码覆盖：

- 小说导入、阅读、原创生成、章节质量循环与版本管理。
- 故事圣经、世界观、角色、剧情记忆与 IP 资产管理。
- 分集、剧本、分镜、关键帧、图生视频和候选片段选择。
- 真人/仿真人短剧生产、原生音频视频、字幕、BGM、SFX、转场与 FFmpeg 合成。
- AI Provider 目录、模型偏好、成本记录、路由、实验台与回退。
- 队列、任务重试、人工介入、额度、审核、运营后台和审计日志。
- 面向生产的独立创作工具，当前已开放“人物三视图”。

因此，面向 Work 的项目名称建议使用：

```text
AI 内容生产平台
```

### 1.2 当前健康度

| 检查项 | 当前结论 |
| --- | --- |
| 后端 API | `ai-backend.service` 正在运行，健康检查返回 `ok` |
| 队列 Worker | `ai-workers.service` 正在运行，消费 14 个 BullMQ 队列 |
| 数据库 | MySQL 正在运行，33 个 Prisma 迁移全部已部署 |
| Redis | 正在运行，Worker 与 API 均配置为使用 Redis |
| 前台/后台 | Vue 3 + Vite 生产构建通过，Nginx 直接托管静态产物 |
| 全仓构建 | 通过：backend、admin、user-app、workers 均成功构建 |
| 自动测试 | 未通过：后端 273 条测试中 238 通过、35 失败；Worker 1 条通过；前台和后台无测试文件 |
| Git 基线 | 高风险：`main` 仅 1 个提交，当前有 85 个修改项、47 个未跟踪项 |
| 运行版本一致性 | 需处理：审计构建产物晚于 backend/worker 进程启动时间，当前进程尚未加载最新构建 |
| 存储 | 当前为本机私有存储；MinIO 代码已实现但当前未完整配置 |
| AI 默认模式 | 全局 `AI_PROVIDER_MODE=mock`，但数据库中有大量真实 Provider 可被显式选择 |

### 1.3 结论

当前项目已经是一个有真实数据、真实调用和真实视频资产的内部生产平台，不是原型空壳；但它还不是可安全标记为“稳定生产版”的发布基线。

当前最重要的工作顺序应为：

1. 固化 Git 与数据库备份基线。
2. 修复测试和状态枚举漂移。
3. 对齐当前构建与运行进程。
4. 补齐队列任务执行覆盖。
5. 再继续扩展新功能。

## 2. 当前项目实际架构

### 2.1 仓库形态

项目为 npm workspaces 单仓库：

```text
ai/
├── backend/       NestJS API、Prisma、业务编排、Provider、FFmpeg 调用
├── workers/       BullMQ Worker，消费队列后委托 backend 执行业务
├── user-app/      Vue 3 + Vite 用户端 H5
├── admin/         Vue 3 + Vite 运营管理后台
├── deploy/        开发依赖与 Nginx 示例，生产脚本尚不完整
├── docs/          原系统 A/B、AI 生产经验、教程和成本资料
├── data/          项目内容、剧本、分镜与生成过程资料
├── storage/       当前本地私有素材存储
└── tmp/           临时处理文件
```

### 2.2 运行拓扑

```mermaid
flowchart TB
  User[用户端 Vue H5] --> Nginx[Nginx]
  Admin[管理端 Vue H5] --> Nginx
  Nginx --> API[NestJS API :3010]
  API --> MySQL[(MySQL ai_manga)]
  API --> Redis[(Redis)]
  API --> Storage[本地私有存储\nMinIO 可选]
  API --> Providers[AI Providers]
  API --> FFmpeg[FFmpeg / FFprobe]
  API --> BullMQ[BullMQ 14 队列]
  BullMQ --> Worker[独立 Worker\n并发 2]
  Worker --> InternalAPI[受 WORKER_SECRET 保护的内部接口]
  InternalAPI --> API
```

### 2.3 后端基础设施

- 框架：NestJS 10。
- ORM：Prisma 6，MySQL。
- 队列：BullMQ 5 + Redis。
- 文件：本地私有文件为当前主存储，MinIO 为可选实现。
- 媒体：FFmpeg、FFprobe。
- 文件解析：PDF、DOCX、纯文本。
- 鉴权：JWT。
- 后台权限：`admin`、`operator`、`finance`、`auditor` 角色与细粒度 permission。
- API 前缀：`/api`。
- 请求体上限：当前 160 MB。
- 中间件：请求 ID、安全响应头、HTTPS/代理判断、应用层加密请求处理。
- API 返回：统一 envelope 和统一异常过滤。

### 2.4 当前部署事实

- 后端由 `ai-backend.service` 托管。
- Worker 由 `ai-workers.service` 托管。
- Nginx 分别托管用户端与管理端，并反向代理 `/api/`。
- MySQL、Redis 为本机服务。
- 当前 `NODE_ENV=production`、`STORAGE_DRIVER=local`、Worker 并发为 2。
- 后端没有强制 `HTTPS_REQUIRED`；传输安全依赖 Nginx 与部署配置。
- `PUBLIC_ASSET_BASE_URL` 类配置当前未设置，依赖外部 Provider 获取临时素材 URL 的链路需要专项复核。

## 3. 已实现模块

### 3.1 后端模块

当前 `AppModule` 注册的业务模块：

| 模块 | 主要职责 | 状态 |
| --- | --- | --- |
| `AuthModule` | 注册、登录、JWT、账号状态 | 已实现且验证 |
| `UsersModule` | 用户资料 | 已实现 |
| `BillingModule` | 额度、订单、冻结、释放、后台人工调整 | 已实现但支付仅为 mock |
| `ProjectsModule` | 项目、作品库、小说库、创意模式、流水线配置 | 已实现 |
| `ProviderLabModule` | Provider 参数试跑与状态轮询 | 已实现 |
| `AssetsModule` | 上传、下载、预览、Range 流、别名、选择状态 | 已实现且有大量真实素材 |
| `NovelsModule` | 导入、解析、阅读、原创小说、Agent 与章节质量流程 | 已实现但测试不足 |
| `StoryBiblesModule` | 故事圣经、制作规则、确认锁定 | 已实现 |
| `CharactersModule` | 项目角色、全局角色、版本、状态、Prompt 审核与优化经验 | 已实现但复杂度较高 |
| `MemoriesModule` | 剧情、角色、伏笔与连续性记忆 | 已实现但测试桩未同步 |
| `EpisodesModule` | 分集计划、请求预览、质量闸门 | 已实现但质量测试有漂移 |
| `ScriptsModule` | 单集剧本、分镜、动态时长、提示词、转场 | 已实现但测试不足 |
| `ImagesModule` | 角色图、锚点图、三视图、关键帧、视觉质检 | 已实现 |
| `LiveActionModule` | 真人短剧准备、关键帧、视频、QC、合并、后期 | 已实现但仍处于生产化磨合 |
| `MediaModule` | TTS、字幕、传统漫剧合成、音频片段重试 | 已实现 |
| `ProvidersModule` | Provider 目录、配置、调用、日志、成本、异步视频轮询 | 已实现且有真实调用 |
| `QueuesModule` | RenderTask、BullMQ、重试、取消、恢复、Worker 委托 | 已实现但执行覆盖不完整 |
| `ReviewsModule` | 文本/素材审核、返修、案例授权 | 已实现但当前数据库尚无审核记录 |
| `AdminModule` | 运营后台聚合 API、审计、配置、Router 审计 | 已实现 |

`AiRouterModule` 没有作为顶层模块单独注册，但被 `LiveActionModule` 导入并实际用于真人视频路由。当前它不是覆盖全平台所有 AI 请求的统一 Router。

### 3.2 用户端模块

用户端实际为 Vue 3 单页应用，不是旧文档描述的 uni-app 多路由实现。

顶级导航：

- 创作：新建、提示词直出、API 快测。
- 工具：独立创作工具。
- 项目：项目列表、制作台、IP 资产中心、进度。
- 作品：视频、小说、素材。
- 任务：运行任务、审核、额度与成本。
- 我的：账号、角色资产、教程。

制作台主流程：

```text
来源 -> 版权 -> 故事圣经 -> 角色 -> 记忆 -> 分集
-> 剧本/分镜 -> 真人视频 -> 合成 -> 审核
```

独立创作工具当前状态：

| 工具 | 状态 |
| --- | --- |
| 人物三视图 | 已开放；支持主锚点参考或输入本次唯一角色描述；生成后可下载和视觉质检 |
| 影视场景专家 | 待接入 |
| 9 宫格分镜 | 待接入 |
| 16 宫格分镜 | 待接入 |
| 25 宫格分镜 | 待接入 |
| 原创剧本 | 待接入 |

虽然 `user-app/src/pages/` 中保留了多页面文件，但当前 `App.vue` 实际只加载大型 `pages/index/index.vue`，没有 Vue Router。多数业务都集中在一个约 1.35 万行的页面组件中。

### 3.3 管理端模块

管理端实际为自研 Vue 3 单页后台，不是完整 GeekerAdmin 集成。

当前菜单包括：

- 仪表盘、使用教程。
- 项目、小说、全局角色、项目角色、分镜、成品。
- 订单额度、内容审核、任务。
- Router 审计、爆款诊断、AI 平台入口。
- Provider、成本、用户、素材。
- 系统配置、版权、审计日志。

后台同样集中在一个约 1.03 万行的 `App.vue` 中，没有实际 Router、Store 和拆分后的 Views。

## 4. 已完成功能与完成度

| 业务域 | 当前能力 | 完成度判断 |
| --- | --- | --- |
| 账号与安全 | 注册、登录、JWT、账号禁用、密码重置、RBAC、操作审计、应用层加密 | 已实现且验证 |
| 项目 | 新建、列表、删除、取消、进度、作品库、提示词直出分镜 | 已实现 |
| 小说导入 | 粘贴、文件上传、章节切割、编辑、版权确认 | 已实现 |
| 小说阅读 | 目录、分页/翻页、阅读进度、书签、批注 | 已实现 |
| 原创小说 | 创作向导、生成计划、章节 Agent、上下文、质检、修复、版本、批次 | 已实现但自动测试未稳定 |
| 故事与世界观 | StoryBible、WorldBible、制作文本和锁定 | 已实现 |
| 角色资产 | 项目角色、全局演员、外观版本、状态、服装、声音、授权范围 | 已实现 |
| 角色提示词闭环 | Prompt 版本、审核、优化经验、下一次生成吸收 | 已实现 |
| 人物三视图 | 主锚点模式、纯描述覆盖模式、旗舰模板、下载、视觉评分 | 已实现 |
| IP 资产中心 | 场景/道具提取、主资产、版本、Prompt、冲突检查 | 已实现但 UI/测试仍在磨合 |
| 长篇记忆 | 剧情记忆、角色记忆、伏笔线程、连续性检查 | 已实现但测试未同步 |
| 分集 | 动态数量、质量闸门、请求预览与 Prompt 覆盖 | 已实现但当前一条质量测试失败 |
| 剧本 | 剧本生成、人工编辑、确认、请求预览 | 已实现 |
| 分镜 | 动态时长、关键帧/视频 Prompt、前后镜衔接、转场字段、视觉板 | 已实现 |
| 关键帧 | 角色/场景/道具参考、单镜/批量、视觉审核 | 已实现且有真实图片调用 |
| 视频 | 单镜/批量、多候选、首帧/首尾帧/参考图、原生音频 Provider | 已实现且有真实视频调用 |
| 视频 QC | 自动评分、同模型重试、Fallback、人工确认、候选选择 | 已实现但测试和策略仍在变化 |
| 视频合并 | 硬切/转场、画面归一、源音轨、字幕、BGM、SFX、FFmpeg | 已实现但产品质量仍需持续验收 |
| 原创音乐 | 音乐圣经、MusicProvider、BGM 对齐、资产包 | 部分接入，默认关闭 |
| 口型 | LipSync Provider 抽象、策略与桥接 | 部分接入；当前真实 LipSync Provider 全部禁用 |
| 素材库 | 类型、别名、分镜号/范围、选中/候选/淘汰、Range 播放、下载 | 已实现 |
| 队列 | 14 队列、任务幂等、重试、取消、过期恢复、人工介入 | 已实现但部分任务类型无 Worker 执行器 |
| 成本 | Provider 成本规则、调用日志、人民币展示、额度冻结/释放 | 已实现；财务口径仍需统一 |
| 支付 | 套餐、订单模型与 mock-pay | 仅测试，不是生产支付 |
| 内容审核 | 文本、素材、后台复核、案例授权 | API/UI 已实现，但当前 `ContentReview` 为 0 条 |
| 爆款诊断 | 样本、片段、创意模式、项目绑定 | 已实现，属于原设计后的扩展 |

## 5. 数据库结构

### 5.1 总体规模

- Prisma Model：61 个。
- Prisma Enum：0 个。
- 数据库迁移：33 个，当前全部已部署。
- 索引、唯一约束和 JSON 字段大量使用。
- 业务状态主要使用字符串字段，而不是数据库枚举。

### 5.2 模型分组

#### 用户与项目

- `User`
- `UserModelPreference`
- `Project`
- `ProjectPipelineConfig`
- `ProjectCreativePattern`
- `CreativePattern`

#### 小说与 Agent

- `NovelSource`
- `NovelChapter`
- `NovelReadingProgress`
- `NovelBookmark`
- `NovelAnnotation`
- `NovelGenerationPlan`
- `NovelChapterVersion`
- `NovelContextMemory`
- `NovelQualityReport`
- `NovelVersionSnapshot`
- `NovelDerivativeJob`
- `AgentPrompt`
- `AgentRun`

#### 故事、版权与世界观

- `CopyrightRecord`
- `StoryBible`
- `WorldBible`

#### 角色与 IP 资产

- `Character`
- `StoryCharacter`
- `CharacterExtractionVersion`
- `GlobalCharacter`
- `GlobalCharacterAsset`
- `GlobalCharacterLookVersion`
- `CharacterImage`
- `CharacterImageQualityReview`
- `CharacterMemory`
- `CharacterDesignVersion`
- `CharacterPromptVersion`
- `CharacterPromptReview`
- `CharacterPromptOptimizationLesson`
- `CharacterState`
- `ActorProfile`
- `ProjectVisualAsset`

#### 剧集生产

- `Episode`
- `EpisodeScript`
- `StoryboardShot`
- `ShotImage`
- `VideoClip`
- `PlotMemory`
- `PlotThread`
- `ContinuityCheck`

#### 素材、任务与 Provider

- `Asset`
- `RenderTask`
- `ProviderConfig`
- `ProviderLog`

#### 计费、审核与运营

- `Order`
- `QuotaAccount`
- `QuotaLog`
- `RevisionRequest`
- `ContentReview`
- `CaseShowcase`
- `HitAnalysisCase`
- `HitAnalysisSegment`
- `AnalyticsEvent`
- `SystemConfig`
- `OperationLog`

### 5.3 当前数据库数据快照

| 数据 | 数量 |
| --- | ---: |
| 用户 | 2 |
| 项目 | 20 |
| 小说源 | 10 |
| 小说章节 | 256 |
| 故事圣经 | 13 |
| 项目角色 | 87 |
| 全局角色 | 14 |
| 分集 | 87 |
| 单集剧本 | 21 |
| 分镜 | 114 |
| 素材 | 977 |
| 任务 | 748 |
| Provider 配置 | 112 |
| Provider 调用日志 | 1002 |
| 内容审核记录 | 0 |
| 操作审计记录 | 44 |

素材构成：

| 类型 | 数量 |
| --- | ---: |
| image | 600 |
| video_clip | 215 |
| video | 74 |
| audio | 50 |
| subtitle | 33 |
| 其他角色图、片段音频、成品类型 | 5 |

任务状态：

| 状态 | 数量 |
| --- | ---: |
| success | 646 |
| failed | 77 |
| manual_required | 22 |
| pending | 2 |
| completed | 1 |

`completed` 不在当前 `TASK_STATUSES` 常量中，属于历史状态漂移，需要迁移或兼容处理。

## 6. API 接口现状

### 6.1 总量

- Controller：25 个。
- HTTP 方法装饰器：289 个。
- API 全局前缀：`/api`。
- 当前没有生成 OpenAPI/Swagger 规范，接口事实依赖 Controller、DTO 与前端 client。

### 6.2 分组

| 接口域 | 代表能力 | 路由规模 |
| --- | --- | ---: |
| Admin | 仪表盘、项目、用户、素材、作品、Provider、成本、审计、Router | 47 |
| Characters | 项目角色、全局角色、版本、状态、IP 资产、Prompt、声音 | 47 |
| Projects | 项目、库、阅读入口、创意模式、流水线配置 | 28 |
| Live Action | 角色档案、关键帧、视频、QC、候选、渲染、音乐 | 21 |
| Novel Generation | 生成计划、IP 圣经、章节、批次、暂停恢复 | 17 |
| Providers | 目录、配置、执行、日志、成本、偏好 | 16 |
| Billing | 套餐、订单、额度、冻结/释放、后台调整 | 13 |
| Scripts | 剧本、分镜、请求预览、确认、重生 | 12 |
| Memories | 剧情、角色、伏笔、上下文、连续性 | 11 |
| Images | 角色图、关键帧、锚点、视觉质检 | 9 |
| Queues | 创建、列表、重试、取消、恢复、统计 | 9 |
| Reviews | 文本/素材审核、案例授权、后台复核 | 9 |
| Novels / Wizard / Original | 导入、解析、原创、创作向导 | 16 |
| Assets | 上传、预览、Range 下载、临时 URL | 7 |
| Auth / Crypto | 登录注册、用户信息、加密会话 | 7 |
| Episodes / StoryBible / Media | 分集、故事圣经、音频字幕视频 | 14 |

### 6.3 安全边界

- 业务接口主要使用 JWT Guard。
- 管理能力在 Service 层执行 permission 检查。
- Worker 内部接口使用 `WORKER_SECRET` 和 timing-safe 比较。
- 生产环境缺失 Worker secret 时不会使用本地默认值。
- 素材为私有存储，支持鉴权下载、Range 请求和带签名的临时 URL。
- API Key 经服务端密钥加密存储，后台不回显明文。

## 7. 前后端目录结构

### 7.1 后端

```text
backend/src/
├── admin/
├── ai-router/
├── assets/
├── auth/
├── billing/
├── characters/
├── common/
├── config/
├── episodes/
├── images/
├── live-action/
├── media/
├── memories/
├── novels/
├── prisma/
├── projects/
├── provider-lab/
├── providers/
├── queues/
├── reviews/
├── scripts/
├── story-bibles/
└── users/
```

当前后端约 9.39 万行 TypeScript。最大文件：

- `live-action.service.ts`：约 1.42 万行。
- `characters.service.ts`：约 7443 行。
- `providers.service.ts`：约 6776 行。
- `admin.service.ts`：约 6096 行。
- `scripts.service.ts`：约 4600 行。

### 7.2 用户端

```text
user-app/src/
├── api/
├── components/tools/CreativeTools.vue
├── pages/index/index.vue
├── pages/auth/
├── pages/help/
├── pages/projects/
├── pages/user/
├── App.vue
├── workflow.ts
└── styles.css
```

当前约 2.37 万行，主要功能集中在 `index.vue`、`api/client.ts` 和全局 CSS。

### 7.3 管理端

```text
admin/src/
├── api/client.ts
├── api/crypto.ts
├── App.vue
├── main.ts
└── styles.css
```

`router/`、`stores/`、`views/` 当前只有占位文件。管理端约 1.34 万行。

### 7.4 Worker

```text
workers/src/main.ts
```

每个队列由 BullMQ Worker 消费，任务本体通过内部 HTTP 接口委托后端执行，Worker 本身不重复实现业务逻辑。

## 8. 当前 AI 调用流程

### 8.1 通用 Provider 流程

```mermaid
flowchart LR
  Input[业务输入] --> Preference[用户/项目模型偏好]
  Preference --> Config[ProviderConfig]
  Config --> Limit[启停、优先级、成本上限]
  Limit --> Execute[ProvidersService]
  Execute --> Sync[同步文本/图片/音频]
  Execute --> Async[异步视频提交与轮询]
  Sync --> Log[ProviderLog]
  Async --> Log
  Log --> Asset[Asset / VideoClip]
  Log --> Task[RenderTask 状态与成本]
  Execute --> Fallback[失败回退或人工介入]
```

### 8.2 Provider 现状

- Provider 配置共 112 个。
- Mock 配置 11 个，其中 10 个启用、1 个 LipSync mock 关闭。
- Real 配置 101 个，其中 64 个启用、37 个关闭。
- 当前已启用的真实 Provider 覆盖 Text、Novel、Image、Video、Voice、Music、Embedding、Moderation。
- 真实 LipSync Provider 当前全部关闭。
- 代表性已启用模型族：OpenAI、豆包/火山、DeepSeek、Qwen、Kimi、智谱、MiniMax、Kling、Seedance、Seedream、Sora 等。
- 全局默认仍为 mock，显式选择真实 Provider 时可产生真实调用。

Provider 日志当前共 1002 条：

| 状态 | 数量 |
| --- | ---: |
| success | 825 |
| failed | 170 |
| running | 5 |
| cancelled | 2 |

数据库 `cost_actual` 原始累计值为 354.9416。由于 Provider 成本币种和历史规则可能不同，该值只能用于技术对账，不能直接视为财务账单。

近期真实使用主要集中在：

- `openai-image`。
- `kling-v3-native-audio-720p-video`。
- `openai-responses-text`。
- `volcengine_seedance_20_mini`。
- `volcengine-seedream-50-image`。
- `openai-tts`。

### 8.3 真人短剧流程

```text
剧本/外部提示词
-> 动态分镜与前后镜关系
-> 角色/场景/道具资产计划
-> Prompt Engine
-> 关键帧
-> 视频 Provider 预检与成本估算
-> 单镜或批量视频、多候选
-> 自动 QC / 重试 / Fallback / 人工选择
-> Scene Composer 计划
-> 字幕 / 源音轨 / TTS / BGM / SFX / 转场
-> FFmpeg 合成
-> 成品与素材库
```

当前支持的后期参数包括：源音轨、额外音频、字幕、BGM、SFX、环境音、无源音轨回退 SFX、口型、字幕模式和音量控制。原创音乐与 Scene Composer 由项目配置控制，默认并非全部开启。

### 8.4 小说流程

```text
创作 Brief / 导入小说
-> 生成计划
-> IP/故事/世界观规则
-> Agent Prompt
-> 章节草稿
-> 质量报告
-> 自动修复或重写
-> 章节版本与上下文记忆
-> 小说快照
-> 听书/短剧派生任务
```

小说新引擎代码已形成，但目前自动测试和管理体验还没有达到可无人值守批量生产的程度。

## 9. 队列任务流程

### 9.1 队列与任务

BullMQ 队列共 14 个：

```text
novel_queue
parse_queue
story_queue
character_queue
episode_queue
script_queue
storyboard_queue
image_queue
audio_queue
subtitle_queue
video_queue
qc_queue
review_queue
analytics_queue
```

任务类型共 21 个，状态包括：

```text
pending / running / success / failed / retrying
cancelled / manual_required / skipped
```

### 9.2 执行链

```mermaid
flowchart LR
  API[API 创建 RenderTask] --> Idempotency[输入哈希 / 幂等键]
  Idempotency --> Queue[BullMQ 入队]
  Queue --> Worker[独立 Worker]
  Worker --> Secret[WORKER_SECRET]
  Secret --> Delegate[backend internal/worker execute]
  Delegate --> Provider[通用 Provider 执行]
  Delegate --> Live[真人视频业务执行]
  Provider --> Result[日志 / 素材 / 状态]
  Live --> Result
  Result --> Retry[按类型自动重试]
  Retry --> Manual[耗尽后 manual_required]
```

已实现：

- 幂等键与输入哈希。
- 不同任务类型的默认重试次数。
- 任务取消与队列 Job 清理。
- stale running 任务恢复。
- 失败后自动重试与人工介入。
- 队列统计。

### 9.3 当前队列覆盖缺口

任务目录比 Worker 执行器更宽。以下任务在当前 `providerTypeForTask` 中没有实际 Provider 映射，也不属于真人业务执行器，走通用 Worker 时会被标记为 `skipped`：

- `long_memory_generate`
- `subtitle_generate`
- `live_action_keyframe_generate`
- `live_action_video_render`
- `analytics_event`

其中部分能力目前由同步 Service 方法直接执行，因此功能本身不一定不可用；但“全部已队列化”的说法不准确。`video_render` 在通用任务映射中指向 `VideoProvider`，与 FFmpeg 合成语义也需要重新核对。

## 10. 已实现但未完整写入原设计文档的功能

相较 `docs/system_a`、`docs/system_b` 的早期设计，当前代码额外出现或显著深化了：

1. 小说创作向导、章节 Agent、上下文构建、质量修复、版本快照与派生任务。
2. 小说阅读器、书签、批注、阅读进度。
3. 全局角色资产、外观版本、角色状态、角色 Prompt 版本与审核经验闭环。
4. 人物三视图独立工具，以及“主锚点参考/本次描述覆盖”两种模式。
5. 三视图视觉质量评分、问题提取、优化经验进入下一次生成。
6. 项目级场景/道具/IP 资产中心和主资产版本。
7. 动态分镜时长、前后镜衔接、转场字段、请求预览与 Prompt 人工覆盖。
8. 真人短剧 AI Router、镜头评分、成本预检、候选视频与自动质量闭环。
9. Kling 原生音频、Seedance、Seedream、Hailuo、Sora 等多模型目录。
10. Scene Composer、字幕/BGM/SFX/环境音开关、源音轨策略和原创音乐包。
11. 素材别名、选中/候选/淘汰状态、按分镜号和范围联合筛选。
12. Provider Lab、模型偏好、人民币成本标签和 Provider 调用审计。
13. 爆款诊断、拉片片段、创意模式和项目模式绑定。
14. API 应用层加密、临时素材签名 URL、视频 Range 流式播放。

## 11. 与原设计文档的主要差异

| 领域 | 原设计世界 | 当前代码现实 |
| --- | --- | --- |
| 产品定位 | 系统 A 小说转漫剧 + 系统 B 真人写真 | 已合并演化为小说、短剧、视频、角色/IP 资产、创作工具平台 |
| 用户端 | uni-app 多页面 | Vue 3 + Vite H5，核心集中在单一大页面 |
| 管理端 | GeekerAdmin | 自研 Vue 单页后台，未引入完整 GeekerAdmin 架构 |
| 数据库 | 约 20 个核心表 | 61 个 Model、33 个迁移 |
| Provider | 抽象层与少量真实模型 | 112 个配置，覆盖大量国内外文本/图像/视频/声音模型 |
| AI Router | 后续路由能力 | 已用于真人视频，但未成为全平台统一入口 |
| 小说 | 原创 mock + 导入改编 | 已加入 Agent、质量循环、版本、阅读器和派生任务 |
| 分镜 | 固定镜头/宫格倾向 | 动态时长、上下镜关系、首尾帧/多图、转场与声音层 |
| 视频 | 图片、TTS、字幕、简单合成 | 真人视频候选、QC、原生音频、Scene Composer、复杂 FFmpeg 后期 |
| 队列 | 所有生产任务统一异步 | Worker 已运行，但部分声明任务没有异步执行器，部分流程仍同步 |
| 存储 | MinIO 优先设计 | 当前实际使用本地私有存储，MinIO 未完整配置 |
| 支付 | 订单支付闭环 | 额度与 mock-pay 可用，真实支付未接入 |
| 审核 | 内容审核闭环 | API/UI 已有，但数据库没有实际审核记录 |
| 测试 | 文档定义生产验收 | 后端单测有覆盖但当前 35 条失败，前后端无自动测试 |
| 版本管理 | 设计文档持续推进 | Git 只有初始提交，大量现实代码尚未形成版本基线 |

## 12. 当前待优化问题

### P0：必须先处理

#### 12.1 Git 无法代表当前系统

- `main` 只有 1 个提交。
- 当前有 85 个修改项、47 个未跟踪项。
- 多个数据库迁移、小说新引擎、Provider Lab、人物三视图、数据与文档都未纳入提交。

风险：服务器故障、误操作或换机后，无法从 Git 恢复当前系统。

建议：先做数据库与素材备份，再把当前状态拆成可审阅提交；不要把生成素材和临时文件混入源码提交。

#### 12.2 测试未达到发布基线

后端结果：

```text
Test Files: 19 passed / 8 failed
Tests:      238 passed / 35 failed
```

失败主要分为：

1. 新增 Prisma 依赖后，旧测试 mock 没有补齐。
2. 动态分镜、质量闸门、BGM/SFX 策略改变后，旧期望未更新。
3. Provider 成本标签新增人民币后，断言仍使用旧文案。
4. Seedance 真人参考图预检策略出现测试与实现不一致。

应逐条判断“测试旧了”还是“代码回归”，不能简单批量改断言。

#### 12.3 当前运行进程未加载最新构建

审计期间全仓构建通过，但 backend 和 worker 进程启动时间早于最新构建产物。需要在备份、测试和变更确认后执行受控重启，并做健康检查与核心链路冒烟测试。

### P1：高优先级

#### 12.4 队列执行覆盖不完整

补齐或明确移出队列：长篇记忆、字幕、真人关键帧、真人合并、分析事件。避免任务显示已入队，Worker 最后却标记 `skipped`。

#### 12.5 状态字段漂移

数据库中存在历史 `completed`，当前代码只认 `success`。项目、任务、素材、审核等大量状态均为自由字符串。建议建立状态字典、迁移脚本和兼容测试。

#### 12.6 本地素材是单机风险点

当前 977 个素材使用本地私有存储，MinIO 未完整配置，部署目录中也没有可执行备份脚本。至少需要：

- 数据库定时备份。
- `storage/private` 增量备份。
- 恢复演练。
- 磁盘容量与失败告警。

#### 12.7 任务和调用失败积压

- RenderTask：77 failed、22 manual_required、2 pending。
- ProviderLog：170 failed、5 running。

需要区分历史测试垃圾、外部异步任务和真实待处理任务，并提供批量归档/恢复策略。

#### 12.8 Provider 配置过多且默认策略不清晰

数据库中有 112 个 Provider 配置，但全局默认仍是 mock。真实 Provider 启停、用户偏好、项目偏好、Router 和显式 provider_code 同时存在，容易出现“页面选了 A，实际走 B”的理解成本。

建议为每次调用固定记录并展示：请求 Provider、路由原因、实际 Provider、模型、参数、输入参考图、成本和回退链。

#### 12.9 外部 Provider 素材 URL 配置需复核

当前公开素材基础 URL 未设置，而部分第三方视频/图片 Provider 需要可访问的临时参考图 URL。应把此项纳入 Provider preflight，而不是运行到提交时才失败。

#### 12.10 审核闭环尚未实际使用

`ContentReview` 当前为 0 条。需要确认是入口未触发、审核结果写到了其他字段，还是生产流程绕过了正式审核。

### P2：结构性优化

#### 12.11 超大文件与前端单体化

- `live-action.service.ts` 约 1.42 万行。
- 用户端主页面约 1.35 万行。
- 管理端主页面约 1.03 万行。

这会放大回归风险和协作冲突。建议按稳定业务边界逐步拆分，不做一次性大重构。

#### 12.12 缺少前后端自动测试与正式 E2E

用户端、管理端目前没有测试文件。后端以单元测试为主，没有覆盖“登录 -> 项目 -> 分镜 -> 真实 Provider -> 素材 -> 合并”的稳定 E2E。

#### 12.13 API 缺少机器可读契约

当前 289 个接口依赖 TypeScript DTO 和手写 client，没有 OpenAPI 文档与自动 client 生成。接口数量继续增长后，前后端容易漂移。

#### 12.14 生产运维不完整

`deploy/` 只有开发 compose、Nginx 示例和说明，没有落地的发布、回滚、备份、日志轮转、监控和告警脚本。当前主要依靠 systemd 日志与人工检查。

#### 12.15 真实支付、多租户和财务对账未完成

- 支付仍为 mock-pay。
- 当前是用户级数据隔离，没有组织/租户模型。
- `cost_actual` 的币种与财务账单口径需统一。

## 13. 建议建立的唯一真相机制

### 13.1 Work 负责

```text
产品定位
业务规则
架构决策
未来路线
功能设计文档
```

### 13.2 Git + Codex 负责

```text
当前代码
数据库迁移
实现细节
测试结果
部署与运行事实
```

### 13.3 同步规则

每个重要功能建议使用以下闭环：

```text
Work 讨论
-> FEATURE_xxx_V1.md
-> Codex 实现
-> 测试与部署
-> 更新 CHANGELOG.md
-> 更新 PROJECT_STATUS_Vn.md
-> 回灌 Work
```

状态文档不应每次全量覆盖，而应保留 V1、V2、V3，便于追踪系统如何演化。

## 14. 建议放入 Work 的首批资料

```text
AI 内容生产平台/
├── 01_项目现状/
│   └── PROJECT_STATUS_V1.md
├── 02_架构设计/
│   └── SYSTEM_ARCHITECTURE.md
├── 03_小说引擎/
│   └── NOVEL_ENGINE.md
├── 04_短剧引擎/
│   └── DRAMA_ENGINE.md
├── 05_AI流水线/
│   └── AI_PIPELINE.md
├── 06_数据库/
│   └── DATABASE.md
└── 07_版本记录/
    └── CHANGELOG.md
```

本次只生成真实状态基线。其余文档应以本文件为依据重新整理，而不是直接复制旧系统 A/B 文档并假定其全部已实现。

## 15. 本次验证记录

已执行并确认：

- 全仓生产构建通过。
- Prisma schema 可用。
- 33 个迁移与当前数据库一致。
- 后端健康检查通过。
- backend 与 worker systemd 服务正在运行。
- MySQL、Redis、Nginx 正在运行。
- 数据库只读数量与 Provider/任务状态统计完成。
- 自动测试执行完成，并如实记录 35 条失败。

未执行：

- 未重启生产服务。
- 未修改数据库数据。
- 未触发新的付费 AI 生成。
- 未做浏览器端完整 E2E。
- 未做数据库或素材恢复演练。