API 与业务服务

API 入口

admin-api

admin-api 是后台管理入口，承载系统管理和 AI 平台 MVP 的 HTTP 接口。后台 AI 的标准链路是：

admin-api → ai-facade → ai-service

Controller 负责 HTTP、权限和参数层适配，不直接调用 AI 基础设施或 Service 实现。

app-api

app-api 面向应用端或对外场景，拥有独立的接口边界。现有 AI 普通对话和 SSE 入口属于历史/示例能力，不作为后台 AI 平台 MVP 的完成依据。

业务模块

模块	Facade	Service	主要职责
sys	sys-facade	sys-service	用户、角色、菜单、租户、部门和系统配置
ai	ai-facade	ai-service	模型配置、对话、RAG、Agent、工作流、工具
oss	oss-facade	oss-service	文件元数据、上传、下载和对象存储
learning	learning-facade	learning-service	Learning OS 学习计划、实践、成长和事件

每个业务模块采用 facade/service 拆分。Facade 暴露跨模块需要的接口和模型，Service 承载业务实现，Mapper 负责数据库访问。

新增服务的基本路径

1. 明确服务职责与不负责的范围
2. 在 facade 定义接口、DTO 与 BO/VO
3. 在 service 实现 Facade，并编排领域 Service
4. 在 API 模块添加 Controller
5. 补齐租户、安全、审计和数据库边界
6. 添加 Facade、Service 或 Controller 回归测试

模块边界检查

• Controller 不绕过 Facade 直接注入 Service 实现。
• 跨模块调用不依赖对方内部 Entity 或 Mapper。
• 请求模型使用 DTO，响应模型使用 BO 或 VO。
• 业务规则放在 Service，不堆积在 Controller 或 Mapper。
• 新增配置和数据库脚本需要在模块内保持可追踪。