feat: expand novel IP and production workflows

2026-09-18 08:14:05 +02:00
parent b2ae4600b4
commit d9c81a3ac0
235 changed files with 117971 additions and 2721 deletions
@@ -0,0 +1,260 @@
+# 数据库现状与维护规范 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 成本币种、精度和财务流水口径。