# AI 中台模块骨架示例

> 本示例用于约束新模块目录和职责。后续新增 `emoon-ai-agent`、`emoon-ai-card`、`emoon-ai-mcp`、`emoon-ai-meter`、`emoon-ai-billing`、`emoon-ai-contract`、`emoon-ai-operation` 时，优先按本骨架组织代码。

## 1. API 模块骨架

以 `emoon-ai-agent-api` 为例：

```text
emoon-ai-agent-api
└── src/main/java/com/emoon/ai/agent/api
    ├── command        # 写操作入参，例如 CreateConversationCommand
    ├── query          # 查询入参，例如 ConversationQuery
    ├── dto            # 内部传输对象
    ├── vo             # 对外响应对象
    ├── event          # 跨模块事件契约
    ├── enums          # 枚举和状态
    ├── facade         # 对外 Facade 接口
    └── spi            # 可插拔能力接口，例如 AgentEngine
```

API 模块允许：

```text
DTO / VO / Command / Query / Event / Enum / Facade / SPI
```

API 模块禁止：

```text
Controller / Mapper / ServiceImpl / RepositoryImpl / EngineImpl / ClientImpl / MyBatis XML / 第三方 SDK 调用
```

## 2. 实现模块骨架

以 `emoon-ai-agent` 为例：

```text
emoon-ai-agent
└── src/main/java/com/emoon/ai/agent
    ├── application
    │   ├── facade     # emoon-ai-agent-api facade 的实现
    │   ├── service    # 用例编排服务
    │   └── assembler  # Command/DTO/DO 转换
    ├── domain
    │   ├── model      # 聚合、实体、值对象
    │   ├── policy     # 业务规则，例如引擎选择策略
    │   └── state      # 状态机
    ├── infrastructure
    │   ├── mapper     # MyBatis Mapper
    │   ├── repository # Repository 实现
    │   ├── outbox     # Outbox、事件发布、重试
    │   └── config     # 模块内部配置
    └── adapter
        ├── dify       # Dify 客户端适配
        ├── directllm  # 直连模型适配
        ├── mcp        # MCP 出站适配
        └── sse        # SSE 事件转换
```

## 3. 标准调用链

```mermaid
flowchart LR
    Controller["Controller / OpenPlatform"]
    Facade["Facade API"]
    App["Application Service"]
    Domain["Domain Model / Policy"]
    Repo["Repository / Mapper"]
    Adapter["External Adapter"]
    Event["Outbox / Domain Event"]

    Controller --> Facade
    Facade --> App
    App --> Domain
    App --> Repo
    App --> Adapter
    App --> Event
```

## 4. 各模块特殊要求

| 模块 | 必须包含 | 禁止包含 |
| --- | --- | --- |
| `emoon-ai-agent` | 引擎选择、会话上下文、调用编排、用量事件生产 | 直接扣款、报表聚合、卡片渲染细节 |
| `emoon-ai-card` | 卡片定义、实例、动作、状态机、幂等 | 直接调用 MCP 工具、直接调用 LLM |
| `emoon-ai-mcp` | 工具注册、权限、限流、审计、工具调用 | Agent 流程编排、卡片状态机 |
| `emoon-ai-meter` | 计量事件、状态机、去重、重放 | 余额扣减、合同维护 |
| `emoon-ai-billing` | 账户、冻结、扣减、退款、冲正、账单 | AI 调用编排、统计报表 |
| `emoon-ai-contract` | 合同、套餐、能力包、价格策略 | 用户权限基础数据、Agent 调用逻辑 |
| `emoon-ai-operation` | 统计宽表、运营报表、异常分析 | 核心链路同步复杂联查 |

## 5. 新增类命名建议

| 类型 | 命名 |
| --- | --- |
| Facade 接口 | `XxxFacade` |
| Facade 实现 | `XxxFacadeImpl` |
| 应用服务 | `XxxApplicationService` |
| 领域策略 | `XxxPolicy` |
| 状态机 | `XxxStateMachine` |
| Repository 接口 | `XxxRepository` |
| Repository 实现 | `XxxRepositoryImpl` |
| MyBatis Mapper | `XxxMapper` |
| 第三方适配器 | `XxxClient` / `XxxAdapter` |
| 领域事件 | `XxxEvent` |
| 命令对象 | `XxxCommand` |
| 查询对象 | `XxxQuery` |

## 6. 初级工程师判断规则

新增类前先判断：

```text
只是定义输入输出？放 api。
需要操作数据库？放 infrastructure。
需要编排一个用例？放 application。
表达业务规则？放 domain。
调用外部系统？放 adapter 或 infrastructure。
给 Controller 调用？先定义 facade。
```