ai/docs/work-sync/06_数据库/DATABASE_CURRENT_V1.md

数据库现状与维护规范 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. 关键关系

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 成本币种、精度和财务流水口径。