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

- 版本：v8
- 更新日期：2026-05-23
- 目标读者：后端 / 架构 / 前端 / 数据库维护者 / 测试
- 阅读时间：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`。

## 1. 目标

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

本文件只固化以下事情：

1. 哪些数据事实复用 Yudao 原生模块，哪些由 Muse 新业务模块持有。
2. Muse 新增表按 `content`、`knowledge`、`ai`、`market`、`account` 等领域 owner 拆分。
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_account_` | `muse_account_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、MetaSchema、导入、导出和下载凭证。
- `knowledge` 拥有 User KB、Local KB、Knowledge Draft 和知识来源绑定。
- `ai` 拥有 Prompt、Agent、Protected Node Registry、Override Slot、Tool Grant、Runtime Permission Envelope、AI Task、Candidate、Quality Result 和 Candidate Decision Archive。
- `market` 拥有 Market Asset、License、Authorization、Install、Bind Precheck、Handoff、Publish、Review、Governance 和 Appeal。
- `account` 拥有 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、MetaSchema、Import、Parse、Export |
| 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、Candidate、Quality Policy、Evaluation |
| Marketplace | `yudao-module-market` | Asset、Listing、License、Purchase/Authorization、Install、Collection、Publish、Review、Governance、Appeal、Handoff |
| Account | `yudao-module-account` 或 `member` 二开 | Profile Extension、Preference、Entitlement Snapshot、Entitlement Ledger、Quota Adjustment、Usage Record、Asset Summary、Security Event、Account Export |
| Source / Authorization | 来源对象 owner + outbox 协作 | 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_meta_schema` | content | admin content service | ai / knowledge / market / account | 激活、停用、回滚写 outbox，供投影和运行时缓存刷新 |
| `muse_content_meta_field` | content | admin content service | ai / knowledge | 随 MetaSchema 版本发布传播 |
| `muse_content_meta_visibility_policy` | content | admin content service | ai / knowledge / account | 随 MetaSchema 版本发布传播 |
| `muse_content_meta_schema_version` | content | admin content service | ai / knowledge / market / account | 发布、激活、回滚和影响预览写 outbox |
| `muse_content_import_task` | content | content | knowledge / ai | 导入完成触发 parse task 或正文初始化事件 |
| `muse_content_parse_task` | content | content | knowledge / ai | `/parse-tasks` 创建、重试、取消和完成写 outbox |
| `muse_content_parse_result` | content | content | knowledge / ai | 章节解析结果通过事件生成或刷新 Knowledge Draft |
| `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_source_snapshot` | source/authorization | 来源 owner 或 source facade | 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_ai_system_function_chain` | ai | ai admin service | content / knowledge | 链路激活、停用写 outbox |
| `muse_ai_system_function_chain_version` | ai | ai admin service | content / knowledge | function chain 版本激活写 outbox |
| `muse_ai_chain_node` | ai | ai admin service | content / knowledge | 节点配置随 chain version 发布 |
| `muse_ai_protected_node_registry` | ai | ai admin service | content / knowledge / audit | 保护节点变更写审计和 outbox |
| `muse_ai_override_slot` | ai | ai admin service | content / market | 槽位变更触发 slot binding 重验 |
| `muse_ai_agent_slot_binding` | ai | content + ai binding service | market / account / source | 仅 active 绑定唯一；授权撤销或版本下架触发失效 |
| `muse_ai_tool_grant` | ai | ai | content / account / audit | 工具授权变更写审计 |
| `muse_ai_runtime_permission_envelope` | ai | ai runtime | content / knowledge / audit | 每次运行固化权限包并写审计引用 |
| `muse_ai_task` | ai | ai runtime | content / knowledge / account | 任务状态变化写 outbox 和 usage 摘要 |
| `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 | content decision service + ai | knowledge / audit | 用户决策归档写 outbox，不确认 Knowledge Draft |
| `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 + target owner precheck | content / ai / knowledge / source | 预检结果短期有效，过期不传播 Canonical |
| `muse_market_handoff_session` | market | market | content / ai / knowledge / account | handoff 原子消费写审计 |
| `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_account_profile_ext` | account | account | market / content | 个人资料变化写账户读模型事件 |
| `muse_account_preference` | account | account | content / ai | 偏好变化刷新运行时默认值 |
| `muse_account_entitlement_snapshot` | account | account entitlement service | ai / market | 权益快照变化写 outbox |
| `muse_account_entitlement_ledger` | account | account entitlement service | ai / market / audit | append-only 权益流水写审计 |
| `muse_account_quota_adjustment` | account | admin account service | ai / audit | 管理员调额 append-only，按幂等键去重 |
| `muse_account_usage_record` | account | account usage service | ai / content / knowledge / market | usage 摘要写个人中心读模型 |
| `muse_account_asset_summary` | account | account projection worker | market / ai / knowledge | 只做读模型投影 |
| `muse_account_security_event` | account | account / audit | content / market | 安全事件 append-only |
| `muse_account_export_task` | account | account | 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` | `active` / `stale` / `revoked` / `recalled` / `blocked` / `owner_missing` / `needs_recheck` |
| `license_restriction_snapshot` | 导出、二次分发、AI 上下文等限制 |

约束：

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

### 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 表

MetaSchema 是管理员治理的元结构定义，由管理后台配置和发布，但它不是管理员私有数据，也不是某个页面表单的临时状态。阶段 7 默认由 `yudao-module-content` 承载基础表，按 `domain / scope / target_type` 服务作品、规划、知识和 AI 上下文。

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

`muse_content_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_entity`、`generation_context` |
| `active_version_id` | 当前激活版本，可为空但不能指向 disabled / archived 版本 |
| `effective_scope` | 适用范围摘要，至少能表达全局、租户、用户、作品、类型灰度 |
| `projection_version` | 当前读模型或运行时缓存使用的投影版本 |

`muse_content_meta_schema_version` 字段合同：

| 字段语义 | 要求 |
|---|---|
| `schema_id` | 关联 `muse_content_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` | 激活人和激活时间 |

约束：

- 管理员配置 MetaSchema 不等于修改用户作品内容、Local KB 或用户知识库资料。
- MetaSchema 不能把系统保护节点重新分类为开放槽位。
- `uiVisible=false` 不等于不能进 AI 上下文；`aiContext=true` 不等于用户可见；`exportable=true` 仍必须受 owner、授权、来源状态和导出许可约束。
- 后端必须在可见投影、保存、检索、AI 上下文组装和导出预检中重复校验 MetaSchema 策略，不能只靠前端隐藏字段。
- 唯一键：`muse_content_meta_schema(domain, scope, target_type, schema_key)`；版本唯一键：`muse_content_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_parse_task` | `/parse-tasks` 的 Schema 落点，记录全书或章节解析任务、状态、幂等键和重试信息 |
| `muse_content_parse_result` | 全书解析章节结果，属于 Shadow 对象 |
| `muse_content_export_task` | 作品正文、设定、规划和作品知识导出任务 |
| `muse_content_download_credential` | 短期下载凭证 |

`muse_content_parse_task` 字段合同：

| 字段语义 | 要求 |
|---|---|
| `work_id` / `chapter_id` | 解析目标；全书解析时 `chapter_id` 可为空，章节解析必须有值 |
| `trigger_type` | `import` / `manual_parse` / `reparse_after_edit` / `scheduled_rebuild` |
| `idempotency_key` | `/parse-tasks` 创建任务的幂等键，同一 owner 和目标范围内唯一 |
| `source_revision` / `source_hash` | 解析输入的正文 revision 或导入文件 hash |
| `status` | `queued` / `parsing` / `retrying` / `reviewing` / `parsed` / `failed` / `canceled` |
| `retry_count` / `next_retry_at` | 失败重试控制 |
| `parse_result_id` | 最近一次主结果引用，便于轮询 |
| `index_status` / `index_version` | 解析结果进入检索或读模型索引的状态和版本 |
| `error_code` / `error_message` | 失败摘要，不保存敏感全文 |

`muse_content_parse_result` 字段合同：

| 字段语义 | 要求 |
|---|---|
| `parse_task_id` | 关联 `muse_content_parse_task` |
| `work_id` / `chapter_id` | 冗余目标，便于章节级查询和权限校验 |
| `result_type` | `entity_draft` / `relation_draft` / `event_draft` / `narrative_state_draft` / `chapter_summary` |
| `result_payload` | Shadow 结果内容，只能生成或刷新 Knowledge Draft |
| `target_draft_id` | 已生成或刷新的 Knowledge Draft 引用 |
| `review_status` | `pending` / `reviewed` / `ignored` / `stale` / `needs_reextract` |
| `source_snapshot_id` / `authorization_snapshot_id` | 解析输入和授权快照 |

约束：

- `/parse-tasks` API 只能创建、查询、取消或重试 `muse_content_parse_task`，不能直接写 Local KB Canonical。
- 导入正文可以初始化正文 Canonical；解析出的知识仍必须进入 Knowledge Draft。
- 导出创建、完成前和下载时都要重验权限、来源状态和授权快照。

## 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、重建投影任务 |

约束：

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

### 5.3 Local KB 表

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

约束：

- Local KB 不需要单独容器表，由 `work_id` 归属表达。
- 用户确认 Knowledge Draft 或手动知识修正才写 Local KB。
- 正式知识修改必须保留来源、操作者、旧值、新值和风险处理结果。

### 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` | 风险标记摘要 |
| `status` | `pending` / `confirmed` / `ignored` / `stale` / `invalidated` / `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` | `active` / `stale` / `revoked` / `blocked` / `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 的来源快照、授权快照、来源状态事件和传播目标，避免每个业务模块各自保存一份“当前授权通过”的临时布尔值。

### 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` / `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` | `active` / `stale` / `revoked` / `recalled` / `blocked` / `owner_missing` / `needs_recheck` |
| `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` / `needs_recheck` |
| `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` | `source_updated` / `source_revoked` / `asset_recalled` / `asset_blocked` / `owner_missing` / `license_changed` / `authorization_expired` / `authorization_revoked` |
| `event_version` | 同一来源事件版本，单调递增 |
| `event_status` | `pending` / `propagating` / `completed` / `partially_failed` / `failed` |
| `reason_code` / `reason_message` | 状态变化原因摘要 |
| `source_owner_module` | 冗余 owner，便于路由传播 worker |
| `occurred_at` / `created_at` | 事件发生和记录时间 |

约束：

- `event_key` 唯一，outbox 消费必须幂等。
- 事件创建不直接改业务 Canonical；必须展开为 propagation target，由目标 owner 或 source propagation worker 按目标合同处理。

### 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` / `content_parse_result` / `knowledge_draft` / `local_kb_entity` / `local_kb_relation` / `local_kb_event` / `knowledge_source_binding` / `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` / `skipped` / `failed` / `retrying` |
| `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、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 明文、完整供应商响应或成本账本 authority。

### 7.2 系统功能链路和槽位

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

`muse_ai_system_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` | 某次试用、生成、解析、检测或质量评测的服务端权限包 |

运行权限包必须固化：

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

前端、Prompt、模型输出和智能体自述权限无效。

### 7.4 任务、候选和质量结果

| 表 | 职责 |
|---|---|
| `muse_ai_task` | 生成、续写、扩写、润色、解析、检测、质量评估等异步任务 |
| `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_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。
- Candidate 进入可接受状态前必须通过静态检查、来源状态校验、质量门控和输出合规。
- Candidate Decision Archive 只证明用户对候选的处理，不证明知识草稿已确认。
- 质量门控可以在 Shadow 内有限重写候选，但不能替用户确认正文或知识。

## 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` | 绑定或使用前的目标 owner 预检结果 |
| `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` | 重复收藏或取消收藏的幂等键 |

约束：

- 购买不等于安装。
- 安装不等于关联作品。
- 收藏不等于购买、授权或安装；收藏不写作品正文、规划正式项、Local KB 或 Agent Slot Binding。
- 安装、绑定和 handoff 只授予账户可用性、目标空间预检结果或短期跳转上下文，不写作品正文、规划正式项或 Local KB。
- 绑定预检必须由目标 owner 校验权限、状态、版本、许可、来源和目标对象。
- handoff 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-account`，还是改造 `member`，后端落地前需要单独决策。无论物理模块如何选择，账户相关 Schema 只保存 Muse 创作系统所需的权益、用量和聚合视图。

| 表 | 职责 |
|---|---|
| `muse_account_profile_ext` | Muse 展示名、创作偏好入口等扩展资料 |
| `muse_account_preference` | 用户偏好、通知偏好、创作辅助偏好 |
| `muse_account_entitlement_snapshot` | 套餐、配额、余额或外部网关权益的本地快照 |
| `muse_account_entitlement_ledger` | 权益变更 append-only 流水，承接购买、赠送、到期、撤销和管理员调额结果 |
| `muse_account_quota_adjustment` | 管理员调额请求记录，支持幂等、原因、前后值和审计 |
| `muse_account_usage_record` | 生成、检索、评估、导出等任务级用量归属摘要 |
| `muse_account_asset_summary` | 个人中心资产摘要读模型 |
| `muse_account_security_event` | 登录、敏感导出、凭证失效、异常访问等安全事件摘要 |
| `muse_account_export_task` | 个人资料、安全事件或账户记录导出任务 |

`muse_account_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_account_entitlement_ledger` 字段合同：

| 字段语义 | 要求 |
|---|---|
| `account_user_id` | 账户 owner |
| `ledger_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` | 业务原因 |
| `audit_event_id` | 审计事件引用 |

约束：

- `muse_account_usage_record` 不是 New-API 成本账本 authority。
- `muse_account_entitlement_ledger` 和 `muse_account_quota_adjustment` 均为 append-only；错误调整必须用反向流水或撤销记录补偿，不能覆盖原记录。
- 管理员调额必须写幂等键、原因、前后值、操作者和审计事件。
- 个人中心是 read model 和跳转入口，不反写作品、知识、市场资产或 AI 任务事实。
- 账户导出只能导出个人中心 owner 范围内的数据，并记录下载审计；`muse_account_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-tasks` 不直接写 Local KB | `muse_content_parse_task` 记录任务，`muse_content_parse_result` 记录 Shadow 结果，只产生或更新 `muse_knowledge_draft` |
| 章节解析确认不写 Local KB | 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 分离 |
| 市场收藏不代表授权或安装 | `muse_market_collection` 只保存用户市场行为 |
| 用户只替换开放槽位 | `muse_ai_override_slot` / `muse_ai_agent_slot_binding`，保护节点在 `muse_ai_protected_node_registry` |
| 入 RAG 不反写事实 | `muse_knowledge_processing_job` / `muse_projection_task` 只产投影和索引 |
| 导出必须重验来源许可 | Export Task + Download Credential + Authorization Snapshot |
| 管理员不替用户确认私有事实 | Admin 接口只写配置、治理和审计；Content/Knowledge 决策命令必须校验 owner 用户 |
| 管理员调额必须可追溯 | `muse_account_quota_adjustment` + `muse_account_entitlement_ledger` append-only，保留幂等键、原因、前后值和审计 |

## 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_task_id + chapter_id + review_status`。
- 当前候选：`work_id + status + create_time`。
- 知识草稿：`work_id + status + update_time`。
- Local KB 检索：`work_id + entity_type + name`。
- 用户知识库：`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_content_parse_task(idempotency_key)`。
- `muse_content_meta_schema(domain, scope, target_type, schema_key)`。
- `muse_content_meta_schema_version(schema_key, version_no)`。
- `muse_knowledge_entity(work_id, entity_type, normalized_name)`。
- `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_ai_system_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_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_account_quota_adjustment(idempotency_key)`。
- `muse_account_entitlement_ledger(idempotency_key)`。
- `muse_outbox_event(event_key)`。

激活唯一约束：

- MetaSchema：同一 `schema_key + effective_scope` 仅一条 `active_flag = true` 的 `muse_content_meta_schema_version`。
- Function Chain：同一 `chain_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_ai_system_function_chain_version`。
- Quality Policy：同一 `policy_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_ai_quality_policy_version`。

### 12.3 JSON 查询

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

## 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` 是新增模块还是改造 `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`