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

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

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

## 1. 工程基线

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

```text
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）。

包结构建议：

```text
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 风格组织：

```text
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 只做参数校验、权限入口和响应转换，不直接拼业务规则。

示例：

```text
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（任务编排、候选生成、质量门控、上下文组装）。为防止职责混淆和越权调用，必须在包级别做隔离：

```text
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 规则：

```java
// 禁止 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 投影 |
| 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` 模块结构：

```text
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 聚合启动形态：

```text
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`