oh-my-muse/design-docs/后端-02-工程结构与模块职责.md

后端-02：工程结构与模块职责

• 版本：v9
• 更新日期：2026-07-09
• 目标读者：后端 / 架构 / 平台 / 测试
• 阅读时间：25-40 分钟
• 边界说明：本文件只定义后端工程基线、Yudao Cloud fork 保留/裁剪模块、Muse 业务模块职责和模块协作边界。领域模型看 后端-01，关键流程看 后端-03，Schema 看 后端-04，API 契约看 后端-05。本文描述目标工程形态，不代表当前仓库所有模块都已实现。
• 变更记录：v9（2026-07-09）§3.4 Governance Facade 落点表补系统功能链路一行——逻辑写入 authority 为 Governance facade、物理落 yudao-module-meta，与 MetaSchema 同模式（案 A，见 架构-03 ADR-022）。

1. 工程基线

Muse 后端使用 YunaiV/yudao-cloud 的 fork，目标仓库命名为：

muse-cloud/  # fork YunaiV/yudao-cloud

定位：Yudao Cloud 做后端微服务/单体聚合底座，先继承它的网关、权限、基础设施、配置、日志、文件、任务等平台能力，再补 Muse 自己的业务模块。

核心原则：

1. 后端按领域能力拆模块，不按管理端/用户端拆模块。
2. /admin-api/** 和 /app-api/** 只是入口不同，不是两套领域事实。
3. 同一个领域事实只能有一个 owner module。
4. 优先复用 Yudao 的 system、infra、framework、gateway、job、log、file、config、dict 等平台能力。
5. Muse 业务模块只补创作系统需要的 content、knowledge、ai、market、meta 能力，account 功能由 yudao-module-member 承载。
6. yudao-server 只负责启动装配、配置聚合和模块引入，不放 use case、领域规则、mapper 拼装或跨模块写入脚本。

2. 当前保留模块

模块	定位	阶段 7 处理
yudao-gateway	统一入口、路由、认证透传、接口聚合	保留，承接 /admin-api/** 与 /app-api/** 路由
yudao-dependencies	依赖版本管理	保留，不复制依赖版本到 Muse 模块
yudao-framework	Web、安全、Redis、MQ、Job、日志、通用能力	保留，Muse 模块按 Yudao 方式接入
yudao-server	当前聚合启动入口，默认启用 system、infra	保留，作为本阶段聚合启动入口；禁止承载业务逻辑
yudao-module-system	用户、角色、权限、菜单、登录日志、操作日志	保留并作为后台权限、菜单和用户基础能力 owner
yudao-module-infra	文件、字典、配置、定时任务、API 日志、监控	保留并作为基础设施能力 owner
yudao-module-ai	Yudao AI 基础能力	保留，默认隐藏；后续二开为 Muse AI/Agent 能力载体
yudao-module-member	会员/账户基础能力；已决策为 Muse Account BC 物理承载	保留并启用；承载端侧用户 Profile、Entitlement、Quota、Usage、Security Event 和 New-API Binding
yudao-module-pay	支付、充值、交易基础能力	保留，默认隐藏；市场交易、套餐、充值时启用
yudao-module-bpm	工作流审批	保留，默认隐藏；审核、申诉、合规流程复杂后启用
yudao-module-report	报表大屏	保留，默认隐藏；运营报表、质量大屏时启用
yudao-module-mp	公众号能力	保留，默认隐藏；公众号分发、订阅通知、运营需要时启用

已清理模块：

• mall
• crm
• erp
• mes
• iot
• 空壳 yudao-cloud/yudao-ui

注意：mp 明确保留，不删除。

保留模块分层：

• gateway/dependencies/framework/server 是工程底座。
• system/infra/member/pay/bpm/report/mp 是 Yudao 平台和可选业务底座；其中 member 同时承载 Muse Account BC。
• content/knowledge/ai/market/meta 是 Muse 创作业务 owner。
• pay/bpm/report/mp 在阶段 7 可以默认隐藏，但不能因为隐藏就删除依赖、菜单扩展点或后续接入边界。

3. Muse 核心业务模块

3.1 模块清单

Muse 模块	职责	不负责
yudao-module-content	作品、章节、文本块、正文版本、作品设置、导入任务、导入文件、章节上下文、导出、Block Source Attribution	Prompt、Agent、市场授权、知识确认、MetaSchema 治理写入、Parse Job / Chapter Parse Result
yudao-module-knowledge	用户知识库、局域知识、知识草稿确认、知识来源、投影、检索来源、知识库绑定	正文写入、市场交易、模型调用
yudao-module-ai 二开	Prompt、Agent、槽位、运行时权限包、生成任务、Parse Job、Chapter Parse Result、候选、质量门控、评测、Tool Grant 投影、Context Assembly、Candidate Archive	New-API 模型 Provider/供应商路由、成本策略、原始调用日志 authority、正文或知识 Canonical、Tool Grant authority 自授权
yudao-module-meta	MetaSchema 元结构定义、字段、可见性策略、版本发布、激活、回滚和影响预览	用户作品正文、Local KB、候选确认、市场目标事实
yudao-module-market	市场资产、授权、安装、来源侧 Handoff Token、授权摘要、跳转审计、发布申请、申诉、治理结果（含市场治理）	作品正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层
yudao-module-member	个人资料、权益、配额、用量、安全事件、New-API 绑定、购买/授权/发布记录总览（Account BC 物理承载）	作品事实、市场资产 owner、New-API 原始调用日志或成本账本 authority

Account BC 物理落点已决策：使用现有 yudao-module-member 模块承载端侧用户（Account）功能，不新增 yudao-module-account。member = 端侧用户，语义等同于 Account BC 的物理承载。

member 模块扩展职责：除 Yudao 原有会员基础能力外，新增 Muse 的权益（Entitlement）、配额（Quota）、用量（Usage）、安全事件（Security Event）和 API 绑定（New-API Binding）。

包结构建议：

yudao-module-member/
  yudao-module-member-api/
    admin/
    app/
    event/
  yudao-module-member-server/
    controller/admin/
    controller/app/
    application/
    domain/
      profile/        # 用户画像/偏好
      entitlement/    # 权益
      quota/          # 配额
      usage/          # 用量
      security/       # 安全事件
      binding/        # New-API 绑定
    infrastructure/

3.2 标准模块结构

Muse 新模块继续按 Yudao 风格组织：

yudao-module-xxx/
  yudao-module-xxx-api/
    admin/
    app/
    event/
  yudao-module-xxx-server/
    controller/admin/
    controller/app/
    application/
    domain/
    infrastructure/

约束：

• yudao-module-xxx-api/admin 与 yudao-module-xxx-server/controller/admin 服务管理后台，接口前缀归入 /admin-api/**。
• yudao-module-xxx-api/app 与 yudao-module-xxx-server/controller/app 服务用户端 muse-studio，接口前缀归入 /app-api/**。
• yudao-module-xxx-api/event 承载跨模块事件、outbox 消息、回调 DTO 和 facade DTO，不放领域事实。
• domain 持有聚合、不变式、领域服务和状态机判断，不能依赖 controller、Yudao Web DTO 或外部 API DTO。
• application 编排用例、事务、幂等、权限摘要、跨模块 facade 和 outbox。
• infrastructure 接数据库、Redis、MQ、文件、外部服务、Yudao 基础设施和 mapper。
• Controller 只做参数校验、权限入口和响应转换，不直接拼业务规则。

示例：

yudao-module-content/
  yudao-module-content-api/
    admin/
    app/
    event/
  yudao-module-content-server/
    controller/admin/
    controller/app/
    application/
    domain/
    infrastructure/

禁止出现 yudao-server/src/main/java/.../muse/... 这类承载业务用例的过渡目录；如果为了启动聚合需要配置 Bean，只能在 yudao-server 做模块装配。

3.3 Agent BC 与 AI Orchestration BC 包级隔离策略

yudao-module-ai 在同一物理模块内承载 Agent BC（智能体配置、版本、槽位）和 AI Orchestration BC（任务编排、候选生成、质量门控、上下文组装）。为防止职责混淆和越权调用，必须在包级别做隔离：

yudao-module-ai-server/
  domain/
    agent/          # Agent BC：Agent、AgentVersion、Slot、SlotBinding
    orchestration/  # AI Orchestration BC：Task、Candidate、QualityGate、ContextAssembly、ParseJob
    grant/          # Tool Grant 投影消费（只读）+ Protection Node + Quality Policy 写入服务
  application/
    agent/          # Agent 配置用例
    orchestration/  # 编排运行用例
    grant/          # Grant/Governance 包：Tool Grant、Runtime Permission Envelope、Protection Node 写入服务，只暴露给 admin-api
  controller/
    admin/
      grant/        # /admin-api/muse/ai/tool-grants/**、/admin-api/muse/governance/protection-nodes/**
    app/
      runtime/      # /app-api/muse/ai/**

AI 授权隔离（grant vs runtime）：

包	职责	暴露入口
ai.grant（application/grant + domain/grant）	Tool Grant 写入、Runtime Permission Envelope 签发、Protection Node 写入服务	只暴露给 admin-api（Governance facade 调用）
ai.runtime（application/orchestration + domain/orchestration）	AI 任务执行、候选生成、上下文组装	只能读取 grant 包签发的 envelope，不能调用 grant 写入接口

ArchUnit 规则：

// 禁止 runtime 包调用 grant 包的写入接口
noClasses()
    .that().resideInAPackage("..ai.application.orchestration..")
    .or().resideInAPackage("..ai.domain.orchestration..")
    .should().accessClassesThat()
    .resideInAPackage("..ai.application.grant..")
    .orShould().callMethodWhere(
        target(nameMatching(".*Write.*|.*Create.*|.*Update.*|.*Delete.*|.*Publish.*"))
        .and(target(owner(resideInAPackage("..ai.domain.grant.."))))
    );

依赖方向约束：

包	允许依赖	禁止依赖
domain/agent	自身聚合、domain/grant（只读投影）	domain/orchestration 内部实现
domain/orchestration	自身聚合、domain/agent（只读版本查询）、domain/grant（只读投影）	domain/grant 写入方法
domain/grant	无外部领域依赖	domain/agent、domain/orchestration
application/grant	domain/grant（读写）、外部 Governance/Security facade	application/orchestration、domain/orchestration
application/orchestration	domain/orchestration、domain/agent（只读 facade）、domain/grant（只读）	application/grant 写入用例

Tool Grant 写入约束：

• Tool Grant 的创建、审批、变更和版本发布只能通过 governance/security facade 包路径完成，物理入口在 Governance/Admin facade 或 Security facade。
• domain/grant 包内只暴露只读投影查询接口（ToolGrantProjectionQuery），不暴露任何写入方法。
• AI runtime（domain/orchestration、application/orchestration）只能调用 domain/grant 的只读投影生成 Runtime Permission Envelope，不能直接调用 grant 写入方法。
• 违反此约束的代码在 code review 和 ArchUnit 规则中必须被拦截。

3.4 Governance Facade 工程落点

Governance facade 是 MetaSchema、保护节点、系统功能链路、Tool Grant 和质量策略的逻辑写入 authority。工程落点已明确拆分：

职责	物理位置	说明
MetaSchema 全部能力	yudao-module-meta（独立模块）	admin 写入 + 用户作品级覆盖 + facade-api 只读消费；Content、Knowledge、AI 等模块通过 meta-api 只读依赖消费 active/gray 投影
系统功能链路定义与版本	yudao-module-meta（独立模块）	与 MetaSchema 同模式（案 A）：Governance facade 为逻辑写入 authority、物理落 meta 模块；meta-api 增 FunctionChainQueryApi 只读端口，AI runtime 按激活功能链解析节点序列与开放槽位
Protection Node + Quality Policy	yudao-module-ai-server/application/grant/	AI grant 包承载保护节点和质量策略的写入服务，只暴露给 admin-api
Tool Grant authority 实现	yudao-module-ai-server/application/grant/	写入入口只接受 Governance/Security facade 调用
市场治理	yudao-module-market-server/controller/admin/	市场资产下架、召回、封禁、申诉处理等治理动作归 market admin 包

yudao-module-meta 模块结构：

yudao-module-meta/
  yudao-module-meta-api/
    admin/          # MetaSchema 管理 DTO、facade 接口
    app/            # 用户作品级覆盖 DTO
    facade/         # 只读消费 facade（供 content/knowledge/ai 依赖）
  yudao-module-meta-server/
    controller/admin/   # /admin-api/muse/governance/meta-schemas/**
    controller/app/     # /app-api/muse/works/{workId}/meta-projections/**
    application/
    domain/
      schema/           # MetaSchema、MetaField、VisibilityPolicy
      version/          # 版本发布、激活、回滚、灰度
      projection/       # 投影计算和缓存
    infrastructure/

约束：

• yudao-module-meta 是 MetaSchema 唯一写入 authority。
• Content、Knowledge、AI 等模块只能通过 meta-api/facade 只读消费 active/gray 投影。
• 用户作品级覆盖（work-level override）通过 app 入口提交，但仍由 meta 模块校验和存储。
• Content 模块不再物理承载 MetaSchema 表。

4. 模块边界

4.1 owner 边界

领域事实	owner module	可读协作者
用户、角色、权限、菜单	yudao-module-system	全部模块通过权限摘要或用户上下文读取
文件、配置、字典、任务、API 日志	yudao-module-infra	全部模块按 Yudao 基础设施方式调用
作品、章节、Block、正文版本	yudao-module-content	knowledge、ai、market、account
MetaSchema、元结构版本、字段定义、可见性策略	yudao-module-meta	content、knowledge、ai、market、account
用户知识库、局域知识、知识草稿、来源绑定	yudao-module-knowledge	content、ai、market
Prompt、Agent、Parse Job、Chapter Parse Result、任务、候选、质量门控、评测、Candidate Archive	yudao-module-ai	content、knowledge、market、account
市场资产、授权、安装、发布、申诉、治理、来源侧 Handoff Token、授权摘要、跳转审计	yudao-module-market	content、knowledge、ai、account
权益、配额、用量、购买/授权/发布记录总览	yudao-module-member	market、ai、personal center read model
Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation Target	来源对象 owner + 授权签发 owner；横切表级 owner 跟随来源 owner，不归入 Knowledge 单模块	content、knowledge、ai、market、account

Source / Authorization Context 是横切上下文：来源 owner 负责发布 Source Status Event，受影响对象 owner 负责幂等消费、禁用新使用或刷新自己的读模型。Knowledge 只拥有知识来源绑定和知识投影，不拥有所有来源授权事实。

Source / Authorization 物理归属：

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

4.2 跨模块调用规则

场景	允许方式	禁止方式
查询摘要	通过 api facade、只读 query service 或事件投影读取	直接跨模块读写对方表并推断状态
写入事实	回到 owner module 的 application use case	在调用方 mapper 里直接写对方事实
异步协作	outbox event + 幂等 consumer + 可重试任务	MQ 消费端无幂等直接改 Canonical
MetaSchema 治理	/admin-api/muse/governance/** 经 yudao-module-meta 写 MetaSchema 草稿、发布、激活、回滚和影响预览	Content app/admin controller 任意写字段结构或让用户端绕过治理改 Schema
Tool Grant	Governance / Security facade 发布授权，AI runtime 只消费授权投影生成权限包	yudao-module-ai 按 Prompt、模型输出或 Agent 自述给自己增加工具、上下文、外发或预算
Handoff	market 只写 Authorization / Install / 来源侧 handoff token / 授权摘要 / 跳转审计，目标 owner 生成并消费自己的 precheck/session	市场模块直接写槽位、知识绑定、正文归因、作品正文或目标预检结果
Source Status Event	来源 owner 发布事件，影响对象 owner 幂等处理	查询时临时拼状态但不落传播结果

4.3 禁止事项

• 不按 admin 和 app 复制两套领域服务。
• 不让管理后台 controller 直接写用户作品正文、知识事实或候选确认结果。
• 不让用户端 controller 直接修改 MetaSchema、系统 Prompt、系统 Agent、质量策略、Tool Grant 或市场治理结果。
• 不让 Content controller 把 MetaSchema 当普通作品表单结构随意更新；MetaSchema 写入只能经 yudao-module-meta、影响预览、版本发布和审计。
• 不让 yudao-module-ai 自授工具、上下文、外发目标、预算或来源访问权限；运行时只能消费服务端签发的 Runtime Permission Envelope。
• 不让 yudao-server 聚合层承载业务逻辑。
• 不让 infra、system 成为 Muse 业务事实的万能容器。
• 不把 New-API 的模型 Provider、供应商路由、分组限流、成本策略和原始调用日志复制成 Muse 本地 authority。

5. 外部集成边界

集成	后端定位	约束
New-API	外部模型网关 authority	Muse 只保存网关绑定引用、任务级摘要、调用归属、错误分类、幂等键和补偿状态；不保存密钥明文、完整 Prompt/Response、模型 Provider/供应商路由、成本策略或原始调用日志 authority
RAGFlow / GraphRAG	检索和投影消费方	只能消费 Muse owner 模块中的正式事实或授权资料投影；不能反向决定作品事实
文件存储	走 Yudao infra 文件能力	导入、导出、市场素材、知识库资料都必须有 owner、权限、来源、文件 hash、大小、MIME、扫描状态、保留期和清理策略；infra 只存 blob，不拥有业务事实
Job / MQ	走 Yudao framework/infra 能力	AI 任务、投影、导出、评估、来源传播必须幂等、可重试、可审计
Pay	走 yudao-module-pay	市场交易、套餐、充值启用时再接入；交易事实不混入 market asset owner
BPM	走 yudao-module-bpm	审核、申诉、合规流程复杂后启用；简单状态机先由对应领域 owner module 承载

6. 运行形态

阶段 7 默认采用 Yudao Cloud 聚合启动形态：

yudao-gateway
  -> yudao-server
       -> yudao-module-system
       -> yudao-module-infra
       -> yudao-module-meta              # MetaSchema 独立模块
       -> yudao-module-content
       -> yudao-module-knowledge
       -> yudao-module-ai
       -> yudao-module-market
       -> yudao-module-member          # 承载 Account BC

可以按模块边界演进到微服务，但阶段 7 文档不要求立即拆成多进程。无论单体聚合还是微服务，领域 owner、API 前缀、权限边界和事件合同保持不变。

7. 权限与入口

• 管理后台入口：/admin-api/**，由 Vben Admin 调用。
• 用户端入口：/app-api/**，由 muse-studio 调用。
• 网关和服务端均必须校验认证、权限、租户/用户上下文、作品访问权和业务前置条件。
• 前端隐藏菜单、默认隐藏模块或路由守卫只是体验边界，不是安全边界。
• 系统任务必须使用明确服务身份、权限范围和审计上下文，不得伪装成普通用户确认正文、知识或候选。

8. 关联阅读

• 领域模型：后端-01-领域模型与聚合设计.md
• 关键流程：后端-03-关键流程实现与接口契约.md
• Schema：后端-04-统一数据库Schema-v1.md
• API：后端-05-统一API契约-v1.md
• 系统边界：架构-01-系统全貌与边界上下文.md
• AI 编排专题：专题-03-AI编排上下文与质量评测实现规范.md