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

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

• 版本：v11
• 更新日期：2026-07-09
• 目标读者：后端 / 架构 / 前端 / 数据库维护者 / 测试
• 阅读时间：35-55 分钟
• 边界说明：本文件定义 Muse 在 YunaiV/yudao-cloud fork 上新增或二开的业务 Schema 目标。Yudao 原生 system、infra、member、pay、bpm、report、mp 表结构由对应 Yudao 模块负责，本文不重复定义。接口契约见 后端-05-统一API契约-v1.md，状态机见 架构-04-状态机与约束清单.md，工程模块见 后端-02-工程结构与模块职责.md。
• 变更记录：v11（2026-07-09）功能链定义表订正为 muse_meta_function_chain/_version/_node/_slot 归 meta（案 A，见 架构-03 ADR-022），逻辑写入 authority 为 Governance facade 经 meta admin service；MetaSchema target_type 示例去粒度后缀收敛为 character；muse_meta_field 增 storage_binding 存储映射；base 种子目标清单引用 专题-06。

1. 目标

阶段 7 的数据库设计不再以旧 muse-* 自研单体和 PostgreSQL jsonb 快照为基线，而是收束到 Yudao Cloud fork 的模块化落地方式。

本文件只固化以下事情：

1. 哪些数据事实复用 Yudao 原生模块，哪些由 Muse 新业务模块持有。
2. Muse 新增表按 content、knowledge、ai、market、account 等领域 owner 拆分；逻辑 owner 和物理表承载可以不同，但写入 authority 必须唯一。
3. /admin-api/** 和 /app-api/** 只是入口差异，不能拆出两套数据库事实。
4. Shadow -> Canonical、用户主权、知识草稿确认、来源 lineage、授权快照和市场 handoff 必须能在表结构上闭合。
5. 用户替换智能体只作用于开放槽位中的子智能体，输入输出合规、拆分切块、入 RAG、语义安全围栏、静态检查、质量门控等保护节点必须有不可替换的系统级配置和运行证据。
6. 市场购买、安装、绑定和授权不自动写入作品正文、Local KB 或规划正式事实。

2. 数据库基线

2.1 复用 Yudao 原生 Schema

以下能力直接复用 Yudao 原生模块，不在 Muse 业务 Schema 中重建：

能力	Owner 模块	Muse 使用方式
用户、部门、岗位、角色、菜单、权限、登录日志、操作日志	yudao-module-system	Muse 保存 user_id / creator / updater 等引用；权限点和菜单按 Yudao 后台模型配置
字典、配置、文件、定时任务、API 日志、监控	yudao-module-infra	Muse 复用文件、配置、Job、日志、缓存和消息能力
会员/账户基础资料	yudao-module-member	若后续选择改造 member，Muse account 表只保存创作权益和资产聚合，不复制登录身份
支付、充值、退款、订单	yudao-module-pay	市场交易启用时引用支付订单，不把支付清结算事实写进 market asset 表
审核流、申诉流、合规流	yudao-module-bpm	简单审核先由 market 状态机承载；复杂流程再引用 BPM 流程实例
报表、公众号	yudao-module-report / yudao-module-mp	默认隐藏保留，需要时读取 Muse 读模型或事件投影

禁止事项：

• 不新增 muse_users、muse_roles、muse_permissions 来替代 Yudao system。
• 不把 Yudao infra 做成 Muse 业务事实万能表。
• 不复制 New-API 的模型路由、成本账本和调用日志 authority。

2.2 Muse 表命名

Muse 新业务表建议使用统一前缀：

模块	表前缀	示例
内容	muse_content_	muse_content_work
知识	muse_knowledge_	muse_knowledge_draft
AI / Agent	muse_ai_	muse_ai_candidate
市场	muse_market_	muse_market_asset
账户	muse_member_	muse_member_usage_record
来源与授权	muse_source_ / muse_authorization_	muse_source_status_event / muse_authorization_snapshot
审计	muse_audit_	muse_audit_event
Outbox	muse_outbox_	muse_outbox_event
Integration	muse_integration_	muse_integration_call_log

物理落地时可以按 Yudao 代码生成和团队习惯微调表名，但必须保留模块前缀、owner 边界和唯一事实归属。

Owner 约定：

• content 拥有作品、章节、Block、正文版本、Block Source Attribution、Planning Canonical、导入任务、导入文件、章节上下文、导出和下载凭证。
• knowledge 拥有 User KB、Local KB、Knowledge Draft、Knowledge Entity/Relation/Event 和知识来源绑定。
• ai 拥有 Prompt、Agent、Protected Node Registry、Override Slot、Tool Grant 投影、Runtime Permission Envelope、AI Task、Parse Job、Chapter Parse Result、Candidate、Quality Result 和 Candidate Decision Archive。候选记录 source_version，接受时实时对比来源版本。
• market 拥有 Market Asset、License、Authorization、Install、来源侧 Handoff Token、授权摘要、跳转审计、Publish、Review、Governance 和 Appeal；不拥有目标 owner precheck/session。
• account（物理承载于 member 模块）拥有 Muse 创作权益、Usage、Entitlement、个人中心读模型、安全事件和账户导出。
• source/authorization 是横切来源与授权快照 owner：由来源 owner 生成或引用，负责不可变来源快照、授权快照、来源状态事件和传播目标。
• audit/outbox/integration 是横切 owner：由触发动作的业务模块写入业务审计、领域事件和外部调用摘要，不接管 Content / Knowledge / AI / Market / Account 的 Canonical 事实。

2.3 通用列约定

Muse 表默认遵循 Yudao BaseDO 风格：

列	要求
id	物理主键，默认按 Yudao Long / 雪花 ID 风格处理
creator / updater	操作者引用，接 Yudao 当前用户上下文
create_time / update_time	创建和更新时间
deleted	逻辑删除标记，公开查询默认过滤
tenant_id	若启用 Yudao 多租户插件，则作为平台租户隔离字段；不能替代作品 owner 或资产 owner

API 层 ID 规则：

• 前端 TypeScript 统一把业务 ID 当 string 使用。
• 后端物理主键可以是 Long，但不得在 API 文档中承诺自增语义。
• 如果某对象需要跨系统稳定暴露，补 public_id / biz_no，而不是把数据库主键当产品合同。

2.4 JSON 与状态字段

阶段 7 不再写 PostgreSQL 专属 jsonb 作为唯一实现前提。

类型	设计口径
结构化内容	使用数据库 JSON 能力或 Yudao TypeHandler 映射；物理库不支持 JSON 时可用 text 保存结构化 JSON 字符串
状态字段	使用 varchar / tinyint + 代码枚举 + 状态机校验；是否用数据库 CHECK 由具体数据库和 Yudao 迁移策略决定
复杂快照	保存不可变快照摘要、hash、版本和必要字段；敏感正文、完整 Prompt、外部响应全文默认不进快照

2.5 外键约束

本文中的外键是领域约束和建模约束。是否使用数据库物理 FK，由后端落地时按 Yudao 项目实践和线上迁移策略决定。

无论是否创建物理 FK，服务端必须保证：

1. work_id、owner_user_id、source_object_id 等 owner 关系不能只靠前端传参。
2. 跨模块写入必须通过 owner module 的 application service、facade 或领域事件。
3. 高危命令必须有幂等键、审计事件和状态机前置条件。

3. 表分区总览

分区	Owner 模块	核心表
Content	yudao-module-content	Work、Chapter、Block、Block Revision、Block Source Attribution、Planning、Import、Import File、Chapter Context、Export
MetaSchema	yudao-module-meta	MetaSchema、MetaField、MetaVisibilityPolicy、MetaSchemaVersion
Knowledge	yudao-module-knowledge	Knowledge Base、Document、Chunk、Processing Job、Local KB、Knowledge Draft、Knowledge Source Binding
AI / Agent	yudao-module-ai 二开	Prompt、Agent、System Function Chain、Protected Node、Override Slot、Tool Grant、Runtime Envelope、AI Task、Parse Job、Chapter Parse Result、Candidate、Quality Policy、Evaluation
Marketplace	yudao-module-market	Asset、Listing、License、Purchase/Authorization、Install、Collection、Publish、Review、Governance、Appeal、Source-side Handoff
Account	yudao-module-member（已决策）	Profile Extension、Preference、Entitlement Snapshot、Entitlement（可变表）、Entitlement Audit Log、Quota Adjustment、Usage Record、Asset Summary、Security Event、Account Export
Source / Authorization	yudao-module-infra（DDL） + 各业务模块分散写入	Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation
Audit / Outbox / Integration	Muse 业务模块 + Yudao infra	High-risk Audit、Outbox、Projection、Integration Call Log

3.1 表级 Owner 矩阵

本矩阵只说明 Schema owner 和写入边界，不替代接口鉴权。建表 owner 负责 migration、字段演进和唯一约束；写入 owner 负责创建、更新、失效和状态机推进；只读协作者只能通过应用服务、facade、事件投影或查询模型读取。

表	建表 owner	写入 owner	只读协作者	事件传播
muse_content_work	content	content	knowledge / ai / market / account	work 创建、归档和 owner 变化写 outbox
muse_content_chapter	content	content	knowledge / ai	chapter 解析状态变化写 outbox
muse_content_block	content	content	knowledge / ai	block revision 变化触发解析、候选和来源状态重验
muse_content_block_revision	content	content	knowledge / ai / source	revision 创建写 outbox，供来源归因和知识重提取消费
muse_content_block_source_attribution	content	content + source propagation	source / authorization / market / account	Source Status Event 必须传播到此表，更新来源状态但不回滚正文
muse_content_planning_item	content	content	ai / knowledge	planning 变化写 outbox，供 AI 上下文投影消费
muse_content_narrative_state	content	content	ai / knowledge	narrative state 变化写 outbox
muse_content_work_asset_use_precheck	content	content target owner service	market / ai / source	作品资产用于参考、模板或 AI 上下文的目标预检；阶段 7 默认 feature disabled
muse_meta_schema	meta	yudao-module-meta admin service	ai / knowledge / market / account / content	激活、停用、回滚写 outbox，供投影和运行时缓存刷新
muse_meta_field	meta	yudao-module-meta admin service	ai / knowledge / content	随 MetaSchema 版本发布传播
muse_meta_visibility_policy	meta	yudao-module-meta admin service	ai / knowledge / account / content	随 MetaSchema 版本发布传播
muse_meta_schema_version	meta	yudao-module-meta admin service	ai / knowledge / market / account / content	发布、激活、回滚和影响预览写 outbox
muse_content_import_task	content	content	knowledge / ai	导入完成触发 AI parse job 或正文初始化事件
muse_content_import_file	content	content + infra file facade	ai / knowledge / source	上传文件 owner、hash、扫描、保留期和清理策略写 outbox
muse_content_import_chapter_context	content	content	ai / knowledge	章节拆分上下文供 AI Parse Job 读取，不保存解析结果
muse_content_export_task	content	content	source / authorization / account	导出创建、完成、失败和过期写 outbox
muse_content_download_credential	content	content	source / authorization / account	下载凭证签发和失效写审计与 outbox
muse_knowledge_base	knowledge	knowledge	content / ai / market / account	KB 状态变化写 outbox，市场安装引用不反写
muse_knowledge_document	knowledge	knowledge	ai / market	document 变化触发处理任务
muse_knowledge_document_version	knowledge	knowledge	ai / source	version hash 变化触发 chunk / RAG 重建
muse_knowledge_chunk	knowledge	knowledge protected node	ai	chunk 创建只进入检索投影，不反写 Canonical
muse_knowledge_processing_job	knowledge	knowledge protected node	ai / account	处理状态变化写 outbox 和 usage 摘要
muse_knowledge_entity	knowledge	knowledge	content / ai / source	Local KB Canonical 状态受 Source Propagation 阻断新使用
muse_knowledge_relation	knowledge	knowledge	content / ai / source	同 Local KB Canonical
muse_knowledge_event	knowledge	knowledge	content / ai / source	同 Local KB Canonical
muse_knowledge_attribute_change	knowledge	knowledge	content / ai / audit	append-only 变更日志写审计
muse_knowledge_draft	knowledge	knowledge	content / ai / source	draft stale、invalidated、needs_reextract 写 outbox
muse_knowledge_source_binding	knowledge	knowledge	content / ai / market / source	绑定状态受来源事件传播，阻断新检索或生成
muse_knowledge_bind_precheck	knowledge	knowledge target owner service	market / source / account	知识绑定目标预检或签名消费凭证，原子消费后写 source binding
muse_source_snapshot	infra（DDL owner）	各业务模块分散写入	content / knowledge / ai / market / account	创建后不可变，通过引用传播
muse_authorization_snapshot	source/authorization	authorization facade	content / knowledge / ai / market / account	创建后不可变，过期或撤权触发重验
muse_source_status_event	source/authorization	来源 owner + market governance	content / knowledge / ai / market / account	event_key 幂等进入 outbox 并展开传播目标
muse_source_propagation_target	source/authorization	source propagation worker	content / knowledge / ai / market / account	逐目标记录 pending / applied / blocked / failed / skipped
muse_ai_prompt	ai	ai	content / market	prompt 发布状态写 outbox
muse_ai_prompt_version	ai	ai	content / market	版本激活、下架写 outbox
muse_ai_agent	ai	ai	content / market / account	agent 状态变化影响 slot binding 和市场资产
muse_ai_agent_version	ai	ai	content / market / account	版本下架触发绑定重验
muse_meta_function_chain	meta	meta admin service（Governance facade）	ai / content / knowledge	链路激活、停用写 outbox；AI runtime 经 FunctionChainQueryApi 读激活链
muse_meta_function_chain_version	meta	meta admin service（Governance facade）	ai / content / knowledge	function chain 版本激活写 outbox
muse_meta_function_chain_node	meta	meta admin service（Governance facade）	ai / content / knowledge	节点配置随 chain version 发布
muse_ai_protected_node_registry	ai	ai admin service	content / knowledge / audit	保护节点变更写审计和 outbox
muse_meta_function_chain_slot	meta	meta admin service（Governance facade）	ai / content / market	槽位定义变更触发 slot binding 重验
muse_ai_agent_slot_binding	ai	content + ai binding service	market / account / source	仅 active 绑定唯一；授权撤销或版本下架触发失效
muse_ai_agent_slot_precheck	ai	ai target owner service	market / source / account	槽位绑定目标预检或签名消费凭证，原子消费后写 binding
muse_ai_tool_grant	ai	governance/security facade -> ai grant service	content / account / audit	工具授权变更写审计；AI runtime 只能消费授权投影
muse_ai_runtime_permission_envelope	ai	security facade + ai runtime	content / knowledge / audit	每次运行固化权限包并写审计引用，不允许运行中扩权
muse_ai_task	ai	ai runtime	content / knowledge / account	任务状态变化写 outbox 和 usage 摘要
muse_ai_parse_job	ai	ai runtime	content / knowledge / account	全书或章节解析任务状态、重试和失败摘要写 outbox
muse_ai_chapter_parse_result	ai	ai runtime	content / knowledge / source	章节解析 Shadow 结果经用户审阅后请求 Knowledge 生成或刷新 Knowledge Draft
muse_ai_context_snapshot	ai	ai runtime	source / authorization / content / knowledge	上下文组装引用来源和授权快照
muse_ai_candidate	ai	ai runtime	content / knowledge / source	Shadow Candidate 状态变化写 outbox
muse_ai_candidate_quality_result	ai	ai quality service	content / audit	质量门控结果写审计引用
muse_ai_candidate_decision_archive	ai	ai decision archive service	content / knowledge / audit	用户决策归档写 outbox，不确认 Knowledge Draft；Content 只引用 decisionArchiveId
muse_ai_quality_policy	ai	ai admin service	content / market	策略发布写 outbox
muse_ai_quality_policy_version	ai	ai admin service	content / market	版本激活、回滚写 outbox
muse_ai_evaluation_dataset	ai	ai quality service	market / account	数据集发布写 outbox
muse_ai_evaluation_run	ai	ai quality service	market / account	评测运行状态写 outbox
muse_ai_evaluation_result	ai	ai quality service	market / account	评测结果只读给治理和市场审核
muse_market_asset	market	market	content / ai / knowledge / account	资产状态变化写 Source Status Event
muse_market_asset_version	market	market	content / ai / knowledge / source	版本发布、召回写 Source Status Event
muse_market_listing	market	market	account	展示状态写 outbox
muse_market_license	market	market	authorization / account	license 变化触发授权快照重验
muse_market_authorization	market	market	authorization / account / content / ai / knowledge	授权创建、撤销写 Source Status Event 或授权事件
muse_market_purchase_ref	market	market	account / pay	支付引用状态只做摘要传播
muse_market_install	market	market	account / ai / knowledge	安装状态变化触发绑定预检重验
muse_market_bind_precheck	market	market source-side precheck	content / ai / knowledge / source	只保存来源侧许可、版本、治理和跳转摘要，不保存目标 owner 事实
muse_market_handoff_session	market	market	content / ai / knowledge / account	短期 handoff token、授权摘要和跳转审计；目标 owner 负责消费凭证
muse_market_collection	market	market	account	收藏只写个人市场行为，不写作品或安装事实
muse_market_publish_draft	market	market	source / authorization	发布草稿不传播，提交时生成检查快照
muse_market_publish_check_snapshot	market	market	source / authorization / audit	检查快照消费后写审核事件
muse_market_review_submission	market	market	audit / bpm	审核状态写 outbox
muse_market_governance_action	market	market governance	source / authorization / audit	下架、召回、blocked 必须写 Source Status Event
muse_market_appeal	market	market	audit / bpm	申诉状态写 outbox
muse_member_profile_ext	member	member	market / content	个人资料变化写账户读模型事件
muse_member_preference	member	member	content / ai	偏好变化刷新运行时默认值
muse_member_new_api_binding	member	member integration service	ai / audit	网关用户绑定摘要和重验状态，不保存 token 或 provider authority
muse_member_entitlement_snapshot	member	member entitlement service	ai / market	权益快照变化写 outbox
muse_member_entitlement	member	member entitlement service	ai / market / audit	可变权益表，变更时同步写审计日志
muse_member_entitlement_audit_log	member	member entitlement service	ai / market / audit	权益变更审计日志，append-only
muse_member_quota_request	member	member integration service	ai / audit	New-API 额度配置请求、correlationId、幂等和补偿状态
muse_member_quota_adjustment	member	admin member service	ai / audit	管理员调额 append-only，按幂等键去重
muse_member_usage_record	member	member usage service	ai / content / knowledge / market	usage 摘要写个人中心读模型
muse_member_call_attribution_job	member	member attribution service	ai / integration / audit	调用归属、补偿和用户可见解释任务
muse_member_asset_summary	member	member projection worker	market / ai / knowledge	只做读模型投影
muse_member_security_event	member	member / audit	content / market	安全事件 append-only
muse_member_export_task	member	member	content / market / source / authorization	API 应承接导出任务创建、轮询和下载审计
muse_audit_event	audit	动作 owner	全模块	append-only，不反写业务事实
muse_outbox_event	outbox	事实 owner	全模块	event_key 幂等消费
muse_projection_task	integration/outbox	投影 owner	全模块	投影失败可重试，不反写 Canonical
muse_integration_call_log	integration	调用 owner	audit / account	外部调用摘要写审计引用

4. Content Schema

4.1 muse_content_work

作品主表。普通用户的创作项目，也是市场作品资产的源对象之一。

字段语义	要求
id	作品 ID
owner_user_id	所属用户，引用 Yudao 用户
title / genre / summary	作品基础信息
status	writing / completed / archived
work_schema_id	可选，关联 MetaSchema
import_status / parse_status	导入和全书解析摘要状态
word_count / chapter_count	读模型字段，可回算校验

不变式：

• 管理员可以治理异常摘要，但不能直接替用户修改正文事实。
• 市场作品资产发布快照不替代源作品 owner。

4.2 muse_content_chapter

章节表。

字段语义	要求
work_id	所属作品
title / order_no	章节标题和排序
status	draft / writing / completed / archived
goal_snapshot / outline_snapshot	已确认规划摘要或引用
parse_review_status	全书解析章节审阅状态摘要

约束：

• 同一作品内 order_no 唯一。
• 章节解析确认只产生或更新 Knowledge Draft，不写 Local KB Canonical。

4.3 muse_content_block

正文最小编辑单元。

字段语义	要求
work_id / chapter_id	所属作品和章节
order_no	章节内排序
content_doc	富文本结构化内容
revision	乐观锁版本，保存正文必须带 expectedRevision
word_count	当前字数

不变式：

• 正文保存只写正文 Canonical，不自动确认知识草稿。
• AI 候选接受只写目标 Block 和候选 Archive，不自动写 Local KB。

4.4 muse_content_block_revision

Block revision 历史。

字段语义	要求
block_id / revision	Block 与版本
content_snapshot	当前 revision 的正文快照
change_source	manual_save / ai_accept / import_init / merge_after_edit
actor_user_id	操作者
decision_id	若来自候选接受，引用 Candidate Decision Archive

约束：

• (block_id, revision) 唯一。
• 当前正文来源不能只依赖历史候选表，必须可从 revision 追溯。

4.5 muse_content_block_source_attribution

正文来源归因表，绑定到 Block revision。

字段语义	要求
work_id / block_id / revision	归因目标
source_type	ai_candidate / user_text / market_asset / user_kb / global_kb / import
source_object_id / source_version	来源对象和版本
lineage_payload	派生链路摘要
authorization_snapshot_id	授权快照
source_status	SourceStatus：active / stale / revoked / recalled / delisted / blocked / owner_missing / unauthorized
license_restriction_snapshot	导出、二次分发、AI 上下文等限制

约束：

• 来自市场、外部知识、授权知识或 AI 派生内容的正文必须有来源归因。
• 来源状态变为 revoked / recalled / blocked / owner_missing / unauthorized 后，不自动回滚正文，但阻断新生成、新确认、受限导出和新绑定。

4.6 muse_content_planning_item 与 muse_content_narrative_state

作品规划台的正式事实载体。

表	职责
muse_content_planning_item	作品方向、章节大纲、情节节拍、章节目标等已确认规划项
muse_content_narrative_state	work / chapter / entity 维度的叙事运行态

不变式：

• 规划候选未确认前不得进入正式生成上下文。
• Narrative State 需要真实持久化载体，不能只靠 MetaSchema 表达。

4.7 MetaSchema 表（归属 yudao-module-meta 独立模块）

MetaSchema 是独立模块 yudao-module-meta 的元结构定义，由管理后台配置、影响预览、发布、激活和回滚，但它不是管理员私有数据，也不是某个页面表单的临时状态。yudao-module-meta 按 domain / scope / target_type 服务作品、规划、知识和 AI 上下文；Content、Knowledge、AI 等模块通过 facade-api 只读消费。

表	职责
muse_meta_schema	元结构根对象，包含 schema_key、domain、scope、target_type、当前激活版本和适用范围
muse_meta_field	字段定义、类型、必填、枚举、引用、排序、校验规则和 storage_binding 存储映射
muse_meta_visibility_policy	uiVisible、aiContext、userEditable、userSearchable、exportable 等可见性策略
muse_meta_schema_version	发布版本、激活状态、灰度、回滚和影响预览摘要

muse_meta_schema 字段合同：

字段语义	要求
schema_key	稳定业务键，同一 domain / scope / target_type 下唯一
domain	content / world / narrative / knowledge / ai_context
scope	work / chapter / block / entity / relation / event / agent
target_type	目标对象类型，例如 novel_work、character、generation_context
active_version_id	当前激活版本，可为空但不能指向 disabled / archived 版本
effective_scope	适用范围摘要，至少能表达全局、租户、用户、作品、类型灰度
projection_version	当前读模型或运行时缓存使用的投影版本

muse_meta_schema_version 字段合同：

字段语义	要求
schema_id	关联 muse_meta_schema
schema_key	冗余稳定键，便于审计和跨版本查询
version_no	单调递增版本号，同一 schema_key 下唯一
status	draft / reviewing / published / active / disabled / archived / rolled_back
active_flag	当前是否激活；同一 schema_key + effective_scope 只能有一个 active
effective_scope	本版本实际生效范围，发布后不可变
field_contract_snapshot	字段、可见性和校验规则快照
impact_preview_snapshot	发布前影响预览，包含受影响作品数、字段差异、潜在不可逆项
rollback_from_version_id / rollback_to_version_id	回滚链路引用
projection_from_version / projection_to_version	投影升级或降级的版本边界
published_by / published_at	发布人和发布时间
activated_by / activated_at	激活人和激活时间

muse_meta_field 的 storage_binding 存储映射（DDL 随 W1 迁移落地）标注每个字段的物理落点：native_column（映射 Work 等聚合的固定列，如 novel_work 容器 schema 对 muse_content_work 的 title / genre / status 等列）、extension_json（扩展字段落 jsonb）、computed（回算字段，userEditable=false）。它承载容器 schema 对既有固定列的元描述，使 MetaSchema 不复制事实载体（对齐 架构-02 §9）。系统内置 base schema 的种子目标清单（四档：作品与结构身份 / 创作骨架 / 画像技法 / 系统侧）由 专题-06-元数据驱动的智能体架构.md 定义，本册不复制清单。

约束：

• MetaSchema 写入入口只能是 /admin-api/muse/governance/** 经 yudao-module-meta；Content 等模块只能通过 meta facade-api 消费只读投影。
• Content / app API 只能读取 active/gray 投影并在目标 owner 命令中校验，不能创建、发布、激活、回滚或废弃 Schema。
• 管理员配置 MetaSchema 不等于修改用户作品内容、Local KB 或用户知识库资料。
• MetaSchema 不能把系统保护节点重新分类为开放槽位。
• uiVisible=false 不等于不能进 AI 上下文；aiContext=true 不等于用户可见；exportable=true 仍必须受 owner、授权、来源状态和导出许可约束。
• 后端必须在可见投影、保存、检索、AI 上下文组装和导出预检中重复校验 MetaSchema 策略，不能只靠前端隐藏字段。
• 唯一键：muse_meta_schema(domain, scope, target_type, schema_key)；版本唯一键：muse_meta_schema_version(schema_key, version_no)。
• 激活唯一约束：同一 schema_key + effective_scope 仅允许一条 active_flag = true 的版本；物理库不支持部分唯一索引时，由状态机事务和唯一辅助列共同保证。
• 发布前必须写 impact_preview_snapshot；回滚必须保留 from / to 版本，不能覆盖原版本记录。

4.8 导入与导出

表	职责
muse_content_import_task	上传旧稿、解析章节、导入正文初始化任务
muse_content_import_file	导入文件、hash、大小、MIME、扫描状态、存储引用、保留期和清理策略
muse_content_import_chapter_context	导入或现有正文拆分出的章节上下文，供 AI Parse Job 读取
muse_content_export_task	作品正文、设定、规划和作品知识导出任务
muse_content_download_credential	短期下载凭证

muse_content_import_file 字段合同：

字段语义	要求
work_id / import_task_id	所属作品和导入任务
file_id / storage_key	Yudao infra 文件引用；infra 不拥有业务事实
original_filename / mime_type / file_size	上传文件基础摘要
sha256 / content_fingerprint	去重、stale guard 和来源追踪
scan_status	pending / passed / blocked / failed
retention_policy / cleanup_status	保留期和清理状态
source_snapshot_id	上传文件来源快照

muse_content_import_chapter_context 字段合同：

字段语义	要求
work_id / chapter_id	目标作品和章节
import_task_id / import_file_id	来源导入任务和文件；手动解析现有正文时可为空
content_revision / source_hash	解析输入版本和 hash
chapter_order_no / title_snapshot	章节结构摘要
context_status	ready / stale / blocked / deleted
source_snapshot_id / authorization_snapshot_id	解析输入和授权快照

约束：

• Content 不拥有 Parse Job 或 Chapter Parse Result；/parse-jobs 目标 Schema 见 AI / Agent Schema。
• 导入正文可以初始化正文 Canonical；解析出的知识仍必须进入 Knowledge Draft。
• 文件上传必须有 owner、用途、hash、大小、MIME、扫描状态、保留期和清理策略；扫描 blocked 或 failed 的文件不得进入解析、知识资料处理、市场素材或导出。
• 导出创建、完成前和下载时都要重验权限、来源状态和授权快照。

muse_content_download_credential 必须保存签发时的 source_snapshot_id、authorization_snapshot_id、source_event_version、source_action_policy、expires_at、disabled_at 和 disabled_reason。来源 revoked / recalled / blocked / unauthorized 或授权过期时，Source Propagation 必须禁用下载或要求重验，不能只依赖前端隐藏下载按钮。

5. Knowledge Schema

5.1 muse_knowledge_base

知识库根表，统一承载全局知识库、用户知识库和已安装知识库引用。

字段语义	要求
kb_type	global / user / installed_ref
owner_user_id	用户知识库 owner；全局知识库为空或系统 owner
source_market_asset_id	若来自市场安装，引用市场资产
status	draft / active / processing / disabled / deleted
visibility_policy	可见范围摘要
license_snapshot_id	授权或安装来源快照

不变式：

• 全局知识库由管理员治理，授权后才能成为普通用户可见、可检索或可生成来源。
• User KB 由 kb_type = user 表达，owner 是普通用户；用户知识库可维护、绑定和上架市场。
• Local KB 不是独立知识库资产，而是作品内正式知识事实集合，见 muse_knowledge_entity / relation / event。
• 安装知识库不等于绑定作品，也不等于写入 Local KB。

5.2 资料、版本、切块和处理任务

表	职责
muse_knowledge_document	知识库资料条目
muse_knowledge_document_version	资料版本、hash、来源和处理状态
muse_knowledge_chunk	系统拆分切块结果
muse_knowledge_processing_job	解析、切块、索引、入 RAG、重建投影任务

muse_knowledge_document_version 字段合同：

字段语义	要求
document_id	关联 muse_knowledge_document
version_no	同一 document 下单调递增版本号
content_hash	版本内容 hash，用于 stale 检测和去重
source_snapshot_id	来源快照
processing_status	pending / processing / completed / failed
previous_version_id	前版本引用（BIGINT），指向同一 document 的上一个版本记录，首版本为空
change_summary	变更摘要（JSON），记录与前版本的差异概要，包含 addedSections、removedSections、modifiedSections、diffStats 等结构化信息
change_reason	变更原因（VARCHAR(500)），记录本次版本变更的业务原因，例如"修正角色设定冲突"、"补充第三章背景资料"等

约束：

• previous_version_id 必须指向同一 document_id 下已存在的版本记录，或为空（首版本）。
• change_summary 在非首版本时建议必填，由处理任务自动生成或用户手动填写。
• change_reason 在非首版本时建议必填，便于审计和版本回溯。
• 版本差异追踪不替代 chunk 级别的增量重建策略；处理任务可基于 change_summary 优化增量切块和索引。

通用约束：

• 拆分切块和入 RAG 是系统保护节点，不允许用户智能体替换。
• 处理失败的资料不得进入正式检索和生成上下文。
• Chunk 只服务检索和解释，不是正式作品事实。

5.3 Local KB 表

表	职责
muse_knowledge_entity	当前作品正式实体
muse_knowledge_relation	当前作品正式关系
muse_knowledge_event	当前作品正式事件
muse_knowledge_attribute_change	正式知识属性变更日志

Local KB Canonical 必要来源字段：

字段语义	要求
work_id	所属作品
entity_type	实体类型，例如 character / location / item / concept
normalized_name	标准化名称
scope	作用域，例如 global / chapter:{chapterId} / arc:{arcId}，用于区分同名实体在不同范围的含义
source_snapshot_id	最近一次确认或修正所依据的来源快照
authorization_snapshot_id	确认时的授权快照
source_status	active / stale / revoked / recalled / blocked / owner_missing / unauthorized
source_action_policy	allowed / read_only / blocked / needs_recheck（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，表示"下次使用时需要重新校验"，不是 SourceStatus 枚举值。SourceStatus 不含 needs_recheck，来源变化时直接决策 active 或 disabled）
source_event_version	最近已消费的来源事件版本
lineage_payload	派生链路摘要，不保存敏感全文

唯一键：(work_id, entity_type, normalized_name, scope)。

约束：

• Local KB 不需要单独容器表，由 work_id 归属表达。
• 用户确认 Knowledge Draft 或手动知识修正才写 Local KB。
• 正式知识修改必须保留来源、操作者、旧值、新值和风险处理结果。
• 来源事件不删除正式知识，但必须更新 source_status / source_action_policy，阻断新检索、新生成、新确认和受限导出。

5.4 muse_knowledge_draft

知识草稿表，替代旧文档中的 Proposal 产品语义。

字段语义	要求
work_id	目标作品
draft_type	entity / relation / event / attribute / narrative_state
target_object_id	若修改已有正式知识则记录目标
draft_payload	待确认变更
current_canonical_snapshot	生成草稿时的正式事实摘要
source_snapshot_id	来源快照
authorization_snapshot_id	授权快照
risk_marker_snapshot	风险标记摘要
source_status / source_action_policy	草稿当前来源状态和动作策略，不能只靠查询时临时计算
status	pending / confirmed / ignored / stale / invalidated / blocked / needs_reextract

不变式：

• Accept Suggestion 不自动确认 Knowledge Draft。
• 修改后合并正文时，旧 Knowledge Draft 必须失效或进入需重提取状态。
• 确认草稿前必须重验来源状态、授权快照、source hash、目标版本和风险标记。

5.5 muse_knowledge_source_binding

作品绑定的全局、用户或市场知识来源。Source Snapshot、Authorization Snapshot 和来源事件传播由独立 Source / Authorization Schema 承接，本节只保留 Knowledge 侧绑定事实。

字段语义	要求
work_id	目标作品
kb_id	绑定的 Knowledge Base
source_snapshot_id	绑定时的来源快照
authorization_snapshot_id	绑定时的授权快照
binding_scope	read / generation_context / parse_context / export
binding_status	SourceStatus / binding 状态投影：active / stale / revoked / recalled / delisted / blocked / owner_missing / unauthorized / disabled
target_version	绑定目标版本，供来源事件传播和幂等重验

约束：

• Knowledge Source Binding 只表达作品与知识来源的绑定，不把来源资料写入 Local KB。
• 绑定创建、启用和导出前必须读取 Source / Authorization Snapshot；来源状态变化由 Source Propagation 更新 binding_status。
• 绑定失效不自动删除 Local KB Canonical，但阻断新检索、新生成和受限导出。

6. Source / Authorization Schema

Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。它承接跨 Content、Knowledge、AI、Market、Account 的来源快照、授权快照、来源状态事件和传播目标，避免每个业务模块各自保存一份”当前授权通过”的临时布尔值。

物理归属：

• source_snapshot 表 DDL 归 yudao-module-infra 模块（横切基础设施表）。
• 各业务模块（content、knowledge、ai、market、account）分散写入 source_snapshot 记录。
• 传播模式为事件驱动自治：通过 Spring Event 或 MQ 发布来源状态事件，各模块自行监听并处理自己 owner 范围内的传播目标。

6.1 muse_source_snapshot

不可变来源快照。任何会进入正文、Knowledge Draft、Local KB Canonical、AI 上下文、市场资产或导出的来源，都必须能追溯到本表。

字段语义	要求
source_owner_module	来源 owner 模块：content / knowledge / ai / market / account / external
source_type	content_block / block_revision / ai_chapter_parse_result / knowledge_draft / local_kb_entity / local_kb_relation / local_kb_event / user_kb_document / global_kb_document / market_asset_version / ai_candidate / import_file
source_object_id	来源对象 ID
source_version	来源版本，例如 Block revision、资料版本、资产版本或候选版本
source_hash	来源内容 hash，用于 stale 检测
source_status	SourceStatus：active / stale / revoked / recalled / delisted / blocked / owner_missing / unauthorized
owner_user_id / tenant_id	来源 owner 上下文；系统或全局来源可以为空但必须有系统 owner 标记
lineage_payload	派生链路摘要，不保存敏感全文
evidence_payload	权利声明、导入材料、检查摘要或外部引用摘要
created_by / created_at	快照创建人和时间

约束：

• Source Snapshot 创建后不可变；来源内容变化必须创建新快照。
• source_owner_module + source_type + source_object_id + source_version + source_hash 建议唯一。
• source_hash 是确认 Knowledge Draft、接受 AI Candidate、导出和绑定前的 stale guard，不能只存在于接口临时参数。

6.2 muse_authorization_snapshot

不可变授权快照。它记录某次读取、生成、绑定、确认、导出或下载动作在当时为什么被允许或拒绝。

字段语义	要求
source_snapshot_id	授权所针对的来源快照
actor_user_id	发起用户或系统服务身份
authorization_purpose	read / generate / bind / confirm_draft / accept_candidate / export / download / publish / evaluate
authorization_scope	可用范围摘要，至少表达 work / chapter / kb / asset / account 范围
authorization_status	allowed / denied / expired / revoked
expires_at	授权过期时间；长期授权也必须明确策略来源
license_restriction_snapshot	导出、二次分发、AI 上下文、市场发布等限制
policy_version	授权策略版本
decision_reason	允许或拒绝原因摘要
idempotency_key	同一动作重复校验的幂等键

约束：

• Authorization Snapshot 创建后不可变；授权撤销或策略变化必须产生新快照或 Source Status Event。
• 所有高危写入只允许引用 authorization_status = allowed 且未过期的快照。
• 导出创建、完成和下载都要重验授权，不能复用创建任务时的过期快照。

6.3 muse_source_status_event

来源状态事件，由来源 owner、市场治理或授权服务发起，经 outbox 幂等传播。

字段语义	要求
event_key	全局幂等键，建议来自 source_snapshot_id + event_type + event_version
source_snapshot_id	受影响来源快照
event_type	SourceEventType：source_updated / source_revoked / asset_recalled / asset_delisted / asset_blocked / owner_missing / license_changed / authorization_expired / authorization_revoked / processing_failed / recheck_required
source_status_after	本事件应用后的 SourceStatus，不得只用 event type 推断
action_policy_after	SourceActionPolicy：allowed / read_only / blocked / needs_recheck（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，不是 SourceStatus 枚举值）
event_version	同一来源事件版本，单调递增
event_status	pending / propagating / completed / partially_failed / failed
reason_code / reason_message	状态变化原因摘要
reason_attribution_payload	归因到治理动作、授权快照、来源 owner、处理任务或外部回调的摘要
source_owner_module	冗余 owner，便于路由传播 worker
occurred_at / created_at	事件发生和记录时间

约束：

• event_key 唯一，outbox 消费必须幂等。
• 事件创建不直接改业务 Canonical；必须展开为 propagation target，由目标 owner 或 source propagation worker 按目标合同处理。
• API 返回必须同时带 source_status_after、action_policy_after、reason_code 和 reason_attribution_payload；不能把 revoked / recalled / blocked / delisted / unauthorized 压缩成一个无原因的 blocked。

SourceEventType 到状态策略的默认映射：

SourceEventType	SourceStatus	SourceActionPolicy
source_updated	stale	needs_recheck
source_revoked	revoked	blocked
asset_recalled	recalled	blocked
asset_delisted	delisted	read_only
asset_blocked	blocked	blocked
owner_missing	owner_missing	blocked
authorization_expired / authorization_revoked	unauthorized	blocked
license_changed / processing_failed / recheck_required	stale	needs_recheck

6.4 muse_source_propagation_target

来源事件传播目标表，记录每个目标对象是否已应用、阻断、跳过或失败。

字段语义	要求
event_id / event_key	来源状态事件引用和幂等键
target_owner	content / knowledge / ai / market / account / export
target_type	content_block_source_attribution / content_export_task / content_download_credential / knowledge_draft / local_kb_entity / local_kb_relation / local_kb_event / knowledge_source_binding / ai_chapter_parse_result / ai_candidate / ai_context_snapshot / ai_agent_slot_binding / ai_task / market_install / market_authorization / account_asset_summary
target_id	目标对象 ID
target_version	目标对象版本，例如 Block revision、draft version、entity version 或 task version
propagation_status	pending / applied / blocked / needs_recheck / skipped / failed / retrying
target_action_policy	传播后目标对象的 SourceActionPolicy
reason_code / reason_attribution_payload	传播到目标的原因和归因
retry_count / next_retry_at	重试次数和下次重试时间
last_error_code / last_error_message	失败摘要
applied_at	成功应用时间

传播目标必须覆盖：

• Content Block Source Attribution：更新 muse_content_block_source_attribution.source_status，不自动回滚正文。
• Local KB Canonical：覆盖 muse_knowledge_entity / relation / event，阻断新检索、新生成、新确认和受限导出，不自动删除正式事实。
• Knowledge Draft、AI Chapter Parse Result、Knowledge Source Binding、AI Candidate、AI Context Snapshot、Agent Slot Binding、Market Install / Authorization、Export Task、Download Credential 和 Account Asset Summary。

约束：

• event_key + target_owner + target_type + target_id + target_version 建议唯一。
• 传播失败时默认阻断新使用，再暴露治理重试入口。
• 已确认 Canonical 不因来源事件自动回滚，但后续新生成、新确认、新绑定、受限导出和下载凭证必须按传播结果阻断或重验。

7. AI / Agent Schema

7.1 Prompt 和 Agent

表	职责
muse_ai_prompt	Prompt 根对象
muse_ai_prompt_version	Prompt 版本、变量结构、灰度和激活状态
muse_ai_agent	智能体根对象，区分 system / user / market_installed
muse_ai_agent_version	Prompt、模型绑定引用、参数、输出合同、工具授权摘要

约束：

• 系统 Agent 由管理员发布。
• 用户 Agent 可创建、购买、安装和按作品绑定开放槽位。
• Agent 表不保存 New-API token、Dify API Key、RAGFlow token 明文、完整供应商响应或成本账本 authority。
• muse_ai_agent_version.config 承载受控 JSON，不是自由扩展垃圾桶。系统 Agent 新版本必须显式包含 runtimeProvider，取值为 new-api / dify / 预留 agentscope；历史 active version 缺失时仅运行时兼容为 new-api。
• runtimeProvider=dify 时，config.providerRef.dify 至少包含 appType、credentialRef 和后端可校验的 app/workflow 引用：appType=agent 必填 appId，appType=workflow 必填 workflowId。credentialRef 是安全配置引用名，不是密钥，禁止为空值默认。
• Dify consoleUrl 不作为前端可写事实入库；后端只能按 Dify baseUrl allowlist 和 app/workflow id 拼装并脱敏返回。
• config.outputContract 应记录输出目标、结构化要求和来源追溯策略。允许 Dify 内部知识参与的版本必须能标记 untraceable_provider_context；要求 Muse source refs 的链路不能接受不可追溯 provider 输出。
• provider 运行状态、providerRequestId、commandId、correlationId、用量归属状态和脱敏失败摘要必须落在 runtime call / job / audit 事实中；Dify usage 摘要不能替代 New-API 成本账本或账户扣费 authority。

7.2 系统功能链路和槽位

功能链定义（chain / version / node / slot）与 MetaSchema 同住 yudao-module-meta（案 A，见 架构-03 ADR-022），逻辑写入 authority 为 Governance facade、经 meta admin service；AI runtime 经 FunctionChainQueryApi 只读激活链做运行编排。muse_ai_protected_node_registry（保护节点注册表实例）与 muse_ai_agent_slot_binding（运行时槽位绑定）仍归 AI。

表	职责
muse_meta_function_chain	生成、分析、检测、导入解析、知识处理等系统预编排链路
muse_meta_function_chain_version	功能链路版本，记录 chain definition、激活状态、回滚来源和兼容范围
muse_meta_function_chain_node	链路节点，标记 protected / open_slot / internal
muse_ai_protected_node_registry	不可替换保护节点注册表
muse_meta_function_chain_slot	可替换子智能体槽位定义
muse_ai_agent_slot_binding	作品级槽位绑定，记录用户选择的 Agent Version

muse_meta_function_chain_version 字段合同：

字段语义	要求
chain_id	关联功能链路根对象
version_no	同一 chain 下单调递增，唯一
status	draft / published / active / disabled / rolled_back
active_flag	当前激活版本标记，同一 chain + effective_scope 仅一条 active
effective_scope	全局、租户、用户组、作品类型或灰度范围
chain_definition_snapshot	节点顺序、输入输出合同、保护节点和开放槽位快照
rollback_from_version_id / rollback_to_version_id	回滚链路

muse_ai_protected_node_registry 字段合同：

字段语义	要求
node_key	稳定节点键
node_type	见下方保护节点枚举
replacement_policy	固定为 system_only 或 admin_only，不能为 user replaceable
input_contract / output_contract	输入输出结构、敏感字段和失败输出合同
permission_requirement	需要的权限过滤、owner 校验和授权快照
audit_requirement	是否必须写 muse_audit_event、保留哪些摘要
quality_policy_version_id	需要质量门控时关联质量策略版本
status	active / disabled / deprecated

保护节点枚举至少包括：

node_type	含义
input_compliance	输入合规
permission_filter	权限过滤
audit	审计写入
split_chunk	拆分切块
rag_ingest	入 RAG
semantic_guardrail	语义围栏
static_check	静态检查
quality_gate	质量门控
source_status_check	来源状态校验
shadow_to_canonical	Shadow -> Canonical 规则
output_compliance	输出合规

约束：

• 用户不能把保护节点重分类为开放槽位。
• 槽位绑定必须保存 agentVersion、authorizationSnapshot、toolGrantSet、回退策略和绑定来源。
• 授权撤销、版本下架或输出不合约时，按状态机回退默认或阻断。
• muse_ai_agent_slot_binding 唯一性是“同一 work_id + slot_key 仅允许一条 active 记录”；inactive 历史允许多条，不能用 work_id + slot_key 全量唯一键。

7.3 Tool Grant 与运行权限包

表	职责
muse_ai_tool_grant	工具、动作、目的、输入来源、输出位置、副作用、外发目标和预算授权的版本化投影
muse_ai_runtime_permission_envelope	某次试用、生成、解析、检测或质量评测的服务端权限包

muse_ai_tool_grant 字段合同：

字段语义	要求
grant_key / version_no	稳定授权键和版本
authority_owner	固定为 governance / security / admin_review 等授权 authority，不允许 ai_runtime 自签
tool_key / action / purpose	工具、动作和用途
input_source_policy	允许读取的来源类型、owner 和授权快照要求
output_target_policy	允许写入的目标 owner、Shadow / Canonical 边界和副作用
egress_policy	外发域名、协议、数据级别和禁止项
budget_policy	token、调用次数、金额或时间预算
approval_status / approved_by	审批状态和审批人
audit_requirement	必须写入的审计摘要

运行权限包必须固化：

• actor。
• work / chapter / block。
• slot。
• agentVersion。
• toolGrantSet。
• allowedContextScopes。
• egressPolicy。
• budget。
• authorizationSnapshot。
• sourceSnapshot。
• auditRequirement。

前端、Prompt、模型输出和智能体自述权限无效。AI runtime 只能基于已发布 Tool Grant、actor 权限、来源状态、授权快照、账户权益和目标 owner 校验生成权限包；运行中不得追加工具、扩大上下文、变更外发目标或绕过审计。

7.4 任务、解析、候选和质量结果

表	职责
muse_ai_task	生成、续写、扩写、润色、解析、检测、质量评估等异步任务
muse_ai_parse_job	全书或章节解析任务、解析配置快照、状态、幂等键和重试信息
muse_ai_chapter_parse_result	章节解析 Shadow 结果、审阅状态、质量结果、来源和授权快照
muse_ai_context_snapshot	上下文组装摘要、来源、授权和省略原因
muse_ai_candidate	可展示或待决策的 AI 候选 / Shadow Candidate
muse_ai_candidate_quality_result	质量门控评分、关键维度、非关键维度、重写结果和风险
muse_ai_candidate_decision_archive	接受、修改后合并、丢弃、过期或失效的决策归档
muse_ai_quality_policy	质量策略根对象，定义适用任务、门控维度和治理目标
muse_ai_quality_policy_version	质量策略版本，记录阈值、权重、重写策略、激活状态和回滚链路
muse_ai_evaluation_dataset	评测数据集，绑定来源、授权、样本版本和适用范围
muse_ai_evaluation_run	评测运行记录，绑定 agent / chain / policy / dataset 版本
muse_ai_evaluation_result	单样本或聚合评测结果，记录评分、失败维度和治理建议

muse_ai_parse_job 字段合同：

字段语义	要求
work_id / chapter_id	解析目标；全书解析时 chapter_id 可为空，章节解析必须有值
content_context_id	Content 提供的导入文件或章节上下文引用
trigger_type	import / manual_parse / reparse_after_edit / scheduled_rebuild
idempotency_key	/parse-jobs 创建任务的幂等键，同一 actor 和目标范围内唯一
source_revision / source_hash	解析输入的正文 revision 或导入文件 hash
agent_version_id / tool_grant_version / runtime_envelope_id	解析使用的 AI 配置和权限快照
status	queued / parsing / retrying / reviewing / parsed / failed / canceled
retry_count / next_retry_at	失败重试控制
error_code / error_message	失败摘要，不保存敏感全文

muse_ai_chapter_parse_result 字段合同：

字段语义	要求
parse_job_id	关联 muse_ai_parse_job
work_id / chapter_id	冗余目标，便于章节级查询和权限校验
result_type	entity_draft / relation_draft / event_draft / narrative_state_draft / chapter_summary
result_payload	Shadow 结果内容，只能在章节审阅后请求 Knowledge 生成或刷新 Knowledge Draft
target_draft_id	已生成或刷新的 Knowledge Draft 引用；未审阅前为空
review_status	pending / reviewed / ignored / stale / blocked / needs_reextract
quality_result_id	解析质量和静态检查结果
source_snapshot_id / authorization_snapshot_id	解析输入和授权快照
source_status / source_action_policy	当前来源状态和动作策略

质量策略与评测字段合同：

表	必要字段
muse_ai_quality_policy_version	policy_id、version_no、status、active_flag、effective_scope、metric_contract_snapshot、threshold_snapshot、rewrite_policy_snapshot、rollback_from_version_id、rollback_to_version_id
muse_ai_evaluation_dataset	dataset_key、dataset_version、source_snapshot_id、authorization_snapshot_id、sample_count、status、effective_scope
muse_ai_evaluation_run	run_key、dataset_id、dataset_version、agent_version_id、chain_version_id、quality_policy_version_id、status、started_at、finished_at、idempotency_key
muse_ai_evaluation_result	run_id、sample_id、result_status、score_payload、failed_dimension、quality_gate_status、risk_marker_snapshot、source_status

约束：

• AI Task 成功不能直接写 Canonical。
• Parse Job / Chapter Parse Result 属于 AI Shadow；章节审阅确认只请求 Knowledge 生成 Knowledge Draft，不直接写 Local KB Canonical。
• Candidate 进入可接受状态前必须通过静态检查、来源状态校验、质量门控和输出合规。
• Candidate Decision Archive 只证明用户对候选的处理，不证明知识草稿已确认。
• 质量门控可以在 Shadow 内有限重写候选，但不能替用户确认正文或知识。

muse_ai_candidate_decision_archive 必须由 AI decision archive service 单一写入，字段至少包含 candidate_id、decision_type、quality_result_version、output_compliance_result_id、static_check_result_id、source_snapshot_id、source_version、authorization_snapshot_id、source_status、market_feature_gate、work_asset_use_precheck_id、expected_revision、idempotency_key、blocked_reason_payload 和 audit_event_id。候选记录 source_version，接受时实时对比当前来源版本。Content Accept 成功后只保存 decision_id 引用；失败时不得创建可误认为已接受的归档。

8. Marketplace Schema

8.1 市场资产

表	职责
muse_market_asset	市场对象统一根，类型为 work / agent / knowledge_base
muse_market_asset_version	上架资产版本快照，引用源作品、源智能体或源知识库版本
muse_market_listing	展示状态、审核状态、价格/授权摘要、分类和推荐摘要
muse_market_license	可见、可用、可复制、可商用、可导出、可绑定、可再发布等规则

不变式：

• 市场资产记录不替代源对象 owner。
• 上架不转移所有权。
• 作品资产当前 feature gate 关闭：只允许阅读、收藏和授权记录，不允许模板化、参考写入或进入 AI 上下文。

8.2 购买、授权、安装和绑定

表	职责
muse_market_authorization	用户获得许可的记录，可来自购买、免费获取或管理员授权
muse_market_purchase_ref	支付订单或外部交易引用，不保存支付清结算事实
muse_market_install	智能体或知识库安装到账户可用资产
muse_market_bind_precheck	绑定或使用前的来源侧许可、版本、治理和授权摘要
muse_market_handoff_session	市场到作品、智能体或知识库工作台的一次性来源侧 handoff 会话
muse_market_collection	用户收藏市场资产，支持作品资产 feature gate 关闭时的阅读和收藏链路

muse_market_collection 字段合同：

字段语义	要求
user_id	收藏用户
asset_id / asset_version_id	收藏的市场资产和当时版本
collection_source	listing / detail / handoff / recommendation
status	active / canceled
idempotency_key	重复收藏或取消收藏的幂等键

muse_market_bind_precheck / muse_market_handoff_session 字段合同：

字段语义	要求
asset_id / asset_version_id	来源市场资产和版本
actor_user_id	发起人
target_owner_hint / target_entry	目标 owner 提示和跳转入口，只作路由，不是目标事实
authorization_snapshot_id / source_snapshot_id	市场侧授权和来源快照
license_summary / governance_summary	来源侧许可、治理和版本摘要
handoff_token_hash	短期 token hash，不保存明文
expires_at / consumed_at / canceled_at	生命周期
jump_audit_id	跳转审计引用

约束：

• 购买不等于安装。
• 安装不等于关联作品。
• 收藏不等于购买、授权或安装；收藏不写作品正文、规划正式项、Local KB 或 Agent Slot Binding。
• 安装、绑定和 handoff 只授予账户可用性、来源侧授权摘要或短期跳转上下文，不写作品正文、规划正式项或 Local KB。
• Market 不保存目标 owner 预检事实；目标 owner 必须自己校验权限、状态、版本、许可、来源和目标对象，并生成 muse_ai_agent_slot_precheck、muse_knowledge_bind_precheck、muse_content_work_asset_use_precheck 或签名消费凭证。
• handoff token 只能短期有效、原子消费一次，不能绕过目标空间确认；Market 消费记录只说明跳转 token 被使用，不证明目标绑定或写入成功。

8.3 发布、审核和治理

表	职责
muse_market_publish_draft	发布者准备中的发布草稿
muse_market_publish_check_snapshot	发布检查快照，绑定资产版本、材料 hash、权利声明和安全检查
muse_market_review_submission	发布审核提交记录
muse_market_governance_action	下架、召回、恢复、部分恢复、终裁等治理动作
muse_market_appeal	申诉记录

约束：

• 发布提交必须消费未过期且匹配当前草稿的检查快照。
• 下架、召回、blocked 必须产生 Source Status Event。
• 管理员拥有系统级治理能力，但不替用户修改已购买或私有资产内容。

9. Account Schema（物理承载：yudao-module-member）

已决策：Account BC 由 yudao-module-member 承载，不新增 yudao-module-account。表前缀统一使用 muse_member_，与 member 模块对齐。

表	职责
muse_member_profile_ext	Muse 展示名、创作偏好入口等扩展资料
muse_member_preference	用户偏好、通知偏好、创作辅助偏好
muse_member_new_api_binding	Muse 用户和 New-API 网关用户绑定摘要
muse_member_entitlement_snapshot	套餐、配额、余额或外部网关权益的本地快照
muse_member_entitlement	用户当前权益可变表，直接更新当前状态；所有变更写入 muse_member_entitlement_audit_log 审计日志
muse_member_entitlement_audit_log	权益变更审计日志，记录每次变更的操作者、原因、前后值和来源，用于追溯和合规
muse_member_quota_request	向 New-API 或本地权益服务发起的额度配置/同步请求
muse_member_quota_adjustment	管理员调额请求记录，支持幂等、原因、前后值和审计
muse_member_usage_record	生成、检索、评估、导出等任务级用量归属摘要
muse_member_call_attribution_job	New-API 调用归属、补偿和用户可见解释任务
muse_member_asset_summary	个人中心资产摘要读模型
muse_member_security_event	登录、敏感导出、凭证失效、异常访问等安全事件摘要
muse_member_export_task	个人资料、安全事件或账户记录导出任务

New-API 绑定、额度和调用归属最小字段：

表	必要字段
muse_member_new_api_binding	account_user_id、gateway_user_ref、binding_status、last_recheck_at、correlation_id、idempotency_key、failure_code
muse_member_quota_request	account_user_id、request_type、requested_value_snapshot、correlation_id、idempotency_key、request_status、retry_group、failure_code
muse_member_call_attribution_job	account_user_id、ai_task_id、gateway_request_id、correlation_id、source_owner、source_id、attribution_status、retry_group、compensation_status、failure_code

muse_member_quota_adjustment 字段合同：

字段语义	要求
account_user_id	被调整账户
adjustment_type	quota_increase / quota_decrease / entitlement_grant / entitlement_revoke / balance_correct
idempotency_key	管理员调额幂等键，同一管理员动作唯一
reason_code / reason_message	调整原因，必须可审计
before_value_snapshot / after_value_snapshot	调整前后权益或配额摘要
ledger_entry_id	调整落账后的审计日志引用
status	pending / applied / rejected / canceled
approved_by / applied_by	审批人和执行人
audit_event_id	高危动作审计引用

muse_member_entitlement_audit_log 字段合同：

字段语义	要求
account_user_id	账户 owner
change_type	purchase / admin_adjustment / usage_debit / refund / expiration / revoke / sync_correction
source_owner / source_id	来源 owner 和来源记录，例如支付订单、调额记录或外部同步记录
idempotency_key	变更幂等键
before_value_snapshot / delta_value_snapshot / after_value_snapshot	前值、变更值和后值
reason_code / reason_message	业务原因
operator_user_id	操作者（系统、管理员或用户自身）
audit_event_id	审计事件引用

Entitlement 存储模式说明：

• muse_member_entitlement 是可变表，直接反映用户当前权益状态（套餐、配额、余额等），支持高效查询和前置检查。
• muse_member_entitlement_audit_log 是审计日志表，记录每次权益变更的完整上下文，用于追溯、合规和争议处理。
• 不采用 append-only ledger 模式；错误调整通过反向变更 + 审计日志记录，直接更新可变表状态。

约束：

• muse_member_usage_record 不是 New-API 成本账本 authority。
• muse_member_entitlement 是可变表，muse_member_entitlement_audit_log 记录所有变更历史；muse_member_quota_adjustment 记录管理员调额请求。
• 管理员调额必须写幂等键、原因、前后值、操作者和审计事件。
• Pay callback、refund、套餐撤销和市场补偿必须按 source_owner + source_id + idempotency_key 写入审计日志并更新可变表；重复回调返回同一处理结果。
• New-API binding、quota request 和 call attribution 只保存 Muse 任务、用户权益和失败恢复需要的引用、correlationId、幂等键和状态，不保存 Provider、供应商路由、成本账本或原始调用日志 authority。
• 个人中心是 read model 和跳转入口，不反写作品、知识、市场资产或 AI 任务事实。
• 账户导出只能导出个人中心 owner 范围内的数据，并记录下载审计；muse_member_export_task 是 API 必须承接的 Schema 落点，接口层应提供创建、轮询、取消和下载凭证领取。

10. Audit、Outbox 与 Integration

表	职责
muse_audit_event	高危业务动作 append-only 审计
muse_outbox_event	跨模块领域事件、来源传播事件和投影事件
muse_projection_task	RAG / 检索 / 报表 / 读模型投影任务
muse_integration_call_log	Muse 调用 New-API、文件、检索、通知等外部接口的轻量日志

Owner 约束：

• 业务审计由动作 owner 写入。例如 Accept 由 content/ai 协作写审计，知识确认由 knowledge 写审计，市场治理由 market 写审计。
• Outbox 由产生事实变化的 owner 写入，消费端只能投影、通知或传播状态，不能反向写 Canonical。
• Integration Call Log 由调用外部服务的模块写入；Yudao infra API 日志仍保留为技术日志，不替代业务审计。

约束：

• 普通接口调用日志优先复用 Yudao infra；高危业务动作必须进入 Muse append-only 审计。
• Integration Call Log 记录 correlationId、idempotencyKey、重试组、外部对象引用和摘要，不保存敏感全文。
• Outbox 事件必须幂等消费，失败可重试，不能让外部投影反向写 Canonical。

11. 关键约束矩阵

约束	数据结构落点
用户接受候选不自动确认知识草稿	muse_ai_candidate_decision_archive 与 muse_knowledge_draft 分表、分状态
修改后合并导致旧知识草稿失效	Candidate Decision Archive 记录 merge_after_edit，Knowledge Draft 进入 invalidated 或 needs_reextract
/parse-jobs 不直接写 Local KB	muse_ai_parse_job 记录任务，muse_ai_chapter_parse_result 记录 Shadow 结果，只在章节审阅后请求 Knowledge 生成或更新 muse_knowledge_draft
章节解析确认不写 Local KB	AI Chapter Parse Result 进入已审阅状态，只产生或更新 muse_knowledge_draft
来源撤权不自动回滚正式正文	muse_content_block_source_attribution 保留状态，Source Propagation 阻断新使用
来源撤权必须覆盖 Local KB Canonical	muse_source_propagation_target 覆盖 muse_knowledge_entity / relation / event，阻断新检索、新生成、新确认和受限导出
市场购买、授权、安装和绑定不写作品事实	muse_market_authorization / install / bind_precheck / handoff 与 Content / Knowledge Canonical 分离
Market 不写目标预检事实	muse_market_bind_precheck 只保存来源侧摘要；目标凭证分别落 muse_ai_agent_slot_precheck、muse_knowledge_bind_precheck、muse_content_work_asset_use_precheck 或目标 owner 签名凭证
市场收藏不代表授权或安装	muse_market_collection 只保存用户市场行为
用户只替换开放槽位	muse_meta_function_chain_slot / muse_ai_agent_slot_binding，保护节点在 muse_ai_protected_node_registry
AI 不能自授工具或外发权限	muse_ai_tool_grant.authority_owner 必须来自 Governance / Security facade，运行时只消费 muse_ai_runtime_permission_envelope
入 RAG 不反写事实	muse_knowledge_processing_job / muse_projection_task 只产投影和索引
导出必须重验来源许可	Export Task + Download Credential + Authorization Snapshot
管理员不替用户确认私有事实	Admin 接口只写配置、治理和审计；Content/Knowledge 决策命令必须校验 owner 用户
管理员调额必须可追溯	muse_member_quota_adjustment + muse_member_entitlement_audit_log，保留幂等键、原因、前后值和审计

12. 索引策略

12.1 热路径索引

必须优先覆盖：

• 我的作品：owner_user_id + update_time。
• 章节列表：work_id + order_no。
• Block 列表：chapter_id + order_no。
• 解析任务：work_id + status + update_time、idempotency_key。
• 解析结果：parse_job_id + chapter_id + review_status。
• 当前候选：work_id + status + create_time。
• 知识草稿：work_id + status + update_time。
• Local KB 检索：work_id + entity_type + normalized_name + scope。
• 用户知识库：owner_user_id + status + update_time。
• 来源传播：event_key、target_owner + target_type + target_id + propagation_status。
• 市场资产：asset_type + listing_status + category + update_time。
• 市场收藏：user_id + status + update_time、user_id + asset_id。
• 授权/安装：user_id + asset_type + status。
• 任务轮询：actor_user_id + task_type + status + update_time。
• 账户权益审计日志：account_user_id + create_time、idempotency_key。

12.2 唯一性

建议唯一键：

• muse_content_chapter(work_id, order_no)。
• muse_content_block(chapter_id, order_no)。
• muse_content_block_revision(block_id, revision)。
• muse_ai_parse_job(idempotency_key)。
• muse_ai_chapter_parse_result(parse_job_id, chapter_id, result_type)。
• muse_meta_schema(domain, scope, target_type, schema_key)。
• muse_meta_schema_version(schema_key, version_no)。
• muse_knowledge_entity(work_id, entity_type, normalized_name, scope)。
• muse_source_snapshot(source_owner_module, source_type, source_object_id, source_version, source_hash)。
• muse_source_status_event(event_key)。
• muse_source_propagation_target(event_key, target_owner, target_type, target_id, target_version)。
• muse_meta_function_chain_version(chain_id, version_no)。
• muse_ai_quality_policy_version(policy_id, version_no)。
• muse_ai_agent_slot_binding(work_id, slot_key) 仅约束 active_flag = true 的 active 记录；inactive 历史允许多条。
• muse_ai_agent_slot_precheck(precheck_id)。
• muse_knowledge_bind_precheck(precheck_id)。
• muse_content_work_asset_use_precheck(precheck_id)。
• muse_market_install(user_id, asset_id, asset_version_id)。
• muse_market_collection(user_id, asset_id) 仅约束 status = active 的收藏记录。
• muse_market_bind_precheck(precheck_id)。
• muse_member_new_api_binding(account_user_id)。
• muse_member_quota_request(idempotency_key)。
• muse_member_call_attribution_job(correlation_id, gateway_request_id)。
• muse_member_quota_adjustment(idempotency_key)。
• muse_member_entitlement_audit_log(idempotency_key)。
• muse_outbox_event(event_key)。

激活唯一约束：

• MetaSchema：同一 schema_key + effective_scope 仅一条 active_flag = true 的 muse_meta_schema_version。
• Function Chain：同一 chain_id + effective_scope 仅一条 active_flag = true 的 muse_meta_function_chain_version。
• Quality Policy：同一 policy_id + effective_scope 仅一条 active_flag = true 的 muse_ai_quality_policy_version。

12.3 JSON 查询

结构化 JSON 字段默认不作为复杂查询主路径。凡是进入筛选、排序、权限、状态机或审计的字段，必须提取成显式列或读模型字段。

12.4 Archive 存储策略

候选归档（Candidate Decision Archive）、知识草稿归档和任务归档采用同表 + status 模式：

• 归档记录与活跃记录存储在同一张表中，通过 status 字段区分（例如 active / archived / expired / invalidated）。
• 不单独创建 archive 表或分区表。
• 热路径查询通过 status 索引过滤归档记录，保证活跃数据查询性能。
• 归档记录保留完整上下文（来源快照、授权快照、质量结果、决策类型），用于审计和追溯。
• 数据量增长后可通过数据库分区（按时间或状态）优化，但逻辑上仍是同一张表。

12.5 API 版本策略

API 版本通过 HTTP Header 传递，路由路径不变：

• Header：X-API-Version: 1（当前版本为 1）。
• 服务端根据 header 值返回对应版本的响应结构。
• 未传 header 时默认使用最新稳定版本。
• Deprecation Policy：旧版本至少保留 6 个月，期间返回 Deprecation 响应头提示迁移；到期后返回 API_VERSION_DEPRECATED 错误码。
• 版本变更只影响响应结构和字段语义，不影响路由路径和认证方式。

13. 迁移与 SQL 文件口径

13.1 迁移策略

阶段 7 的迁移策略：

1. 先确认本文件的模块 owner 和表清单。
2. 再按 Yudao 模块生成对应 migration / SQL。
3. 每个模块只创建自己 owner 的表。
4. 不把旧 services/muse-engine Flyway V1-V18 直接搬进 yudao-cloud。
5. 不把旧 PostgreSQL jsonb、UUID/BIGSERIAL、S0-ID 字符串主键作为当前工程基线。

13.2 后端-04a 的处理

后端-04a-完整建表SQL.sql 当前不再是目标建表 SQL。它只能作为旧实现快照和迁移对照，不允许直接执行到 yudao-cloud 目标库。

目标 SQL 必须等以下事项确认后重新生成：

1. account 模块选择：已决策，使用 yudao-module-member 承载。
2. 目标数据库类型和 Yudao migration 方式。
3. 是否启用 Yudao 多租户字段。
4. 物理外键策略。
5. JSON 字段的物理类型和 TypeHandler。

14. 非目标

• 不重写 Yudao system、infra、pay、bpm、member、report、mp 的原生 Schema。
• 不在 Muse 本地复制 New-API 模型路由、成本账本和调用日志 authority。
• 不把市场资产获取、安装或绑定设计成自动写入作品事实。
• 不把知识库绑定设计成自动写入 Local KB。
• 不把智能体配置设计成可替换保护节点。
• 不把旧 Proposal 语义恢复为产品主词；产品和接口层统一使用 Knowledge Draft。
• 不在本阶段伪造一份未经目标数据库和 Yudao migration 策略确认的完整可执行 SQL。

15. 关联阅读

• 工程结构与模块职责：后端-02-工程结构与模块职责.md
• 领域模型与聚合设计：后端-01-领域模型与聚合设计.md
• 关键流程实现与接口契约：后端-03-关键流程实现与接口契约.md
• API 契约：后端-05-统一API契约-v1.md
• 核心数据结构与双轨模型：架构-02-核心数据结构与双轨模型.md
• 状态机与约束清单：架构-04-状态机与约束清单.md