# 数据库现状与维护规范 V1

> 文档状态：当前有效  
> 基线日期：2026-07-15  
> 唯一结构真相：`backend/prisma/schema.prisma` 与 `backend/prisma/migrations/`。

## 1. 当前事实

- 数据库：MySQL。
- ORM：Prisma 6。
- Model：69 个。
- Prisma Enum：0 个。
- 已部署迁移：40 个。
- 迁移状态：审计时全部已部署。
- 状态字段主要是字符串，存在历史值漂移风险。

本文只解释领域结构和维护规则，不复制所有字段。字段、索引、默认值和约束以 Prisma schema 为准。

## 2. 领域分组

### 2.1 用户、项目与偏好

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

### 2.2 小说与 Agent

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

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

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

### 2.4 角色与 IP 资产

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

### 2.5 剧集与媒体生产

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

### 2.6 素材、任务与 Provider

- `Asset`
- `RenderTask`
- `ProviderConfig`
- `ModelCapabilityVersion`
- `ModelParameterSchemaVersion`
- `ModelPricingVersion`
- `ProviderLog`

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

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

### 2.8 S+ 生产合同

- `ProductionSourceSnapshot`
- `ProductionContract`
- `ProductionContractReview`

`Project.engine_version` 隔离历史写路径与 `splus_v1` 新内核；`Project.production_lifecycle` 记录当前生产阶段。数据库默认值保持 `legacy_v1 / legacy_snapshot`，避免迁移把历史项目误标为新项目；应用层只为普通新项目明确写入 `splus_v1`。

## 3. 关键关系

```text
User
└── Project
    ├── NovelSource -> NovelChapter -> ChapterVersion/Quality/Memory
    ├── StoryBible / WorldBible
    ├── Character / ProjectVisualAsset
    ├── Episode -> EpisodeScript -> StoryboardShot
    │                               ├── ShotGenerationPlan
    │                               ├── ShotImage
    │                               └── VideoClip
    ├── Asset
    ├── RenderTask
    └── ProductionSourceSnapshot
        └── ProductionContract -> ProductionContractReview

ProviderConfig -> ModelCapabilityVersion/ModelParameterSchemaVersion/ModelPricingVersion
ShotGenerationPlan -> 三类不可变模型注册表版本 -> ShotImage/VideoClip/RenderTask
ProviderConfig -> ProviderLog -> Asset/业务对象
GlobalCharacter -> LookVersion/Asset/CharacterProviderBinding -> Project Character/ActorProfile
```

全局角色与项目角色不是同一层：全局角色用于复用演员母版，项目角色承载本项目身份、服装、状态和授权范围。

生产合同按类型、范围和版本追加写入；已确认版本不原地覆盖。来源快照保存正文与哈希，合同保存父版本、输入哈希、来源引用、质量结果和下游放行状态。

`ProviderConfig` 是允许运营调整的工作配置，不作为历史执行凭证。每次 S+ 镜头冻结前，系统按规范化内容哈希发布或复用三类不可变注册表版本，并把版本 ID 和内容快照写入 `ShotGenerationPlan`。能力、参数 Schema 或价格发生变化时创建下一修订，不更新旧修订。

`CharacterProviderBinding` 保存平台角色与供应商长期角色资产之间的真实绑定。当前字段覆盖供应商与元素 ID、元素类型、源视频、外观版本、声线、质检分、审批状态、主版本和绑定修订。正式生成只读取 `approved` 绑定；镜头冻结后，所用元素 ID 会复制进入 `ShotGenerationPlan.element_plan_json`，后续修改角色主元素不会污染旧计划。

## 4. 数据快照

审计时主要数据量：

| 数据 | 数量 |
| --- | ---: |
| 用户 | 2 |
| 项目 | 20 |
| 小说源 | 10 |
| 小说章节 | 256 |
| 故事圣经 | 13 |
| 项目角色 | 87 |
| 全局角色 | 14 |
| 分集 | 87 |
| 单集剧本 | 21 |
| 分镜 | 114 |
| 素材 | 977 |
| 任务 | 748 |
| Provider 配置 | 114 |
| Provider 调用日志 | 1002 |
| 模型能力版本 | 156 |
| 参数 Schema 版本 | 156 |
| 价格版本 | 114 |
| 角色供应商绑定 | 0 |
| 内容审核记录 | 0 |
| 操作审计记录 | 44 |

该表是 2026-07-15 快照，不应作为实时运营数据使用。实时数量应从数据库只读查询或管理后台获得。

## 5. 状态治理

当前 Prisma 没有数据库 Enum，状态由字符串常量和业务代码约束。已发现 `RenderTask` 中存在历史 `completed`，而当前代码使用 `success`。

后续要求：

1. 每个业务域建立唯一状态字典。
2. API 入参、Service、前端展示和 Worker 共用同一组状态语义。
3. 删除状态前先提供兼容读取和数据迁移。
4. 未知历史状态必须显示为“需迁移”，不能静默当成功或失败。
5. 新状态需更新数据库文档、API 契约和测试。

## 6. JSON 字段规则

JSON 适合保存：

- Provider 原始参数和归一结果。
- Prompt、质量报告和调用快照。
- 非核心扩展元数据。

以下信息不应只存在 JSON：

- 需要频繁筛选、排序或唯一约束的核心字段。
- 业务主状态。
- 资产、角色、分镜和 Provider 的主外键。
- 财务扣减所需的金额和流水关系。

JSON 结构发生兼容性变化时，应写入 `schema_version` 或提供读时迁移。

## 7. 迁移流程

每次 schema 变更必须遵循：

1. 说明业务目的、影响表和回滚策略。
2. 在备份或可恢复环境验证数据量和锁表风险。
3. 修改 `schema.prisma` 并生成命名清晰的迁移。
4. 审阅 SQL，禁止无意删除列、索引或生产数据。
5. 更新受影响的 DTO、Service、测试和前端类型。
6. 运行 Prisma 校验、构建和相关测试。
7. 先部署兼容代码，再执行破坏性清理。
8. 更新 `CHANGELOG.md`、本文件和状态文档。

禁止手工改生产表后不补迁移。

## 8. 备份与恢复

当前数据库和素材都在单机，备份应成对管理：

- MySQL 逻辑备份或一致性快照。
- `storage/private` 增量备份。
- schema、迁移和部署版本标识。
- 备份校验和、保留期和异地副本。

恢复演练必须验证：

1. 数据库可恢复并通过迁移检查。
2. `Asset.storage_key` 对应文件存在。
3. 视频可 Range 播放，图片和音频可下载。
4. RenderTask、ProviderLog 和业务资产关系没有断链。
5. 用户权限和密钥配置不从文档包恢复。

## 9. 隐私与敏感信息

- Work 只上传模型名称、表名、字段职责和聚合统计。
- 不上传用户邮箱、手机号、JWT、API Key、密码哈希或私有素材 URL。
- Provider 原始响应进入日志前需屏蔽鉴权头和签名参数。
- 删除用户或项目时，必须明确数据库记录、素材对象和外部任务的处理策略。

## 10. 当前问题

1. 状态字段自由字符串较多。
2. `completed` 等历史状态未迁移。
3. 本地素材和数据库缺少已验证的成套恢复流程。
4. `ContentReview` 为 0 条，需要确认正式审核是否绕过该模型。
5. 成本字段存在历史币种/口径差异。
6. 69 个 Model 尚无自动生成的数据字典和关系图。

## 11. 下一阶段

- 建立状态字典和历史状态迁移。
- 增加数据库与素材每日备份脚本及恢复演练记录。
- 增加注册表待发布差异预览、管理员确认和回滚到旧修订的操作审计。
- 从 Prisma 自动生成不含敏感值的数据字典。
- 为核心关系增加删除策略和孤儿资产检查。
- 统一 Provider 成本币种、精度和财务流水口径。