系统架构

顶层模块

┌──────────────────────────────────────────────────────────────┐
│                        x-boot-cloud                           │
├────────────────┬────────────────┬────────────────┬───────────┤
│ x-boot-starters │    x-boot-api  │ x-boot-modules │ job-admin │
│ 通用基础能力    │  HTTP 入口契约 │  业务服务集合   │ XXL-Job   │
└────────────────┴────────────────┴────────────────┴───────────┘

x-boot-starters

提供核心工具、统一 Web 响应、异常处理、AOP、鉴权、Redis、限流、CRUD、Dubbo、国际化、多租户、RocketMQ、AI 和 XXL-Job 等可复用能力。

x-boot-api

• admin-api：后台管理 HTTP 入口，承载企业后台用户和 AI 平台 MVP 的接口。
• app-api：应用端或对外 HTTP 入口，保留独立的应用场景边界。

x-boot-modules

• sys：用户、角色、菜单、部门、租户、参数、字典和日志等系统能力。
• ai：模型配置、对话、知识库/RAG、Agent、工作流和工具/MCP 子域。
• oss：文件信息、上传、下载和对象存储相关能力。
• learning：Learning OS 学习领域能力。

x-boot-job-admin

基于 XXL-Job 的任务管理、调度、执行器注册和日志管理平台。

标准调用链

HTTP Controller
      │
      ▼
@DubboReference Facade
      │
      ▼
@DubboService FacadeImpl
      │
      ▼
Spring Service
      │
      ▼
Mapper / MyBatis-Plus / Database

每一层有明确职责：

层级	主要职责	不应承担的职责
Controller	参数接收、权限注解、响应包装	领域规则、直接操作 Mapper
Facade	跨模块接口契约、DTO/BO/VO	复杂业务实现
FacadeImpl	Dubbo Provider 适配、调用 Service	把所有业务规则堆在实现类
Service	业务规则、事务、领域编排	对外暴露 HTTP 细节
Mapper	数据访问与持久化	用户权限和业务流程判断

上下文与安全

用户身份、租户信息和权限不是只在 Controller 层存在的临时变量，而是需要沿服务调用链传递的业务上下文。涉及租户数据时，服务、实体、Mapper 和 SQL 都必须保持隔离规则一致。

项目当前使用 Sa-Token 处理认证与权限，后台权限以 RBAC 菜单权限码为基础。AI 平台后台接口统一从 admin-api 进入，标准链路为：

admin-api → ai-facade → ai-service → mapper → database / model provider

架构原则

• HTTP 入口放在 API 模块，业务实现放在对应 service 模块。
• 跨模块接口和模型放在 facade，不让 Controller 依赖 service 实现。
• 新增业务表默认考虑租户、审计、逻辑删除和乐观锁字段。
• 配置和密钥不写死在源码中，使用环境变量、Nacos、Vault 或 CI/CD Secret。
• 新增服务时先明确服务职责，再设计 API、Facade、Service 和 Mapper 链路。