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

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

• 版本：v6
• 更新日期：2026-05-23
• 目标读者：后端 / 架构 / 平台 / 测试
• 阅读时间：25-40 分钟
• 边界说明：本文件只定义后端工程基线、Yudao Cloud fork 保留/裁剪模块、Muse 业务模块职责和模块协作边界。领域模型看 后端-01，关键流程看 后端-03，Schema 看 后端-04，API 契约看 后端-05。本文描述目标工程形态，不代表当前仓库所有模块都已实现。

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、account 能力。
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	会员/账户基础能力	保留，默认隐藏；后续评估改造成账户/权益或被 account 替代
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 平台和可选业务底座。
• content/knowledge/ai/market/account 是 Muse 创作业务 owner。
• pay/bpm/report/mp 在阶段 7 可以默认隐藏，但不能因为隐藏就删除依赖、菜单扩展点或后续接入边界。

3. Muse 核心业务模块

3.1 模块清单

Muse 模块	职责	不负责
yudao-module-content	作品、章节、文本块、正文版本、作品设置、导入任务、导入文件、章节上下文、导出、Block Source Attribution、MetaSchema 物理表和版本化投影消费	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 Decision Envelope / Archive	New-API 模型 Provider/供应商路由、成本策略、原始调用日志 authority、正文或知识 Canonical、Tool Grant authority 自授权
yudao-module-market	市场资产、授权、安装、来源侧 Handoff Token、授权摘要、跳转审计、发布申请、申诉、治理结果	作品正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层
yudao-module-account 或改造 member	个人资料、权益、配额、用量、购买/授权/发布记录总览	作品事实、市场资产 owner、New-API 原始调用日志或成本账本 authority

建议决策：业务语义上使用 account 承载权益、配额、用量、授权和发布记录；member 先作为 Yudao 可复用底座保留隐藏。是否物理新增 yudao-module-account，还是在 member 内二开，需要在后端落地前单独确认。

物理落地约束：account 与 member 只能二选一承载 Muse 账户权益事实。选择前，文档和 API 使用逻辑名 account；选择后，另一个模块只能作为依赖或适配层，不得并行写 Profile、Entitlement、Quota、Usage Summary 或 Personal Center Summary。

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 做模块装配。

4. 模块边界

4.1 owner 边界

领域事实	owner module	可读协作者
用户、角色、权限、菜单	yudao-module-system	全部模块通过权限摘要或用户上下文读取
文件、配置、字典、任务、API 日志	yudao-module-infra	全部模块按 Yudao 基础设施方式调用
作品、章节、Block、正文版本、MetaSchema 物理表和版本化投影	yudao-module-content；MetaSchema 逻辑 owner 是 Governance/Admin facade	knowledge、ai、market、account
用户知识库、局域知识、知识草稿、来源绑定	yudao-module-knowledge	content、ai、market
Prompt、Agent、Parse Job、Chapter Parse Result、任务、候选、质量门控、评测、Candidate Decision Archive	yudao-module-ai	content、knowledge、market、account
市场资产、授权、安装、发布、申诉、治理、来源侧 Handoff Token、授权摘要、跳转审计	yudao-module-market	content、knowledge、ai、account
权益、配额、用量、购买/授权/发布记录总览	yudao-module-account 或 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 只拥有知识来源绑定和知识投影，不拥有所有来源授权事实。

4.2 跨模块调用规则

场景	允许方式	禁止方式
查询摘要	通过 api facade、只读 query service 或事件投影读取	直接跨模块读写对方表并推断状态
写入事实	回到 owner module 的 application use case	在调用方 mapper 里直接写对方事实
异步协作	outbox event + 幂等 consumer + 可重试任务	MQ 消费端无幂等直接改 Canonical
MetaSchema 治理	/admin-api/muse/governance/** 经 Governance/Admin facade 写 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 写入只能经 Governance/Admin facade、影响预览、版本发布和审计。
• 不让 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-content
       -> yudao-module-knowledge
       -> yudao-module-ai
       -> yudao-module-market
       -> yudao-module-account/member

可以按模块边界演进到微服务，但阶段 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