emoon-backend/docs/standards/工程规约生效说明.md

---

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 聚合模块

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

原因：

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

生效方式：

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

2.2 新 AI 实现聚合模块

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

原因：

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

生效方式：

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 暂时保留，不立即删除。

原因：

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

处理方式：

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

3. 架构规则说明

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

规则：

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

原因：

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

生效方式：

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

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

规则：

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

原因：

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

生效方式：

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

R3. openplatform 不允许新增 Mapper 直连

规则：

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

原因：

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

生效方式：

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

R4. Controller 不允许新增 Mapper 直连

规则：

Controller 不得直接 import Mapper。

原因：

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

生效方式：

AiPlatformArchitectureTest 扫描所有 /controller/ 包。

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

规则：

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

原因：

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

生效方式：

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

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

规则：

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

原因：

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

生效方式：

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

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

规则：

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

原因：

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

生效方式：

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

4. 违反规约的处理方式

默认处理：

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

例外处理：

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

5. 推荐本地验证命令

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

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