# AI 中台历史基线分批治理计划

| 项目 | 内容 |
| --- | --- |
| 文档定位 | 说明 `legacy-architecture-baseline.txt` 剩余违规如何分批清理 |
| 适用范围 | `emoon-chat-api`、`emoon-knowledge-api`、`emoon-system-api`、`emoon-openplatform` |
| 当前状态 | 第一档已清理；第二档 B1-B4 的 Mapper / XML / ServiceImpl / 文件解析实现已下沉到实现模块；第三档第一批已消除 openplatform 对 system Mapper 的直连 |
| 更新时间 | 2026-05-27 |

## 1. 当前剩余基线

清理过期 MCP 路径后，剩余历史违规按业务域分布如下：

| 业务域 | 剩余数量 | 主要类型 | 当前风险判断 |
| --- | ---: | --- | --- |
| `emoon-chat-api` | 4 | Domain | Mapper、XML、ServiceImpl 已迁入 `emoon-chat`；剩余 Domain 暂作为历史契约保留 |
| `emoon-knowledge-api` | 18 | Domain / 少量接口 | Mapper、XML、ServiceImpl、文件解析与切分实现已迁入 `emoon-knowledge`；剩余 Domain/接口暂作为历史契约保留 |
| `emoon-system-api` | 33 | Domain / 少量接口 | Mapper、XML、ServiceImpl 已迁入 `emoon-system`；剩余 Domain/接口暂作为历史契约保留 |
| `emoon-openplatform` | 16 | Mapper 直连 / 入口层业务实现 | system Mapper 直连已改为 Facade；剩余主要是 MCP / openplatform 自身 Mapper 直连 |
| 其他 Controller | 3 | Controller 直连 Mapper | 可跟随对应业务域一起处理 |

## 2. 治理原则

本次治理目标不是“把文件从一个目录移动到另一个目录”。

真正目标是：

```text
API 模块只保留契约、DTO/BO/VO、枚举和轻量接口。
实现模块承载 Mapper、Mapper XML、ServiceImpl、文件解析、三方 SDK 和数据库事务。
入口模块通过 Service / Facade 调用业务能力，不直接 import Mapper。
```

每一批迁移必须满足：

```text
1. 不改数据库表结构。
2. 不改 Java package，除非该批明确包含调用方同步改造。
3. Mapper 接口和 Mapper XML 必须同批移动。
4. 移动后必须从 baseline 删除对应路径。
5. 每批至少跑 Maven 编译、架构测试和对应启动模块 package。
```

## 3. 第二档分批计划

### B1. Chat API 瘦身

目标模块：

```text
emoon-infra/emoon-modules-api/emoon-chat-api
emoon-infra/emoon-modules/emoon-chat
```

处理结果：

| 类型 | 从 | 到 |
| --- | --- | --- |
| Mapper | `emoon-chat-api/src/main/java/com/emoon/chat/mapper` | 已迁入 `emoon-chat/src/main/java/com/emoon/chat/mapper` |
| Mapper XML | `emoon-chat-api/src/main/resources/mapper/chat` | 已迁入 `emoon-chat/src/main/resources/mapper/chat` |
| ServiceImpl | `emoon-chat-api/src/main/java/com/emoon/chat/service/impl` | 已迁入 `emoon-chat/src/main/java/com/emoon/chat/service/impl` |
| 硬件信息返回对象 | 原 `HardwareInfoServiceImpl` 嵌套 DTO | 已抽为 `HardwareDataVo`，避免 API 接口反向依赖实现类 |
| DO 实体 | `emoon-chat-api/src/main/java/com/emoon/chat/domain` | 暂保留，属于历史契约，不在本轮移动 |

注意点：

```text
HardwareInfoController 已改为依赖 IHardwareInfoService + HardwareDataVo。
FileController 已改为依赖 IKnowledgeAttachService，不再直接注入 KnowledgeAttachMapper。
```

验收命令：

```bash
mvn -pl :emoon-chat -am -DskipTests compile
mvn -pl emoon-admin -DskipTests=false -Dtest=AiPlatformArchitectureTest test
```

### B2. Knowledge CRUD 瘦身

目标模块：

```text
emoon-infra/emoon-modules-api/emoon-knowledge-api
emoon-infra/emoon-modules/emoon-knowledge
```

处理结果：

| 子域 | 迁移内容 |
| --- | --- |
| 知识库基础数据 | `KnowledgeInfo`、`KnowledgeAttach`、`KnowledgeFragment` 相关 Mapper / XML / ServiceImpl 已迁入 `emoon-knowledge` |
| 模型与项目配置 | `ThinkProject`、`ThinkApi`、`ThinkModel`、`ThinkRag`、`ThinkAgent`、`ThinkAskinfo` 相关 Mapper / XML / ServiceImpl 已迁入 `emoon-knowledge` |
| 病历与质控 | `PatientRecord`、`MedicalRecordResult`、`QualityControlRule`、`QualityControlRuleExample`、`PromptTemplate` 相关 Mapper / XML / ServiceImpl 已迁入 `emoon-knowledge` |

本轮未迁移：

```text
Domain / BO / VO / Service 接口仍留在 API 模块，作为当前 Controller、openplatform 和跨模块调用的历史契约。
```

原因：

```text
本轮目标是不影响对外接口与现有跨模块编译。
Domain/BO/VO 后续如需进一步下沉，需要先抽稳定 DTO/Facade，否则会连带影响入口层返回结构和前端序列化字段。
```

验收命令：

```bash
mvn -pl :emoon-knowledge -am -DskipTests compile
mvn -pl emoon-admin -DskipTests=false -Dtest=AiPlatformArchitectureTest test
```

### B3. Knowledge 文件解析与向量链路瘦身

目标模块：

```text
emoon-infra/emoon-modules/emoon-knowledge
```

处理结果：

| 类型 | 迁移内容 |
| --- | --- |
| 文件加载 | `chain/loader/*` 已迁入 `emoon-knowledge` |
| 文本切分 | `chain/split/*` 已迁入 `emoon-knowledge` |
| 文件类型判断 | `chain/constant/*` 已迁入 `emoon-knowledge` |
| 重排与向量辅助 | `chain/xinference/*` 已迁入 `emoon-knowledge` |
| 解析服务实现 | `FileParseServiceImpl` 已迁入 `emoon-knowledge` |
| 向量服务实现 | `VectorStoreServiceImpl` 已迁入 `emoon-knowledge` |

后续建议补充验证用例：

```text
PDF 解析
Word 解析
Excel 解析
Markdown / Text 解析
知识片段入库
向量化调用失败时的降级行为
```

验收命令：

```bash
mvn -pl :emoon-knowledge -am -DskipTests compile
mvn -pl emoon-admin -DskipTests=false -Dtest=AiPlatformArchitectureTest test
```

### B4. System 核心后台瘦身

目标模块：

```text
emoon-infra/emoon-modules-api/emoon-system-api
emoon-infra/emoon-modules/emoon-system
```

处理结果：

| 子批次 | 子域 | 迁移内容 | 风险 |
| --- | --- | --- | --- |
| B4-1 | 字典 / 参数 / 通知 | `SysDict*`、`SysConfig*`、`SysNotice*` 的 Mapper / XML / ServiceImpl 已迁入 `emoon-system` | 低 |
| B4-2 | 岗位 / 部门 / 角色 / 菜单 | `SysPost*`、`SysDept*`、`SysRole*`、`SysMenu*` 的 Mapper / XML / ServiceImpl 已迁入 `emoon-system` | 中 |
| B4-3 | 租户 / 客户端 / OSS | `SysTenant*`、`SysClient*`、`SysOss*` 的 Mapper / XML / ServiceImpl 已迁入 `emoon-system` | 中 |
| B4-4 | 用户 / 登录 / 社交 / 权限 | `SysUser*`、`SysLogininfor*`、`SysSocial*`、`SysPermission*` 的 Mapper / XML / ServiceImpl 已迁入 `emoon-system` | 高 |
| B4-5 | AI 配置遗留表 | `AiAgentApp*`、`AiAgentEngineConfig*`、`AiCard*`、`AiUsageLog*` 的 Mapper / ServiceImpl 已迁入 `emoon-system` | 高，后续仍建议结合 AI 中台边界迁入 `emoon-ai-*` |

特别注意：

```text
emoon-admin 当前仍直接 import SysUserMapper，但 emoon-admin 已依赖 emoon-system，因此编译与运行不受影响。
emoon-openplatform 已不再直接 import AiAgentAppMapper / AiAgentEngineConfigMapper / AiUsageLogMapper / AiCardDefinitionMapper。
为不破坏现有开放平台功能，openplatform 仍保留 emoon-system 运行时依赖，用于装配 AiOpenPlatformFacadeImpl。
这不是最终目标，但在当前模块化单体部署方式下，直接移除实现依赖会导致 Facade Bean 缺失，存在启动风险。
```

因此 B4 本轮采用临时兼容策略：

```text
1. Mapper / XML / ServiceImpl 先从 API 下沉到 emoon-system。
2. openplatform 通过 AiOpenPlatformFacade 访问 system AI 元数据，不直接访问 Mapper。
3. openplatform 暂保留 emoon-system 运行时依赖，保证当前 Spring 扫描范围内的 Facade 实现可装配。
4. 后续如果 openplatform 要独立部署，必须先补远程 Facade Client 或内部 RPC 适配器，再移除 emoon-system 实现依赖。
```

验收命令：

```bash
mvn -pl :emoon-system -am -DskipTests compile
mvn -pl :emoon-openplatform -am -DskipTests compile
mvn -pl emoon-admin -DskipTests=false -Dtest=AiPlatformArchitectureTest test
```

## 4. 第三档专项：OpenPlatform 去 Mapper

`emoon-openplatform` 不建议归入第二档直接迁移。

原因：

```text
openplatform 是开放入口层，承担签名、鉴权、限流、SSE、外部调用协议。
它直连 Mapper 的问题应该通过应用服务或 Facade 消除，而不是把 Mapper 换一个模块继续 import。
```

涉及文件：

```text
CardRegistryImpl
AgentChatServiceImpl
ConversationServiceImpl
AskInfoServiceImpl
KnowledgeBaseServiceImpl
ModelServiceImpl
RagServiceImpl
SysProjectServiceImpl
CheckController
```

推荐顺序：

```text
1. 先为 AI 配置、卡片定义、会话、知识库、模型配置建立 Facade。
2. openplatform 改为只依赖 Facade / API。
3. 再移动 system-api / knowledge-api 中被 openplatform 直接依赖的 Mapper。
4. 最后删除 openplatform baseline。
```

### 4.1 第一批：OpenPlatform 去 System Mapper

处理结果：

| 文件 | 调整 |
| --- | --- |
| `AgentChatServiceImpl` | `AiAgentApp`、`AiAgentEngineConfig`、`AiUsageLog` 访问改为 `AiOpenPlatformFacade` |
| `ConversationServiceImpl` | 智能体与引擎配置查询改为 `AiOpenPlatformFacade` |
| `CardRegistryImpl` | 卡片定义加载改为 `AiOpenPlatformFacade`，本地 Caffeine 缓存逻辑保留 |
| `AiOpenPlatformFacade` | 新增开放平台访问 system AI 元数据的统一契约 |
| `AiOpenPlatformFacadeImpl` | 在 `emoon-system` 中统一封装 Mapper 查询、租户上下文和使用日志写入 |

运行时依赖说明：

```text
当前 OpenPlatformApplication 会扫描 com.emoon.system。
因此 emoon-openplatform 暂时保留 emoon-system 依赖，保证 AiOpenPlatformFacadeImpl 能被装配。
第一批治理目标是消灭 Mapper 直连，不是立即改部署拓扑。
后续要彻底移除 emoon-system 依赖，需要先把 Facade 实现替换为 Feign/RPC Client 或把开放平台合入统一启动器。
```

## 5. 每批完成标准

每批完成后必须做到：

```text
1. 该批迁移文件从 legacy-architecture-baseline.txt 删除。
2. AiPlatformArchitectureTest 通过。
3. 相关 Maven 模块 compile 通过。
4. 入口模块 compile 或 package 通过。
5. 如果涉及 Controller 或外部接口，补充最小 WebMvc / Service 测试。
6. 文档中记录本批处理了哪些路径、剩余哪些路径。
```

推荐优先级：

```text
B1 Chat API 瘦身
B2 Knowledge CRUD 瘦身
B3 Knowledge 文件解析与向量链路
B4-1 System 字典 / 参数 / 通知
B4-2 System 岗位 / 部门 / 角色 / 菜单
B4-3 System 租户 / 客户端 / OSS
B4-4 System 用户 / 登录 / 社交 / 权限
B4-5 System AI 配置遗留表
第三档 OpenPlatform 去 Mapper
```