33aad93bef
基于产品/架构/流程/前端/后端五维度并行review，澄清并落地22项关键决策： 架构层：Governance按消费者归属拆散、MetaSchema独立模块、 Source传播改为事件驱动自治、去掉Candidate Decision Envelope 和needs_recheck中间状态、Neo4j决策为依赖RAGFlow GraphRAG 后端层：Entitlement统一为可变表+审计日志、API版本策略采用 X-API-Version Header、知识实体唯一键加scope字段 前端层：SSE实时通信（AI stream独立+事件统一）、正文持久化 IndexedDB安全网、Block粒度为场景/小节级 产品层：范围不变UX解决复杂度、知识确认默认自动+冲突时人工
1164 lines
74 KiB
Markdown
1164 lines
74 KiB
Markdown
# 后端-04：统一数据库 Schema(结构定义)-v1
|
||
|
||
- 版本：v10
|
||
- 更新日期：2026-05-24
|
||
- 目标读者：后端 / 架构 / 前端 / 数据库维护者 / 测试
|
||
- 阅读时间：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 拆分；逻辑 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_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_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` | 字段定义、类型、必填、枚举、引用、排序和校验规则 |
|
||
| `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_entity`、`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` | 激活人和激活时间 |
|
||
|
||
约束：
|
||
|
||
- 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 明文、完整供应商响应或成本账本 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` | 某次试用、生成、解析、检测或质量评测的服务端权限包 |
|
||
|
||
`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_ai_override_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_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_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_ai_system_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`
|