oh-my-muse/design-docs/后端-04-统一数据库Schema-v1.md

后端-04：统一数据库 Schema(结构定义)-v1

• 版本：v7
• 更新日期：2026-05-13
• 目标读者：后端/架构/前端/数据库维护者
• 阅读时间：35–55 分钟
• 边界说明：本文件只定义持久化模型、表结构职责、关系、约束与索引策略；流程与状态跳转细节统一引用 架构-04-状态机与约束清单.md，接口输入输出统一引用 后端-05-统一API契约-v1.md。本文描述目标 Schema(结构定义)，不代表当前代码或 migration 都已实现。

1. 目标

这份 Schema(结构定义) 只做一件事：把 Muse 的双轨模型落成不会自相矛盾的数据结构。

本版直接固化以下设计决策：

• Block.content 使用结构化 jsonb，不再退回纯文本。
• Work 直接持有导入/解析状态，不另建工作流状态总表。
• Shadow(待审层) 只存待审对象；历史进入 Archive(归档层)/Audit。
• 异步作业状态与审核状态分离：作业进 *_jobs，待审对象进 suggestions / proposals。
• 保留 work_id 冗余字段，但必须用复合唯一键与复合外键保证一致性，禁止只靠应用层“记得写对”。
• 所有业务主键和外键统一使用自定义字符串 ID，不再使用 UUID 或自增整数作为目标态业务 ID。
• 知识 Canonical(规范数据) 使用 jsonb 快照，但必须补属性级变更日志，不能把来源链路弄丢。
• meta_schemas 采用三维分类：domain（content/world/narrative）+ scope（work/chapter/entity/relation/event）+ target_type。
• Narrative State(叙事状态) 的运行态值不能只靠 meta_schemas；work / chapter / entity 三个 scope 必须有真实持久化载体。
• PG 是唯一事实源；RAGFlow 和 Graph Query Provider 都是 PG 的投影，通过 projection_outbox 异步同步。Neo4j 只是不满足 GraphRAG 能力时的条件交付 provider。
• Proposal 携带 source snapshot（source_kind/ref_id/revision/content_hash），用于 stale draft 检测。
• 管理员(Admin)配置能力进入 Admin BC，不混入普通用户作品工作台。
• Sa-Token 作为认证授权基座，负责登录认证、RBAC、接口鉴权、会话与 Token 生命周期、当前用户上下文和基础审计上下文。
• 全局知识库(Global Knowledge Base)与局域知识库(Local Knowledge Base)分层；全局知识库授权不自动写入作品事实。
• 元数据可见性至少表达 ui_visible、ai_context、user_editable、user_searchable、exportable。
• New-API 继续负责模型供应商、路由、用户分组限流、Token 成本策略和消耗日志；Muse 只同步用户、分组、配额、套餐和绑定状态。

2. 总体原则

2.1 持久化对象分类

系统内持久化对象按事实层级分类，不能把配置、事实、待审对象、任务和投影混成一张万能表。

类别	说明	代表表
Canonical(规范数据)	用户确认后的事实数据	works / chapters / blocks / knowledge_entities / knowledge_relations / knowledge_events / narrative_states
Shadow(待审层) Active(活跃层)	仍待审核的建议/提案	suggestions / proposals
Job	异步生成、解析、批处理状态	generation_jobs / extraction_jobs
Configuration(系统配置)	管理员配置、版本、启停和授权策略	roles / permissions / user_roles / role_permissions / system_service_identities / meta_schemas / meta_fields / prompt_versions / agent_configs / global_knowledge_bases / global_knowledge_access_policies / newapi_user_bindings / newapi_plan_mappings / evaluation_datasets
History / Audit	已完成审核、审计或评测记录	suggestion_archive / proposal_archive / audit_logs / knowledge_attribute_changes / evaluation_runs
Projection	投影基础设施（PG → 外部存储的异步同步）	projection_outbox / projection_watermarks / ragflow_id_mappings
Infrastructure(基础设施)	非业务实体的系统支撑表	id_sequence_segments

2.2 通用列约定

• 主键和业务外键默认使用 varchar(96)，由应用层 ID 生成器生成，不使用数据库自增或 UUID 默认值。长度放宽到 96 是为了容纳表名大写对象码，例如 GLOBAL_KNOWLEDGE_ACCESS_POLICIES。
• 时间统一使用 timestamptz。
• 状态字段统一使用 text + CHECK，不使用 PostgreSQL 原生 enum，避免以后迁移把自己卡死。
• 计数字段统一为非负整数，写入端负责维护，读端允许按需回算校验。
• 所有跨表 ownership 约束优先使用复合唯一键 + 复合外键；只有表达不了的“写一次后不可改”规则才考虑触发器。

2.3 自定义字符串 ID 规则

目标态业务 ID 统一格式：

<OBJECT_CODE><YYYYMMDD><SEQ6><RAND6><HHMMSS>

ID 不带额外分隔符，示例：WORKS20260512000001A1B2C3153045。如果表名本身包含下划线，下划线属于对象码本身，不作为 ID 片段分隔符。

组成说明：

片段	规则
OBJECT_CODE	默认采用所属表名大写，例如 USERS、WORKS、CHAPTERS、BLOCKS、KNOWLEDGE_ENTITIES；确需例外时必须在 S0-ID spec 中登记
YYYYMMDD	生成日期，固定使用 Asia/Shanghai
SEQ6	按 OBJECT_CODE + YYYYMMDD 独立递增的 6 位取号器，左侧补 0
RAND6	6 位大写 Base36 随机片段；应用层使用 Java SecureRandom 生成，不要再称为 UUID
HHMMSS	生成时间，补充可读性和粗粒度排序信息

取号器由数据库号段表管理，服务每次按对象码和日期领取 1000 个号段，并立即把数据库起始值推进到下一个未分配号段；服务进程只在内存中消费已领取号段。服务重启后未消费号段直接作废，重新领取下一个未分配号段，避免重复取号。

取号器超过 999999 时必须失败并告警，不能静默扩位破坏 ID 格式。API 契约对外只暴露字符串 ID，不再暴露迁移前的数字 ID 或 UUID。

迁移范围包含 users.id，以及作品、章节、Block、任务、建议、提案、知识、配置、审计、投影等所有业务和配置对象。对象码采用“表名大写 + 文档登记 + 代码常量”双维护：本文件和 S0-ID spec 是对象码的设计证据，代码实现必须用 enum 或常量集中定义；不引入数据库元数据表动态管理对象码。

S0-ID 采用停机清库/重建，不做双写过渡。基于“当前无重要数据，可以全部清理”的已确认前提，迁移方式改为清库/重建/重置式迁移：删除现有 schema，重建 schema，重新执行 migration，重新生成最小 smoke 数据，并一次性改表、改代码、改前端类型后跑全量回归。

该口径默认允许用于本地、隔离测试库和当前远程开发库。执行清理前必须记录环境标识、数据库连接摘要、操作者和清理范围；不要求快照或备份。若进入有价值数据或生产数据环境，必须停止执行该口径，重新评审是否需要数据保留和映射迁移方案。

最小 smoke 数据只覆盖验证主链路所需对象：管理员用户、普通用户、角色、权限、示例作品、章节、Block、基础 Prompt/Agent/MetaSchema/New-API 绑定配置，以及一组可触发建议、提案、知识确认和用量反馈的测试样本。不在 S0-ID 阶段重建完整演示小说样本。

2.4 冗余 work_id 的约束策略

既然决定保留冗余 work_id，那就别装作没成本。

必须满足：

• chapters 提供唯一键 (work_id, id)。
• blocks 提供唯一键 (work_id, id)，并通过 (work_id, chapter_id) 复合外键绑定到 chapters。
• knowledge_entities 提供唯一键 (work_id, id)。
• suggestions、proposals、knowledge_relations 只要同时保存 work_id 和下游对象 ID，就必须走复合外键校验同属一个 work。

2.5 新产品形态表结构处理矩阵

本节只定义目标处理方式，不表示所有对象都已落地为当前 migration。

分类	对象	处理原则
优先复用	meta_schemas、narrative_states、knowledge_entities、knowledge_relations、generation_jobs、extraction_jobs、audit_logs	作品规划台、叙事状态、知识确认和任务记录优先复用这些目标模型；不要为每个 UI 面板新增孤立表
扩展字段	元数据可见性字段、知识库访问策略字段、任务来源和审计字段	在已有模型能承载时优先扩展字段；必须保留版本、来源、操作者和权限上下文
倾向新增	roles、permissions、user_roles、role_permissions、system_service_identities、prompt_versions、agent_configs、newapi_user_bindings、newapi_plan_mappings、global_knowledge_bases、global_knowledge_access_policies、evaluation_datasets、evaluation_runs	这些属于认证授权、系统级配置、授权或评测能力，适合独立建模；具体聚合职责见 后端-01
明确不新增	local_knowledge_bases 独立表	局域知识库由 work_id + knowledge_entities / knowledge_relations / knowledge_events / narrative_states 隐式表达，不单独建容器表
明确不新增	usage_logs 本地明细表或本地汇总表	New-API 是成本账本权威；Muse 只在任务记录、审计和个人中心响应中保留 New-API 引用、同步状态和任务级 usage 摘要

作品规划台(Planning Desk)的数据结构优先复用 MetaSchema、narrative_states、knowledge_entities、knowledge_relations、Work、Chapter 和 Block。产品可写“情节节拍 / 场景推进”，但本版不新增小说场景(Scene)独立一级表。

3. 表结构

3.1 Auth / User

users

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	用户 ID
email	text	NOT NULL, UNIQUE	登录邮箱，应用层统一 lower-case
display_name	text	NOT NULL	显示名称
password_hash	text	NOT NULL	Argon2id 哈希
status	text	NOT NULL, default 'active', CHECK IN ('active', 'pending_deletion')	用户状态
deletion_requested_at	timestamptz	nullable	进入删除缓冲期的时间
deleted_at	timestamptz	nullable	物理删除前的最终标记时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

补充约束：

• status = 'pending_deletion' 时，deletion_requested_at 必须非空。
• status = 'active' 时，deleted_at 必须为空。

roles

Sa-Token 使用的最小角色表。角色表达接口和后台能力，不表达某个作品的正文或知识确认权。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	角色 ID
role_key	text	NOT NULL, UNIQUE	角色标识，例如 admin、user
role_name	text	NOT NULL	角色名称
description	text	nullable	说明
builtin	boolean	NOT NULL, default false	是否内置角色
status	text	NOT NULL, default 'active', CHECK IN ('active', 'disabled')	状态
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

内置角色至少包含：

• admin：管理员控制台(Admin Console)能力。
• user：普通用户(User Workspace / Personal Center)能力。

permissions

Sa-Token 使用的最小权限点表。权限点用于接口鉴权、菜单展示和审计解释，不替代业务用例内的作品级校验。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	权限 ID
permission_key	text	NOT NULL, UNIQUE	权限标识，例如 admin:prompts:write、workspace:works:read
permission_name	text	NOT NULL	权限名称
resource_type	text	NOT NULL	资源类型，如 admin_api、workspace_api、personal_api、system_job
action	text	NOT NULL	动作，如 read、write、execute
description	text	nullable	说明
builtin	boolean	NOT NULL, default false	是否内置权限
status	text	NOT NULL, default 'active', CHECK IN ('active', 'disabled')	状态
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

user_roles

字段	类型	约束	说明
user_id	varchar(96)	NOT NULL, FK → users.id ON DELETE CASCADE	用户
role_id	varchar(96)	NOT NULL, FK → roles.id ON DELETE CASCADE	角色
assigned_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	分配人
assigned_at	timestamptz	NOT NULL, default now()	分配时间

约束：

• PK (user_id, role_id)。

role_permissions

字段	类型	约束	说明
role_id	varchar(96)	NOT NULL, FK → roles.id ON DELETE CASCADE	角色
permission_id	varchar(96)	NOT NULL, FK → permissions.id ON DELETE CASCADE	权限
assigned_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	分配人
assigned_at	timestamptz	NOT NULL, default now()	分配时间

约束：

• PK (role_id, permission_id)。

system_service_identities

系统任务(System Job)服务身份表。服务身份用于投影消费、索引重建、同步重试、评测执行和清理任务，不允许伪装成普通用户做作品事实确认。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	服务身份 ID
service_key	text	NOT NULL, UNIQUE	服务身份标识，例如 projection-worker
service_name	text	NOT NULL	展示名称
permission_scope	jsonb	NOT NULL, default '{}'::jsonb	允许执行的系统任务范围
status	text	NOT NULL, default 'active', CHECK IN ('active', 'disabled')	状态
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• 服务身份只能进入明确的后台任务入口。
• 服务身份写入审计时必须标记 actor_type='system_job' 或等价语义。
• 服务身份不得调用确认正文、确认知识草稿、接受 AI 候选等普通用户决策接口。

id_sequence_segments

自定义字符串 ID 的数据库号段表。它不是业务实体，只负责保证同一 OBJECT_CODE + YYYYMMDD 下不会重复分配取号器区间。

字段	类型	约束	说明
object_code	text	NOT NULL	对象码，如 USERS、WORKS、CHAPTERS、BLOCKS
yyyymmdd	char(8)	NOT NULL	生成日期
next_value	int	NOT NULL, CHECK next_value BETWEEN 1 AND 1000000	下一个未分配取号器起始值
segment_size	int	NOT NULL, default 1000, CHECK segment_size > 0	每次领取号段大小
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• PK (object_code, yyyymmdd)。
• 服务领取号段时必须在同一事务内锁定当前行，并把 next_value 推进到 next_value + 1000。
• 已领取但未消费的内存号段在服务重启后直接作废，不允许回收复用。

3.2 Content BC(内容上下文)

works

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	作品 ID
user_id	varchar(96)	NOT NULL, FK → users.id ON DELETE RESTRICT	所属用户
title	text	NOT NULL	标题
genre	text	NOT NULL	题材
summary	text	nullable	简介
work_schema_id	varchar(96)	nullable, FK → meta_schemas.id ON DELETE SET NULL	绑定的作品级 Schema(结构定义)，要求 scope='work'
status	text	NOT NULL, default 'writing', CHECK IN ('writing', 'completed', 'archived')	作品状态
word_count	int	NOT NULL, default 0, CHECK word_count >= 0	总字数
chapter_count	int	NOT NULL, default 0, CHECK chapter_count >= 0	章节数
imported_at	timestamptz	nullable	导入完成时间；只能从 null 写一次
import_error	text	nullable	导入失败原因
parse_status	text	NOT NULL, default 'not_parsed', CHECK IN ('not_parsed', 'parsing', 'parsed', 'parse_failed')	解析状态
parse_progress	int	nullable, CHECK parse_progress BETWEEN 0 AND 100	解析进度百分比
parse_error	text	nullable	解析失败原因
parsed_at	timestamptz	nullable	解析成功完成时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

补充约束：

• parsed_at 只能在 parse_status = 'parsed' 时非空。
• parse_status = 'not_parsed' 时，parsed_at 必须为空。
• imported_at 是 write-once 字段，应用层和触发器都要拒绝二次写入。

chapters

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	章节 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
title	text	NOT NULL	章节标题
order_index	int	NOT NULL	作品内顺序
summary	text	nullable	章节摘要
block_count	int	NOT NULL, default 0, CHECK block_count >= 0	Block(文本块) 数
word_count	int	NOT NULL, default 0, CHECK word_count >= 0	章节字数
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (work_id, order_index)
• UNIQUE (work_id, id)

blocks

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Block(文本块) ID
work_id	varchar(96)	NOT NULL	冗余所有权，用于复合约束与热路径过滤
chapter_id	varchar(96)	NOT NULL	所属章节
order_index	int	NOT NULL	章节内顺序
content	jsonb	NOT NULL	Tiptap(富文本编辑器)/结构化文档内容
revision	int	NOT NULL, default 1, CHECK revision > 0	乐观锁版本
word_count	int	NOT NULL, default 0, CHECK word_count >= 0	当前 Block(文本块) 字数
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, chapter_id) → chapters(work_id, id) ON DELETE CASCADE
• UNIQUE (chapter_id, order_index)
• UNIQUE (work_id, id)

说明：

• content 是唯一 Canonical(规范数据) 正文载体；不再额外存 status='canonical' 这种废话字段。
• revision 是写入锚点，任何正文写操作都必须基于它。

3.3 AI BC(人工智能上下文)：Job

generation_jobs

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	生成任务 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
requested_by	varchar(96)	NOT NULL, FK → users.id ON DELETE RESTRICT	触发用户
target_block_id	varchar(96)	nullable	目标 Block(文本块)
suggestion_type	text	NOT NULL, CHECK IN ('continuation', 'rewrite', 'expand', 'planning', 'check')	建议类型；覆盖写作台与作品规划台 AI 辅助
context_block_ids	jsonb	NOT NULL, default '[]'::jsonb	上下文 Block(文本块) ID 列表
request_source	text	NOT NULL, default 'writing_desk', CHECK IN ('writing_desk', 'planning_desk', 'knowledge_check', 'import_parse', 'admin_evaluation')	任务来源，用于区分写作、规划、检查、解析或评测触发
config_snapshot	jsonb	NOT NULL, default '{}'::jsonb	PromptVersion、AgentConfig、上下文策略、New-API 绑定和全局知识授权快照摘要
audit_context	jsonb	NOT NULL, default '{}'::jsonb	请求 ID、入口、用户意图、来源解释等审计上下文；禁止写正文全文
status	text	NOT NULL, default 'queued', CHECK IN ('queued', 'running', 'succeeded', 'failed', 'canceled')	作业状态
pipeline_step	text	nullable, CHECK IN ('generating', 'extracting', 'validating', 'risk_routing', 'regenerating')	Generation Pipeline 内部步骤追踪；只在 status=running 时有意义；外部 API（GenerationJobSummary）不暴露此字段（v4 修正：新增字段，支持 Pipeline 内部多步追踪）
error_code	text	nullable	失败代码
error_message	text	nullable	失败信息
started_at	timestamptz	nullable	开始时间
finished_at	timestamptz	nullable	完成时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, target_block_id) → blocks(work_id, id) ON DELETE SET NULL

extraction_jobs

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	提取任务 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
requested_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	发起用户；导入批处理可为空
trigger_type	text	NOT NULL, CHECK IN ('accept_suggestion', 'import_parse', 'manual_extract', 'block_save', 'planning_confirm')	触发来源
scope_type	text	NOT NULL, CHECK IN ('block', 'work')	提取范围
source_block_id	varchar(96)	nullable	来源 Block(文本块)
source_suggestion_archive_id	varchar(96)	nullable	来源建议归档 ID
request_source	text	NOT NULL, default 'writing_desk', CHECK IN ('writing_desk', 'planning_desk', 'knowledge_check', 'import_parse', 'admin_evaluation')	任务来源
config_snapshot	jsonb	NOT NULL, default '{}'::jsonb	提取、校验、风险路由使用的配置快照摘要
audit_context	jsonb	NOT NULL, default '{}'::jsonb	来源、请求和审计上下文；禁止写正文全文
status	text	NOT NULL, default 'queued', CHECK IN ('queued', 'running', 'succeeded', 'failed', 'canceled')	作业状态
error_code	text	nullable	失败代码
error_message	text	nullable	失败信息
started_at	timestamptz	nullable	开始时间
finished_at	timestamptz	nullable	完成时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, source_block_id) → blocks(work_id, id) ON DELETE SET NULL
• FK (source_suggestion_archive_id) → suggestion_archive(id) ON DELETE SET NULL

3.4 AI BC(人工智能上下文)：Shadow(待审层) Active(活跃层)

suggestions

Active(活跃层) 表只存待审对象。行存在，就意味着 pending_review；接受、拒绝、过期后必须迁出到 suggestion_archive。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Suggestion(建议) ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
generation_job_id	varchar(96)	NOT NULL, UNIQUE, FK → generation_jobs.id ON DELETE CASCADE	来源生成任务
target_block_id	varchar(96)	nullable	目标 Block(文本块)
suggestion_type	text	NOT NULL, CHECK IN ('continuation', 'rewrite', 'expand')	建议类型
anchor_type	text	NOT NULL, CHECK IN ('replace_block', 'insert_after_block', 'replace_range')	锚点类型
anchor_payload	jsonb	NOT NULL	锚点细节：位置、范围、上下文摘要
base_block_revision	int	NOT NULL, CHECK base_block_revision > 0	生成时绑定的 Block(文本块) revision
content	jsonb	NOT NULL	建议内容，结构与 blocks.content 同型
source_context	jsonb	nullable	生成上下文摘要
conflict_warning	jsonb	nullable	预检测冲突说明
expires_at	timestamptz	NOT NULL	过期时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, target_block_id) → blocks(work_id, id) ON DELETE SET NULL
• expires_at > created_at

proposals

Active(活跃层) 表只存待审提案。终态进入 proposal_archive。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Proposal(提案) ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
extraction_job_id	varchar(96)	NOT NULL, FK → extraction_jobs.id ON DELETE CASCADE	来源提取任务
parse_job_id	varchar(96)	nullable, FK → extraction_jobs.id ON DELETE CASCADE	全书解析批次 ID；仅 trigger_type='import_parse' 时使用，通常等于该行的 extraction_job_id
chapter_id	varchar(96)	nullable	关联章节；全书解析场景下必填，表示当前 Proposal 属于哪个章节批次
suggestion_id	varchar(96)	nullable, FK → suggestions.id ON DELETE SET NULL	关联的 Suggestion(建议)；生成链路中 Proposal 通过此字段关联到 Suggestion，实现 Knowledge Draft 数据合同
entity_id	varchar(96)	nullable	关联实体；创建新实体时为空
proposal_type	text	NOT NULL, CHECK IN ('create_entity', 'update_attribute', 'add_relation')	提案类型
stage	text	NOT NULL, default 'raw', CHECK IN ('raw', 'validated')	内部校验阶段
risk_level	text	nullable, CHECK IN ('low', 'medium', 'high', 'critical')	风险级别（v7 修正：新增 critical）
dedupe_group	text	nullable	去重分组 ID
conflict_summary	jsonb	nullable	冲突摘要
proposed_data	jsonb	NOT NULL	提议写入的数据
current_data	jsonb	nullable	当前 Canonical(规范数据) 快照
source_block_id	varchar(96)	nullable	来源 Block(文本块)
source_kind	text	nullable	来源类型：block / suggestion / parse_job（v7 新增，Source Snapshot 合同）
source_ref_id	varchar(96)	nullable	来源引用 ID（v7 新增）
source_block_revision	int	nullable	来源 Block revision（v7 新增）
source_content_hash	text	nullable	来源内容 hash，用于 stale draft 检测（v7 新增）
expires_at	timestamptz	NOT NULL	过期时间
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, entity_id) → knowledge_entities(work_id, id) ON DELETE SET NULL
• FK (work_id, chapter_id) → chapters(work_id, id) ON DELETE SET NULL
• FK (work_id, source_block_id) → blocks(work_id, id) ON DELETE SET NULL
• expires_at > created_at
• parse_job_id 与 chapter_id 只在全书解析场景使用：parse_job_id IS NOT NULL 时，chapter_id 必须非空
• source_kind='parse_job' 时，parse_job_id、chapter_id、source_content_hash 必须非空
• 缺少 source_kind、source_ref_id、source_block_revision 或 source_content_hash 的历史 Proposal 在新链路下全部视为 stale draft，必须重新提取；不得 best-effort 补 snapshot 后继续确认
• 同一章节批量确认边界由 parse_job_id + chapter_id 决定；Schema 允许同一边界下存在多条 Proposal，但确认提交必须由状态机按章节事务循环保证 all-or-nothing，不能实现成跨章节大事务

3.5 AI BC(人工智能上下文)：Archive(归档层)

suggestion_archive

字段	类型	约束	说明
id	varchar(96)	PK	沿用原 Suggestion(建议) ID
work_id	varchar(96)	NOT NULL	所属作品
generation_job_id	varchar(96)	NOT NULL	来源任务
target_block_id	varchar(96)	nullable	原目标 Block(文本块)
suggestion_type	text	NOT NULL	建议类型
anchor_type	text	NOT NULL	锚点类型
anchor_payload	jsonb	NOT NULL	锚点快照
base_block_revision	int	NOT NULL	生成时 revision
original_content	jsonb	NOT NULL	原建议内容
final_content	jsonb	nullable	用户修改 Block 后合并时写入正文的最终内容快照（仅用于归档/审计）
disposition	text	NOT NULL, CHECK IN ('accepted', 'rejected', 'expired')	终态
disposition_reason	text	nullable	拒绝说明/过期原因
archived_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	审核人；系统过期时为空
archived_at	timestamptz	NOT NULL	归档时间
merged_block_id	varchar(96)	nullable	接受后写入的 Block(文本块)
merged_block_revision	int	nullable	接受后 Block(文本块) 的 revision
source_context	jsonb	nullable	生成上下文
conflict_warning	jsonb	nullable	冲突警告
created_at	timestamptz	NOT NULL	原始创建时间

proposal_archive

字段	类型	约束	说明
id	varchar(96)	PK	沿用原 Proposal(提案) ID
work_id	varchar(96)	NOT NULL	所属作品
extraction_job_id	varchar(96)	NOT NULL	来源任务
parse_job_id	varchar(96)	nullable	全书解析批次 ID 快照
chapter_id	varchar(96)	nullable	章节批次快照
entity_id	varchar(96)	nullable	原实体
proposal_type	text	NOT NULL	提案类型
stage	text	NOT NULL	归档前阶段
risk_level	text	nullable	风险级别
dedupe_group	text	nullable	去重分组
conflict_summary	jsonb	nullable	冲突摘要
proposed_data	jsonb	NOT NULL	提议数据
current_data	jsonb	nullable	原快照
source_block_id	varchar(96)	nullable	来源 Block(文本块)
source_kind	text	nullable	来源类型快照
source_ref_id	varchar(96)	nullable	来源引用 ID 快照
source_block_revision	int	nullable	来源 Block revision 快照
source_content_hash	text	nullable	来源内容 hash 快照；用于 stale 检测留痕
disposition	text	NOT NULL, CHECK IN ('accepted', 'rejected', 'expired')	终态
disposition_reason	text	nullable	拒绝/过期原因
archived_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	审核人；系统过期时为空
archived_at	timestamptz	NOT NULL	归档时间
applied_entity_id	varchar(96)	nullable	接受后最终作用到的实体
applied_snapshot	jsonb	nullable	接受后的实体快照
created_at	timestamptz	NOT NULL	原始创建时间

3.6 Knowledge BC(知识上下文)

knowledge_entities

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	实体 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
name	text	NOT NULL	实体名
entity_type	text	NOT NULL	实体类型，如 character / location / item，由 MetaSchema(domain=world, scope=entity) 定义
entity_schema_id	varchar(96)	nullable, FK → meta_schemas.id ON DELETE SET NULL	绑定的实体 Schema(结构定义)，要求 scope='entity'
attributes	jsonb	NOT NULL, default '{}'::jsonb	当前 Canonical(规范数据) 属性快照
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (work_id, name, entity_type)
• UNIQUE (work_id, id)

knowledge_relations

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	关系 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
source_entity_id	varchar(96)	NOT NULL	起点实体
target_entity_id	varchar(96)	NOT NULL	终点实体
relation_type	text	NOT NULL	关系类型，由 MetaSchema(domain=world, scope=relation) 定义
description	text	nullable	关系描述
properties	jsonb	nullable	关系属性（JSONB），字段结构由 MetaSchema 约束
since_chapter	int	nullable	关系生效起始章节序号
until_chapter	int	nullable	关系失效章节序号，NULL 表示仍然有效
source_block_id	varchar(96)	nullable	来源 Block(文本块)
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, source_entity_id) → knowledge_entities(work_id, id) ON DELETE CASCADE
• FK (work_id, target_entity_id) → knowledge_entities(work_id, id) ON DELETE CASCADE
• FK (work_id, source_block_id) → blocks(work_id, id) ON DELETE SET NULL
• CHECK (source_entity_id <> target_entity_id)
• UNIQUE (work_id, source_entity_id, target_entity_id, relation_type)

knowledge_events

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	事件 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
event_type	text	NOT NULL	事件类型，如 突破、相遇、冲突、转折，由 MetaSchema(domain=world, scope=event) 定义
description	text	NOT NULL	事件描述
chapter_order	int	NOT NULL	事件发生的章节序号
source_block_id	varchar(96)	nullable	来源 Block
properties	jsonb	NOT NULL, default '{}'::jsonb	事件属性（JSONB），包含 involves（参与实体列表）和 causes（因果效果列表），字段结构由 MetaSchema 约束
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间
deleted	boolean	NOT NULL, default false	软删除标记

knowledge_attribute_changes

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	变更记录 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
entity_id	varchar(96)	NOT NULL	目标实体
attribute_key	text	NOT NULL	属性键
change_type	text	NOT NULL, CHECK IN ('set', 'unset', 'merge')	变更类型
old_value	jsonb	nullable	旧值
new_value	jsonb	nullable	新值
source_type	text	NOT NULL, CHECK IN ('proposal_accept', 'manual_edit', 'import')	来源类型
source_proposal_archive_id	varchar(96)	nullable	来源归档提案
source_block_id	varchar(96)	nullable	来源 Block(文本块)
changed_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	操作者
created_at	timestamptz	NOT NULL, default now()	变更时间

约束：

• FK (work_id, entity_id) → knowledge_entities(work_id, id) ON DELETE CASCADE
• FK (work_id, source_block_id) → blocks(work_id, id) ON DELETE SET NULL
• FK (source_proposal_archive_id) → proposal_archive(id) ON DELETE SET NULL

narrative_states

Narrative State(叙事状态) 的运行态值载体。meta_schemas(domain=narrative) 只定义字段形状，真正的运行态值必须落在这里，而不是挂在 Schema 定义本身。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	叙事状态记录 ID
work_id	varchar(96)	NOT NULL, FK → works.id ON DELETE CASCADE	所属作品
scope	text	NOT NULL, CHECK IN ('work', 'chapter', 'entity')	运行态作用域；只允许三个可写 scope
chapter_id	varchar(96)	nullable	scope='chapter' 时必填
entity_id	varchar(96)	nullable	scope='entity' 时必填
schema_id	varchar(96)	nullable, FK → meta_schemas.id ON DELETE SET NULL	对应的 narrative Schema(结构定义)
state_payload	jsonb	NOT NULL, default '{}'::jsonb	当前叙事状态值，如弧线进度、章节意图、角色目标/动机
source_type	text	NOT NULL, CHECK IN ('manual_edit', 'proposal_accept', 'batch_confirm')	最近一次写入来源
source_proposal_archive_id	varchar(96)	nullable, FK → proposal_archive.id ON DELETE SET NULL	由提案确认写入时记录来源
invalidated_at	timestamptz	nullable	失效时间；内容改写导致需要重提取时写入
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• FK (work_id, chapter_id) → chapters(work_id, id) ON DELETE CASCADE

• FK (work_id, entity_id) → knowledge_entities(work_id, id) ON DELETE CASCADE

• scope='work' 时，chapter_id 与 entity_id 必须为空

• scope='chapter' 时，chapter_id 必须非空，entity_id 必须为空

• scope='entity' 时，entity_id 必须非空，chapter_id 必须为空 唯一性：

• work scope：UNIQUE (work_id, scope) WHERE scope='work'

• chapter scope：UNIQUE (work_id, scope, chapter_id) WHERE scope='chapter'

• entity scope：UNIQUE (work_id, scope, entity_id) WHERE scope='entity'

3.7 Admin BC(管理上下文)

meta_schemas

meta_schemas 只定义字段、校验规则和继承关系。对于 domain='narrative'，它不是运行态存储；运行态值统一进入 narrative_states。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Schema(结构定义) ID
schema_key	text	NOT NULL, UNIQUE	稳定标识，如 xuanhuan_work / character_base
name	text	NOT NULL	展示名称
description	text	nullable	描述
scope	text	NOT NULL, CHECK IN ('work', 'chapter', 'entity', 'relation', 'event')	Schema(结构定义) 作用域
target_type	text	NOT NULL	work 作用域时表示作品类型；entity 作用域时表示实体类型；relation/event 作用域时表示关系/事件类型
domain	text	NOT NULL, DEFAULT 'world', CHECK IN ('content', 'world', 'narrative')	领域分类：content(创作容器) / world(世界模型) / narrative(叙事模型)（v7 新增）
parent_schema_id	varchar(96)	nullable, FK → meta_schemas.id ON DELETE SET NULL	父 Schema(结构定义)
is_builtin	bool	NOT NULL, default false	是否内置
version	int	NOT NULL, default 1, CHECK version > 0	配置版本；变更时创建新版本或保留可追溯变更记录
status	text	NOT NULL, default 'active', CHECK IN ('draft', 'active', 'disabled', 'archived')	配置状态
ui_visible	bool	NOT NULL, default true	该 Schema(结构定义)对应对象是否允许在普通用户 UI 展示
ai_context	bool	NOT NULL, default false	该 Schema 对象是否默认允许进入 AI 上下文
user_editable	bool	NOT NULL, default false	普通用户是否默认可编辑该 Schema 对象
user_searchable	bool	NOT NULL, default true	普通用户是否默认可检索该 Schema 对象
exportable	bool	NOT NULL, default true	是否默认允许随作品导出
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建者
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (scope, target_type, name)
• UNIQUE (domain, scope, target_type, name)（v7 修正：三维分类唯一约束）

meta_fields

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	字段 ID
schema_id	varchar(96)	NOT NULL, FK → meta_schemas.id ON DELETE CASCADE	所属 Schema(结构定义)
field_key	text	NOT NULL	字段键
field_label	text	NOT NULL	字段显示名
field_type	text	NOT NULL, CHECK IN ('text', 'number', 'enum', 'boolean', 'array', 'reference')	字段类型
is_required	bool	NOT NULL, default false	是否必填
default_value	jsonb	nullable	默认值
enum_options	jsonb	nullable	枚举选项
reference_target_type	text	nullable	引用类型：仅 reference 时有效
validation_rules	jsonb	NOT NULL, default '{}'::jsonb	范围、正则、数组长度等规则
order_index	int	NOT NULL	字段顺序
ui_visible	bool	NOT NULL, default true	字段是否在普通用户 UI 展示
ai_context	bool	NOT NULL, default false	字段是否允许进入 AI 上下文
user_editable	bool	NOT NULL, default false	普通用户是否可编辑该字段
user_searchable	bool	NOT NULL, default true	普通用户是否可检索该字段
exportable	bool	NOT NULL, default true	字段是否允许随作品导出
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (schema_id, field_key)
• UNIQUE (schema_id, order_index)
• 字段级可见性优先于 Schema 默认值；ui_visible=false 不代表 ai_context=false。
• 可见性变更必须写入审计，并触发用户可见投影重建或失效标记。

prompt_versions

指令模板(Prompt)版本表。Prompt 是系统级配置，普通用户不能通过作品工作台读取或修改原始 Prompt。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Prompt 版本 ID
prompt_key	text	NOT NULL	稳定标识，如 generation.default / planning.chapter
prompt_type	text	NOT NULL, CHECK IN ('system', 'task', 'genre', 'style', 'planning', 'validation')	Prompt 类型
version	int	NOT NULL, CHECK version > 0	版本号，同 prompt_key 下递增
status	text	NOT NULL, default 'draft', CHECK IN ('draft', 'active', 'disabled', 'archived')	生命周期状态
content	text	NOT NULL	Prompt 正文
variables_schema	jsonb	NOT NULL, default '{}'::jsonb	变量结构与必填规则
rollout_policy	jsonb	NOT NULL, default '{}'::jsonb	灰度、回滚、适用范围
change_summary	text	nullable	变更摘要
activated_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	激活人
activated_at	timestamptz	nullable	激活时间
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (prompt_key, version)
• 同一 prompt_key 同一时间最多一个 active 版本。
• 已激活版本不得原地静默修改；需要变更时创建新版本或显式回滚。

agent_configs

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	Agent 配置 ID
agent_key	text	NOT NULL	稳定标识，如 generation.default / extraction.block
agent_type	text	NOT NULL, CHECK IN ('generation', 'extraction', 'validation', 'planning', 'retrieval')	Agent 类型
version	int	NOT NULL, CHECK version > 0	版本号
status	text	NOT NULL, default 'draft', CHECK IN ('draft', 'active', 'disabled', 'archived')	生命周期状态
config_payload	jsonb	NOT NULL, default '{}'::jsonb	Muse 侧编排配置，不保存模型供应商路由权威数据
timeout_ms	int	NOT NULL, default 60000, CHECK timeout_ms > 0	超时配置
retry_policy	jsonb	NOT NULL, default '{}'::jsonb	重试策略
fallback_policy	jsonb	NOT NULL, default '{}'::jsonb	降级策略
activated_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	激活人
activated_at	timestamptz	nullable	激活时间
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (agent_key, version)
• 同一 agent_key 同一时间最多一个 active 版本。
• agent_configs 不承载模型供应商、模型路由、用户分组限流、Token 成本策略和 New-API 消耗日志。

global_knowledge_bases

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	全局知识库 ID
kb_key	text	NOT NULL	稳定标识
name	text	NOT NULL	名称
description	text	nullable	描述
version	int	NOT NULL, default 1, CHECK version > 0	内容版本
status	text	NOT NULL, default 'preparing', CHECK IN ('preparing', 'active', 'disabled', 'archived')	生命周期状态
source_type	text	NOT NULL, CHECK IN ('upload', 'ragflow_dataset', 'manual', 'external')	来源类型
source_ref	text	nullable	外部来源引用，如 RAGFlow dataset ID
index_status	text	NOT NULL, default 'not_indexed', CHECK IN ('not_indexed', 'indexing', 'indexed', 'index_failed')	索引状态
metadata	jsonb	NOT NULL, default '{}'::jsonb	体裁、平台、标签等元信息
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (kb_key, version)
• 停用后不得进入新的检索或生成上下文。
• 全局知识库不会自动写入任何作品的局域知识库(Local Knowledge Base)。
• 全局知识库是独立逻辑资料集；即使多个全局知识库共用同一个物理数据库、向量索引或 RAGFlow dataset，也必须保留可过滤的 global_kb_id 或等价资料集标识。

global_knowledge_access_policies

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	访问策略 ID
global_kb_id	varchar(96)	NOT NULL, FK → global_knowledge_bases.id ON DELETE CASCADE	全局知识库
version	int	NOT NULL, default 1, CHECK version > 0	策略版本
status	text	NOT NULL, default 'draft', CHECK IN ('draft', 'active', 'disabled', 'archived')	策略状态
subject_type	text	NOT NULL, CHECK IN ('user', 'user_group', 'plan', 'all_users')	授权对象类型
subject_id	text	nullable	授权对象 ID；all_users 可为空
default_bound	bool	NOT NULL, default false	是否默认绑定
ui_visible	bool	NOT NULL, default false	普通用户是否可见
user_searchable	bool	NOT NULL, default false	普通用户是否可主动检索
ai_context	bool	NOT NULL, default false	是否允许进入 AI 生成上下文
user_bindable	bool	NOT NULL, default false	用户是否可主动绑定
user_unbindable	bool	NOT NULL, default false	用户是否可主动解绑
readonly	bool	NOT NULL, default true	普通用户是否只读使用
active_from	timestamptz	nullable	生效时间
active_until	timestamptz	nullable	失效时间
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• 没有 active 策略时，全局知识库不得展示、检索或进入生成上下文。
• 策略变更不得改写任何作品的局域知识库事实。
• 全局知识库版本和访问策略版本可独立回滚。
• 授权撤销后的权限边界是请求时计算允许使用的 global_kb_id 列表；被撤销资料集不得进入检索请求和上下文组装。
• 如果授权对象共用同一个物理索引或数据库，检索条件必须包含 global_kb_id IN allowedIds 或等价过滤条件；异步索引失效、重建或清理只作为性能和数据清理手段，不能作为权限边界。

newapi_user_bindings

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	绑定 ID
user_id	varchar(96)	NOT NULL, UNIQUE, FK → users.id ON DELETE CASCADE	Muse 用户
newapi_user_id	text	NOT NULL	New-API 侧用户 ID
newapi_group_key	text	nullable	New-API 分组
plan_key	text	nullable	Muse 套餐标识
quota_snapshot	jsonb	NOT NULL, default '{}'::jsonb	最近一次同步得到的配额/套餐摘要
status	text	NOT NULL, default 'syncing', CHECK IN ('syncing', 'active', 'error', 'disabled')	同步状态
last_synced_at	timestamptz	nullable	最后同步时间
last_sync_error	text	nullable	最后同步失败原因
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (newapi_user_id)
• 同步必须幂等；失败保留原因和重试入口。
• 不保存 New-API 模型供应商、模型路由或消耗日志权威数据。

newapi_plan_mappings

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	套餐映射 ID
muse_plan_key	text	NOT NULL	Muse 套餐标识
newapi_group_key	text	NOT NULL	New-API 分组标识
version	int	NOT NULL, default 1, CHECK version > 0	映射版本
status	text	NOT NULL, default 'draft', CHECK IN ('draft', 'active', 'disabled', 'archived')	状态
quota_policy	jsonb	NOT NULL, default '{}'::jsonb	配额策略摘要
package_payload	jsonb	NOT NULL, default '{}'::jsonb	套餐同步所需参数
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (muse_plan_key, version)
• active 映射变更只影响后续 New-API 同步任务，不改写已完成任务记录。

evaluation_datasets

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	评测集 ID
dataset_key	text	NOT NULL	稳定标识
version	int	NOT NULL, CHECK version > 0	版本号
status	text	NOT NULL, default 'draft', CHECK IN ('draft', 'active', 'locked', 'archived')	生命周期状态
scenario	text	NOT NULL	评测场景，如续写、改写、描写、作品规划、实体一致性、角色一致性、角色弧光、世界事实、大纲一致性、细纲一致性、叙事手法、伏笔与回收、张力曲线、节奏与信息释放、主题表达、文风匹配、全书解析、长程连载
scoring_rubric	jsonb	NOT NULL	固定评分标准
dataset_payload	jsonb	NOT NULL	固定输入、参考输出或样本集
locked_at	timestamptz	nullable	首次正式使用后的锁定时间
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	创建人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• UNIQUE (dataset_key, version)
• locked 后不得原地修改样本和评分标准。

evaluation_runs

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	评测运行 ID
dataset_id	varchar(96)	NOT NULL, FK → evaluation_datasets.id ON DELETE RESTRICT	使用的评测集
run_status	text	NOT NULL, default 'queued', CHECK IN ('queued', 'running', 'succeeded', 'failed', 'canceled')	运行状态
tested_config_snapshot	jsonb	NOT NULL, default '{}'::jsonb	被测 Prompt、Agent、上下文策略快照
judge_model_set	jsonb	NOT NULL, default '[]'::jsonb	多模型评审集合
result_summary	jsonb	nullable	算法汇总评分、置信度和指标
risk_summary	jsonb	nullable	风险结论
started_at	timestamptz	nullable	开始时间
finished_at	timestamptz	nullable	完成时间
created_by	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	发起人
created_at	timestamptz	NOT NULL, default now()	创建时间
updated_at	timestamptz	NOT NULL, default now()	更新时间

约束：

• 评测运行只影响系统改进判断，不替代普通用户对正文、规划和作品知识的确认。

3.8 Audit & Projection(审计与投影)

audit_logs

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	审计日志 ID
work_id	varchar(96)	nullable, FK → works.id ON DELETE CASCADE	所属作品；全局认证行为可为空
user_id	varchar(96)	nullable, FK → users.id ON DELETE SET NULL	用户操作者；系统任务可为空
service_identity_id	varchar(96)	nullable, FK → system_service_identities.id ON DELETE SET NULL	系统任务服务身份
actor_role	text	nullable, CHECK IN ('admin', 'user', 'system_job')	操作角色
action	text	NOT NULL	动作名
target_type	text	NOT NULL	目标类型
target_id	varchar(96)	nullable	目标 ID
source_surface	text	nullable, CHECK IN ('admin_console', 'user_workspace', 'personal_center', 'system_job')	来源入口
request_id	text	nullable	请求追踪 ID
metadata	jsonb	NOT NULL, default '{}'::jsonb	结构化上下文；禁止写正文全文
created_at	timestamptz	NOT NULL, default now()	发生时间

projection_outbox

PG 事务内写业务数据 + outbox，保证原子性。投影消费者从 outbox 幂等消费，用 PG 稳定业务 ID 做幂等键。 只有 Canonical(规范数据) 正文与已确认知识会写入正式投影；suggestions / proposals 里的 Shadow draft 永不直接进入正式检索。

字段	类型	约束	说明
id	varchar(96)	PK, 应用层生成	消息 ID
work_id	varchar(96)	NOT NULL	所属作品
event_type	text	NOT NULL	事件类型，如 entity_created、attribute_changed、relation_added、event_recorded
payload	jsonb	NOT NULL	事件载荷
projection_target	text	NOT NULL	投影目标：ragflow / graph_provider；若 Graph Query Provider 选型为 Neo4j，则由 graph_provider 消费者写入 Neo4j
created_at	timestamptz	NOT NULL, default now()	创建时间
consumed_at	timestamptz	nullable	消费时间，NULL 表示未消费

projection_watermarks

每个投影目标独立 watermark。Context Assembly 组装时读 watermark 判断投影是否追平，未追平时用 PG overlay 补齐。

字段	类型	约束	说明
work_id	varchar(96)	PK (composite)	所属作品
projection_target	text	PK (composite)	投影目标：ragflow / graph_provider
last_synced_revision	bigint	NOT NULL	最后同步的 revision
last_synced_at	timestamptz	NOT NULL	最后同步时间

3.9 Integration(外部集成)

ragflow_id_mappings

维护 PG 业务 ID ↔ RAGFlow document ID 的映射。Graph Query Provider 若落到 Neo4j，不需要单独映射表——图节点直接使用 PG 稳定业务 ID。

字段	类型	约束	说明
pg_id	varchar(96)	PK (composite)	PG 侧业务 ID（entity ID 或 block ID）
pg_type	text	PK (composite)	PG 侧类型：entity / block
ragflow_doc_id	text	NOT NULL	RAGFlow 侧文档 ID
work_id	varchar(96)	NOT NULL	所属作品
created_at	timestamptz	NOT NULL, default now()	创建时间

4. 外键与删除策略

4.1 Canonical(规范数据)

• users → works：RESTRICT。用户删除必须走缓冲期和应用层编排，不能裸删。
• works → chapters → blocks：CASCADE。作品删除时正文整体删除。
• works → knowledge_entities / knowledge_relations / knowledge_attribute_changes / narrative_states：CASCADE。

4.2 Shadow(待审层) Active(活跃层)

• works → generation_jobs / extraction_jobs / suggestions / proposals：CASCADE。
• blocks → suggestions.target_block_id：SET NULL，保留待审对象直到过期或归档。
• knowledge_entities → proposals.entity_id：SET NULL，保留提案上下文。

4.3 Archive(归档层) / Audit

• Archive(归档层) 表不反向依赖 Active(活跃层) 表。
• Archive(归档层) 中保留原始业务 ID 与快照，允许下游对象被删除后仍保留审核证据。
• audit_logs.user_id 使用 SET NULL，避免因用户删除破坏审计链。

5. 索引策略

5.1 热路径

索引	类型	用途
works(user_id, updated_at DESC)	B-tree	用户作品列表
chapters(work_id, order_index)	B-tree, UNIQUE	章节树
blocks(work_id, chapter_id, order_index)	B-tree	章节 Block(文本块) 有序分页
suggestions(work_id, target_block_id, created_at DESC)	B-tree	Block(文本块) 待审建议
proposals(work_id, created_at DESC)	B-tree	提案列表
proposals(parse_job_id, chapter_id, created_at DESC)	B-tree	全书解析章节批量确认边界查询
generation_jobs(work_id, status, created_at DESC)	B-tree	生成作业查询
extraction_jobs(work_id, status, created_at DESC)	B-tree	提取作业查询
knowledge_entities(work_id, entity_type, name)	B-tree	实体列表/筛选
knowledge_relations(work_id, source_entity_id)	B-tree	关系展开
narrative_states(work_id, scope)	B-tree, partial UNIQUE	work scope Narrative State 读取
narrative_states(work_id, scope, chapter_id)	B-tree, partial UNIQUE	chapter scope Narrative State 读取
narrative_states(work_id, scope, entity_id)	B-tree, partial UNIQUE	entity scope Narrative State 读取
prompt_versions(prompt_key, version)	B-tree, UNIQUE	Prompt 版本追溯
prompt_versions(prompt_key) WHERE status='active'	B-tree, partial UNIQUE	每个 Prompt 当前 active 版本
agent_configs(agent_key, version)	B-tree, UNIQUE	Agent 配置版本追溯
agent_configs(agent_key) WHERE status='active'	B-tree, partial UNIQUE	每个 Agent 当前 active 版本
global_knowledge_bases(kb_key, version)	B-tree, UNIQUE	全局知识库版本
global_knowledge_access_policies(global_kb_id, subject_type, subject_id, status)	B-tree	授权判断
newapi_user_bindings(user_id)	B-tree, UNIQUE	用户绑定读取
newapi_plan_mappings(muse_plan_key, version)	B-tree, UNIQUE	套餐映射版本
evaluation_datasets(dataset_key, version)	B-tree, UNIQUE	评测集版本
evaluation_runs(dataset_id, created_at DESC)	B-tree	评测运行历史
audit_logs(source_surface, created_at DESC)	B-tree	管理员/用户入口审计筛选

5.2 JSONB(二进制JSON)

索引	类型	用途
knowledge_entities(attributes)	GIN	按属性路径查询
suggestions(anchor_payload)	GIN	锚点范围查询
meta_fields(validation_rules)	GIN	规则检索/调试

（v4 修正：移除 knowledge_entities(embedding) HNSW/IVFFlat 向量索引，向量检索改为 RAGFlow）

说明：

• 语义检索由 RAGFlow 提供，不再依赖 PostgreSQL 向量索引。

6. 迁移建议

6.1 必须一次定死的东西

• blocks.content 的结构化 JSON(结构化文本) 形态
• works 的导入/解析状态字段
• Shadow(待审层) Active(活跃层) 与 Archive(归档层) 分层
• meta_schemas.scope + target_type
• 元数据可见性字段：ui_visible、ai_context、user_editable、user_searchable、exportable
• knowledge_attribute_changes
• narrative_states 作为 Narrative State 真实运行态载体
• proposals.parse_job_id + chapter_id 作为 Full Parse(全书解析) 章节批量确认边界
• 管理员配置对象的版本与启停语义：prompt_versions、agent_configs、global_knowledge_bases、global_knowledge_access_policies、evaluation_datasets

6.2 可以后补的东西

• 更细粒度的 anchor_type
• Archive(归档层) 查询 API(接口)
• 不建 local_knowledge_bases 显式表；局域知识库由 work_id + knowledge_* / narrative_states 表达
• 不建 usage_logs 显式表或本地 usage 汇总表；用户可见用量由 New-API 汇总和 Muse 任务级 usage 摘要生成

6.3 与完整建表 SQL 的同步口径

后端-04a-完整建表SQL.sql 当前标注为 V1-V18 实际落地 SQL，不是本文件目标 Schema 的自动展开。只有当这些目标结构进入正式 migration 设计时，才同步改 后端-04a；不能为了让 SQL 看起来完整而把尚未确认的目标表伪装成已落地事实。

7. 非目标

以下内容不在本版 Schema(结构定义) 中解决：

• 多人协同编辑
• 版本回滚到任意历史快照
• 草稿层（用户私有 Draft(草稿层)）与 Canonical(规范数据) 的双层正文模型
• 通用任务编排平台
• 把 New-API 的模型供应商、路由、成本策略和消耗日志复制到 Muse 作为新事实源
• 为作品规划台每个 UI 面板单独建表

8. 关联阅读

• 模型与双轨规则：架构-02-核心数据结构与双轨模型.md
• 接口契约：后端-05-统一API契约-v1.md
• 生命周期与约束：架构-04-状态机与约束清单.md
• 完整建表 SQL（当前实际落地状态）：后端-04a-完整建表SQL.sql