oh-my-muse/design-docs/后端-01-领域模型与聚合设计.md

后端-01：领域模型与聚合设计

• 版本：v7
• 更新日期：2026-05-24
• 目标读者：后端 / 架构 / 产品
• 阅读时间：30-45 分钟
• 边界说明：本文件只定义 Muse 领域模型、聚合职责、owner module 和不变式；工程结构看 后端-02，流程看 后端-03，Schema 看 后端-04，API 看 后端-05。

1. 设计原则

1. 领域事实按业务 owner 归属，不按管理端/用户端归属。
2. admin-api 和 app-api 是入口差异，不是两套模型。
3. Yudao 的 system/infra/pay/bpm/report/mp 是平台能力和可复用底座，不承载 Muse 创作事实。
4. AI、市场、知识库、作品、账户权益都必须有完整入口、状态、来源、审计和失败路径，不能做孤儿模型。
5. Shadow -> Canonical 的用户主权和来源 lineage 是后端硬约束，不能依赖前端自觉。
6. Protected Node Registry 是保护节点唯一口径，开放槽位只能替换子智能体，不能绕过保护节点。

平台底座的含义必须收紧：

Yudao 底座	Muse 使用方式	禁止承载
yudao-gateway	统一入口、鉴权透传、路由 /admin-api/** 与 /app-api/**	领域判断、候选确认、知识确认
yudao-dependencies / yudao-framework	依赖、Web、安全、Redis、MQ、Job、日志等基础能力	任何 Muse 业务事实
yudao-server	聚合启动入口和模块装配	业务规则、事务脚本、跨模块事实写入
yudao-module-system	用户、角色、权限、菜单、登录日志、操作日志	作品正文、知识、市场授权、AI 候选
yudao-module-infra	文件、配置、字典、任务、API 日志、监控	创作事实、权益账本、市场事实
yudao-module-pay	支付、充值、退款和交易基础能力	市场资产 owner、授权快照、作品事实
yudao-module-bpm	复杂审核、申诉、合规流程编排	简单业务状态机的唯一事实源
yudao-module-report	报表、大屏、运营分析	业务事实写入
yudao-module-mp	公众号分发、订阅通知、运营触达	创作、知识、市场或账户事实

2. BC 到 Yudao 模块映射

本映射是逻辑 owner 到 Yudao fork 模块的目标落点。若落地阶段临时折叠到现有模块，也必须保留逻辑 owner，不允许两个模块同时写同一个事实。

BC	owner module	主要对象	Admin/App 入口	不负责
Auth / Permission	yudao-module-system	用户、角色、权限、权限组、菜单、登录日志、操作日志	Yudao 原生 admin/app 认证与权限接口	作品级事实确认、知识确认、市场授权事实
Infra	yudao-module-infra	文件、配置、字典、定时任务、API 日志、监控	Yudao 原生 infra 接口	Muse 业务领域事实
MetaSchema BC	yudao-module-meta（独立模块）	MetaSchema、元结构版本、字段定义、可见性策略、影响预览和发布审计	/admin-api/muse/governance/meta-schemas/**（admin 写）、facade-api 只读消费	用户私有正文、Local KB Canonical、候选确认、市场目标事实、保护节点、质量策略
Content BC	yudao-module-content	Work、Chapter、Block、正文版本、Planning Canonical、Block Source Attribution、导入导出任务、作品设置	/admin-api/muse/content/**、/app-api/muse/works/**	Prompt、Agent、知识确认、市场交易、MetaSchema 治理写入
Knowledge BC	yudao-module-knowledge	User KB、Local KB、Knowledge Draft、Knowledge Entity/Relation/Event、Knowledge Source Binding、投影状态	/admin-api/muse/knowledge/**、/app-api/muse/knowledge-*/**	正文写入、市场资产授权、模型路由
AI Orchestration BC	yudao-module-ai 二开	Prompt、Agent、Agent Slot、Tool Grant 投影、Runtime Permission Envelope、AI Task、Parse Job、Chapter Parse Result、Suggestion、Planning Candidate、Quality Result、Evaluation Dataset/Run	/admin-api/muse/ai/**、/app-api/muse/ai/**、/app-api/muse/suggestions/**	New-API 模型 Provider/供应商路由、分组限流、成本策略、原始调用日志 authority、用户权益账本、正文 Canonical、Tool Grant authority 自授权
Marketplace/Asset BC	yudao-module-market	Marketplace Asset、Listing、License、Authorization、Install、Publish Request、Appeal、Governance Result、来源侧 Handoff Token、授权摘要、跳转审计、Source Status Event	/admin-api/muse/market/**、/app-api/muse/marketplace/**	正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层
Account / Entitlement BC	yudao-module-member（已决策：member 模块承载端侧用户 Account 功能）	Profile、Entitlement、Quota、Usage Summary、Purchase/Auth/Publish Summary、Personal Center Summary	/admin-api/muse/account/**、/app-api/muse/account/**、/app-api/muse/me	作品事实、市场 asset owner、New-API 原始调用日志或成本账本 authority
Source / Authorization Context	来源对象 owner + outbox 协作	Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation Target	通过 Content / Knowledge / AI / Market / Account 的 owner API 和 /admin-api/muse/source-events/** 暴露	业务 Canonical 写入、支付清结算、权限菜单
Payment BC	yudao-module-pay	充值、支付、交易流水、退款基础能力	Yudao 原生 pay 接口，Muse 只引用交易结果	市场资产 owner、作品事实
Workflow BC	yudao-module-bpm	复杂审核、申诉、合规流程	Yudao 原生 bpm 接口或 Muse 流程回调	简单资产状态机的唯一 owner

Account BC 物理落点已决策：yudao-module-member。member 模块承载端侧用户的 Profile、Entitlement、Quota、Usage、Security Event 和 New-API Binding 聚合。不新增 yudao-module-account；member 内的 Muse account 包是唯一写入 authority，不允许并行新增另一个模块写同一批事实。

3. 核心聚合

3.1 Content

聚合/实体	说明	不变式
Work	单个创作项目，也是市场作品资产的来源对象	owner 用户不可丢；发布到市场不转移作品私有事实 owner
Chapter	作品结构单元	同一 Work 内排序唯一；章节审阅不直接写正式知识
Block	正文最小编辑单元	revision 单调递增；任何正文写入必须基于 expectedRevision
Block Source Attribution	正文 revision 的来源归因	候选使用 AI、市场、外部或授权知识来源时必须写入 lineage、授权快照和召回状态
Import / Export Task	导入解析和导出交付任务	外部文件处理异步化；导出前必须重验权限、来源和许可
Planning Canonical	用户确认或手动保存后的正式规划项	规划候选不能自动进入正式规划；进入 AI 上下文前必须校验来源、版本和可见性
MetaSchema Projection	作品和知识表达结构的系统级版本化投影	逻辑 owner 是 yudao-module-meta（独立模块）；Content 和 app API 只能消费 active/gray 版本投影

Content 只拥有正文和作品结构。知识、AI 候选、市场授权都通过公开接口或事件协作。

3.2 Knowledge

聚合/实体	说明	不变式
User Knowledge Base	用户自己的可复用知识库，可绑定作品、可发布市场	不自动写入任一作品 Local KB
Local Knowledge Base	单作品正式知识空间	只归属当前 Work，不跨作品共享 Canonical
Knowledge Draft	待确认知识变更	必须有来源快照、授权快照、风险标记和确认入口
Knowledge Source Binding	知识来源和授权绑定	来源 revoked/recalled/blocked/owner_missing/unauthorized 时禁止新确认、新绑定或受限导出
Projection State	PG 到检索/图查询的投影状态	投影不是事实源，失败可重试，不反写 Canonical

知识草稿进入 Local KB 的唯一入口是用户在知识确认入口显式确认。接受正文候选不自动确认知识草稿。

全局知识库由管理员治理策略和 Knowledge 处理能力共同承接：管理员决定可见性、授权范围和启停策略，Knowledge 负责资料处理、索引、投影和绑定状态。全局知识不能因为被授权、安装或绑定而自动成为作品事实。

3.3 AI Orchestration

聚合/实体	说明	不变式
Agent	配置型或工作流型智能体	只能替换开放槽位，不能替换保护节点
Agent Slot Binding	作品级智能体槽位绑定	必须绑定版本、授权、来源状态和预检快照
Tool Grant	工具授权投影	授权 authority 来自 Governance / Security facade；AI 模块只能按版本消费授权集合，不能自授工具、上下文或外发权限
Agent Runtime Permission Envelope	智能体运行时权限包	由安全 facade 和运行时执行器按 actor、source、authorization、tool grant 生成；智能体和前端不能自报可读上下文、工具、外发目标或预算
AI Task	生成、解析、检测、评估任务	任务启动时固化权限包、上下文快照、配置快照和幂等键
Parse Job / Chapter Parse Result	导入解析和全书解析的 AI Shadow 结果	AI 拥有任务、章节解析结果、质量和失败状态；章节审阅通过后只请求 Knowledge 生成 Knowledge Draft
AI Suggestion	正文候选	只能进入 Shadow，不能直接写正文
Planning Candidate	规划候选	只能进入 Shadow，必须经用户确认或手动保存后才成为正式规划
Candidate Quality Result	候选质量结果	质量结果不单独决定可接受性，接受时实时校验来源版本、质量结果和合规状态
Evaluation Dataset / Run	质量评估集和评估运行	默认不得使用用户私有正文、私人候选全文、完整 Prompt/Response 或完整上下文

AI 模块负责 Muse 侧编排、智能体、任务和待审对象。Yudao 原生 ai 能力只是可复用底座；一旦二开为 Muse AI owner，仍不得拥有 New-API 模型 Provider、供应商路由、分组限流、成本策略、原始调用日志 authority 或正文/知识 Canonical。

Agent 配置、Tool Grant authority、运行时权限包和审计必须分层：Agent 版本只描述 Prompt、参数、输出合同和可用槽位；Tool Grant authority 由 Governance / Security facade 发布；运行时执行器只能消费已发布授权并生成不可扩权的 Runtime Permission Envelope；审计由触发动作 owner 写入，AI 不能用模型输出或 Prompt 反向扩大权限。

3.4 Marketplace

聚合/实体	说明	不变式
Marketplace Asset	作品、智能体、知识库市场对象	市场上架不改变原 owner，也不自动写入购买者作品事实
Listing	上架记录	必须经过发布检查、授权快照和治理状态
License	授权规则	阅读、安装、绑定、生成上下文、导出、商用必须按用途分开授权
Authorization / Install	授权和安装状态	只记录市场授权、安装和可展示状态；不写目标对象绑定事实
Handoff / Precheck	跨空间跳转包和目标 owner 预检凭证	Market 只保存来源侧 handoff token、授权摘要和跳转审计；agentSlotPrecheckId、kbBindPrecheckId、workAssetUsePrecheckId 必须由目标 owner 生成、签名或原子消费
Source Status Event	来源状态事件	撤权、下架、召回、owner 缺失、版本变化、处理失败和需重验必须可幂等传播
Appeal / Governance Result	申诉和治理结果	召回、下架、blocked 必须通过 Source Status Event 传播

市场 owner 只拥有市场资产、Authorization、Install、来源侧 Handoff Token、授权摘要、跳转审计和治理结果。目标 precheck/session、签名消费凭证和目标事实必须回到目标 owner：Agent Slot Binding 由 AI 写，Knowledge Source Binding 由 Knowledge 写，作品正文或 Block Source Attribution 由 Content 写，账户聚合由 Account 写。市场展示状态只能通过目标 owner 的事件或状态回执刷新，不能直接写目标事实。

3.5 Account / Entitlement

账户模块是用户可见的权益和记录总览，不是所有消费账本的事实源。

对象	说明
Profile	普通用户资料和偏好
Entitlement / Quota	套餐、配额、能力开关和用量限制
Usage Summary	任务级用量摘要、New-API 引用和用户可见解释
Purchase/Auth/Publish Summary	购买、授权、发布记录总览

New-API 的模型 Provider、供应商路由、分组限流、成本策略和原始调用日志仍以 New-API 为准；Muse 只保留与自身任务、作品、权益和失败恢复相关的网关绑定引用、任务级摘要、调用归属、错误分类、幂等键和补偿状态。

3.6 Source / Authorization Context

Source / Authorization Context 是横切上下文，不是 Knowledge 单模块能力。来源对象由各自 owner 管理，授权快照和来源状态通过 outbox 传播。

对象	owner	不变式
Source Snapshot	来源对象 owner，例如 Content、Knowledge、AI、Market	只描述来源对象、版本和 owner，不写目标 Canonical
Authorization Snapshot	授权签发 owner	固化授权用途、范围、有效期、许可限制和撤销状态
Source Status Event	来源对象 owner	撤权、召回、blocked、owner 缺失、版本变化、处理失败必须幂等发布
Source Propagation Target	受影响对象 owner	Content、Knowledge、AI、Market、Account 幂等消费事件并更新自己的状态、禁用新使用或要求重验

3.7 Protected Node Registry

Protected Node Registry 是系统保护节点唯一口径，至少包含以下 registry ID；任何开放槽位、市场智能体或工作流智能体都只能挂在保护节点之后，不能替换这些节点：

Registry ID	保护节点	owner / 落点	约束
input_compliance / output_compliance / semantic_guardrail	输入合规、输出合规、语义安全围栏	AI application + 系统策略	用户智能体和市场智能体不能替换或关闭
permission_filter / audit	权限过滤、审计	各业务 owner + Yudao system/infra 基础能力	前端、智能体或批任务不能自报权限或跳过审计
chunking / rag_ingest	拆分切块、入 RAG	Knowledge pipeline	只能处理已授权资料和正式事实投影，失败可重试但不能反写 Canonical
static_check / quality_gate	静态检查、质量门控	AI application	可以阻断或标记风险，不能替用户确认正文、知识或规划
source_status_check	来源状态校验	来源 owner + 目标 owner	revoked/recalled/blocked/owner_missing/unauthorized 默认禁止新使用
shadow_to_canonical	Shadow -> Canonical	Content、Knowledge、AI 对应 owner	只能由用户确认或明确批量确认触发，不能被工作流智能体替代

4. 全局不变式

4.1 写入边界

• 用户保存正文写 Content Canonical。
• AI 只能写自己 owner 的 Shadow 对象，例如 AI Suggestion、Planning Candidate、Risk Marker、Parse Job 和 Chapter Parse Result；Knowledge Draft 由 Knowledge owner 在章节审阅确认或知识生成请求后创建。
• Accept Suggestion 只写正文、候选归档、Block Source Attribution 和必要 outbox；不写 Local KB。
• Knowledge Draft 必须经知识确认入口进入 Local KB。
• 全书解析章节确认只允许产生或推进章节范围内的 Knowledge Draft，不写正式知识。

关键流程 owner 和状态边界：

流程	owner 边界	错误 / 幂等 / 状态边界
规划	AI 只写 Planning Candidate；Content 只写用户确认后的 Planning Canonical	候选过期、来源失效、版本冲突时不写 Canonical；确认按 workId + candidateId + decisionId 幂等
全书解析	Content 拥有导入任务、文件、章节上下文和正文初始化；AI 拥有 Parse Job / Chapter Parse Result；Knowledge 只在章节审阅确认后拥有 Knowledge Draft / KB Canonical	章节级失败可重试；章节确认只推进 Knowledge Draft，不写正式知识；知识确认按 workId + chapterId + draftId + decisionId 幂等
知识库	Knowledge 拥有 KB、Knowledge Draft、Knowledge Source Binding 和投影状态	来源失效禁用新确认、新绑定和受限导出；投影失败可重试，不反写 Canonical
市场资产使用	Market 只写 Authorization、Install、来源侧 Handoff Token、授权摘要和跳转审计；目标 precheck/session 与目标事实由 Content / Knowledge / AI owner 写	token 过期、已消费、来源变化、目标 owner 缺失或目标凭证不匹配时拒绝写入；消费按目标 owner 凭证幂等；market 只通过事件刷新展示状态
New-API 用量	AI Task 记录网关调用引用和调用归属；Account 只汇总用户可见摘要；New-API 保持 Provider、路由、成本和原始调用日志 authority	超时、限流、回调失败按 task/request 幂等重试；Muse 只保存错误分类、幂等键和补偿状态

4.2 权限边界

• Yudao system 负责登录、角色、菜单、权限和基础审计。
• Muse 业务模块负责作品访问权、知识库授权、市场授权、Agent 槽位授权和导出许可。
• 管理员权限不等于可以替用户确认正文、知识草稿或 AI 候选。
• 系统任务必须使用服务身份，不得复用普通用户身份绕过 Shadow -> Canonical。

4.3 来源和授权边界

• 外部或授权来源进入上下文时必须有 Authorization Snapshot 和 Source Status。
• revoked、recalled、blocked、owner_missing、unauthorized 来源不得进入新生成、新确认、新绑定或受限导出。
• 修改后合并默认继承上游 lineage、授权快照、许可限制和召回状态；不能靠改写文本洗白来源。

4.4 配置快照

• Prompt、Agent、Tool Grant、Quality Policy、MetaSchema、授权策略都必须版本化。
• 已启动任务使用启动时配置快照，中途不能混用新旧配置。
• 管理员回滚只影响后续任务，不改写历史候选和质量结果。

5. 关联阅读

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