emoon-backend/docs/templates/ai-platform-module-skeleton.md

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 为例：

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 模块允许：

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

API 模块禁止：

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

2. 实现模块骨架

以 emoon-ai-agent 为例：

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. 标准调用链

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. 初级工程师判断规则

新增类前先判断：

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