---
doc_id: STD-202605-002
feature_id:
type: standard
title: AI 中台工程规约生效说明
status: approved
owner: 医梦研发团队
created_at: 2026-05-31
updated_at: 2026-05-31
reviewers: []
related_docs:
  - STD-202605-001
related_modules:
  - emoon-admin
tags:
  - 工程规约
  - 架构测试
  - PR自检
---

# AI 中台工程规约生效说明

| 项目 | 内容 |
| --- | --- |
| 文档定位 | 说明工程规约为什么存在、如何生效、违反后怎么处理 |
| 适用范围 | Maven 模块结构、二期 Agent/Card/MCP/Device/File、统一入口客户端后端能力、三期 Meter/Billing/Contract/Operation |
| 更新时间 | 2026-05-31 |

## 1. 当前生效方式

本工程规约通过四类机制生效：

| 机制 | 文件 | 生效方式 |
| --- | --- | --- |
| Maven 模块结构 | `emoon-infra/emoon-modules-api/emoon-ai-api`、`emoon-infra/emoon-modules/emoon-ai` | 新代码必须落到新 AI 分层模块中 |
| PR 自检 | `.github/pull_request_template.md` | 每个 PR 提交前由开发人员自查 |
| 任务模板 | `docs/templates/AI中台任务拆分模板.md` | 每个任务启动前先限定模块、依赖、流程和验收标准 |
| 架构边界测试 | `emoon-admin/src/test/java/com/emoon/architecture/AiPlatformArchitectureTest.java` | 测试扫描源码，拦截新增违规 |
| 历史违规基线 | `docs/architecture/legacy/历史架构违规基线.txt` | 保留当前历史包袱，不影响启动；后续只允许减少，不允许增加 |

规约采用“可验证案例 + 创业公司裁剪”的原则：参考东软智慧医院统一平台、华为/医惠智慧病房物联平台、Dify Workflow 版本能力、科大讯飞医疗 AI 辅助决策等公开实践，但只落地 AI 中台必须掌握的入口、卡片、设备场景、工具审计和计量能力，不复制大厂完整医院平台、物联网平台和重运营体系。

## 2. Maven 模块规约

### 2.1 新 AI API 聚合模块

```text
emoon-infra/emoon-modules-api/emoon-ai-api
├── emoon-ai-agent-api
├── emoon-ai-card-api
├── emoon-ai-mcp-api
├── emoon-ai-device-api
├── emoon-ai-file-api
├── emoon-ai-meter-api
├── emoon-ai-billing-api
├── emoon-ai-contract-api
└── emoon-ai-operation-api
```

原因：

```text
API 层只表达契约，避免入口层和其他模块为了拿 DTO 被迫引入实现类、Mapper、三方 SDK。
```

生效方式：

```text
Maven reactor 已纳入 emoon-modules-api。
根 pom.xml 已纳入 dependencyManagement。
架构测试会拦截 API 模块新增 Mapper / Impl / Controller / 重依赖。
```

### 2.2 新 AI 实现聚合模块

```text
emoon-infra/emoon-modules/emoon-ai
├── emoon-ai-agent
├── emoon-ai-card
├── emoon-ai-mcp
├── emoon-ai-device
├── emoon-ai-file
├── emoon-ai-meter
├── emoon-ai-billing
├── emoon-ai-contract
└── emoon-ai-operation
```

原因：

```text
二期和三期功能不能继续堆进 emoon-mcp-api 或 openplatform。
实现模块按业务闭环拆分，后续具备独立部署的边界。
```

生效方式：

```text
Maven reactor 已纳入 emoon-modules。
根 pom.xml 已纳入 dependencyManagement。
后续新增实现必须按 `docs/templates/AI中台模块骨架示例.md` 的包结构落位。
```

### 2.3 统一入口客户端工程边界

统一入口客户端后端能力仍在 AI 中台 Maven 工程中，不能新建长期维护的终端 Demo 后端：

| 能力 | 后端落位 |
| --- | --- |
| Device Registry、Scene Profile、设备事件、设备命令 | `emoon-ai-device` |
| AgentRouter、ConversationService、TaskStateService、DifyAgentEngine、DifyOutputNormalizer | `emoon-ai-agent` |
| Card Runtime、卡片实例、卡片动作状态 | `emoon-ai-card` |
| File Service、舌象/身份证/报告文件元数据 | `emoon-ai-file` |
| HisMockAdapter、RealHisAdapter、TongueDiagnosisAdapter | `emoon-ai-mcp` |

前端和移动端另起 `emoon-terminal-client` 工程，包含机器人、自助机、导诊屏等端侧应用和 `terminal-bridge`。该工程不进入后端 Maven reactor，后端只通过 OpenAPI、卡片 schema、设备命令协议和联调样例对其提供契约。

### 2.4 legacy 兼容原则

`emoon-mcp-api` 暂时保留，不立即删除。

原因：

```text
当前已有业务代码大量 import com.emoon.mcp.*。
如果一次性移动类，会影响启动、Mapper 扫描、Spring Bean 装配和线上业务验证。
```

处理方式：

```text
旧模块作为 legacy 兼容层保留。
新功能不得继续进入 emoon-mcp-api。
迁移一个历史文件后，从 legacy baseline 移除对应路径。
```

## 3. 架构规则说明

### R1. API 模块不允许新增实现类

规则：

```text
*-api 不得新增 Mapper / Impl / Controller。
```

原因：

```text
API 模块是契约，不是业务实现。实现类进入 API 后，所有调用方都会被迫依赖数据库、Spring Bean 或第三方 SDK。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描 emoon-modules-api 和 com.emoon.ai.*.api。
新增违规文件会让测试失败。
```

### R2. API 模块不允许新增重依赖

规则：

```text
API 模块不得新增 Web / MyBatis / AI SDK / PDFBox / Tika / OkHttp 等实现依赖。
```

原因：

```text
契约层应该轻量稳定。重依赖会扩大编译范围，增加循环依赖风险，并把实现细节暴露给上游。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描源码 import 和关键依赖字符串。
```

### R3. openplatform 不允许新增 Mapper 直连

规则：

```text
emoon-openplatform 新代码不得直接 import *.mapper.*。
```

原因：

```text
开放平台是入口适配层，负责鉴权、签名、限流、参数转换和 SSE 输出。
如果入口层直接操作表，Agent、Card、Meter、Billing 的边界会失效。
```

生效方式：

```text
历史 Mapper 直连已进入 baseline。
新增文件或新增路径不在 baseline 中时，测试失败。
```

### R4. Controller 不允许新增 Mapper 直连

规则：

```text
Controller 不得直接 import Mapper。
```

原因：

```text
Controller 只负责 HTTP 协议，不负责业务事务。直接访问 Mapper 会绕过应用服务、状态机、幂等、审计和计量。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描所有 /controller/ 包。
```

### R5. Card 不允许绕过 Agent 调 MCP 实现

规则：

```text
emoon-ai-card 不得依赖 emoon-ai-mcp 的 infrastructure / adapter / application。
```

原因：

```text
卡片是确定性交互状态，不是工具编排入口。
如果 Card 直接调 MCP，会出现 Agent->MCP 和 Card->MCP 两条工具调用链，权限、审计、计量都会分叉。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描 com.emoon.ai.card.*。
```

### R6. Billing 不允许反向依赖 Agent 实现

规则：

```text
emoon-ai-billing 不得依赖 emoon-ai-agent 的 application / infrastructure / adapter。
```

原因：

```text
账务只能消费计量结果和合同规则，不能反向依赖 AI 调用链。
否则会出现调用失败影响扣款、扣款失败阻塞对话、账务无法独立对账的问题。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描 com.emoon.ai.billing.*。
```

### R7. Operation 不允许依赖核心链路实现层

规则：

```text
emoon-ai-operation 不得依赖 agent/card/mcp 的 infrastructure。
```

原因：

```text
运营统计应使用事件、宽表或 API 契约，不能在核心链路业务表上做复杂联查。
否则报表查询会拖慢线上调用链。
```

生效方式：

```text
AiPlatformArchitectureTest 扫描 com.emoon.ai.operation.*。
```

## 4. 违反规约的处理方式

默认处理：

```text
不允许合并。
开发人员应把代码移动到正确模块，或通过 Facade / Event / Outbox 重建调用关系。
```

例外处理：

```text
1. 必须补 ADR，说明为什么必须违反。
2. 技术负责人确认。
3. 如果是临时兼容，必须写清楚迁移期限。
4. 更新 legacy baseline 时，只能由技术负责人操作。
```

## 5. 推荐本地验证命令

```bash
mvn -pl emoon-admin -DskipTests=false -Dtest=AiPlatformArchitectureTest test
```

如果本机 Maven 仓库缺少 surefire provider，首次运行可能需要联网下载 Maven 测试插件依赖。该架构测试本身不引入额外第三方库。