emoon-backend/docs/architecture/legacy-baseline-refactor-plan.md

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. 治理原则

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

真正目标是：

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

每一批迁移必须满足：

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

3. 第二档分批计划

B1. Chat API 瘦身

目标模块：

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	暂保留，属于历史契约，不在本轮移动

注意点：

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

验收命令：

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

B2. Knowledge CRUD 瘦身

目标模块：

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

本轮未迁移：

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

原因：

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

验收命令：

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

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

目标模块：

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

后续建议补充验证用例：

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

验收命令：

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

B4. System 核心后台瘦身

目标模块：

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-*

特别注意：

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

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

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 实现依赖。

验收命令：

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 不建议归入第二档直接迁移。

原因：

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

涉及文件：

CardRegistryImpl
AgentChatServiceImpl
ConversationServiceImpl
AskInfoServiceImpl
KnowledgeBaseServiceImpl
ModelServiceImpl
RagServiceImpl
SysProjectServiceImpl
CheckController

推荐顺序：

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 查询、租户上下文和使用日志写入

运行时依赖说明：

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

5. 每批完成标准

每批完成后必须做到：

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

推荐优先级：

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