# RuoYi-AI 后端项目审查报告
> 审查时间：2026-03-26
> 项目路径：/data/ruoyi-ai/ruoyi-ai/
---
## 一、项目概述
### 1.1 基本信息
| 属性 | 内容 |
|------|------|
| 项目名称 | RuoYi-AI |
| 定位 | 企业级AI助手平台 |
| 版本 | 3.0.0 |
| 技术栈 | Spring Boot 3.5.8 + Spring AI + LangChain4j |
| Java版本 | JDK 17 |
### 1.2 核心能力
- **多模型接入**：OpenAI、DeepSeek、通义、智谱等
- **多模态理解**：文本、图像、文档解析
- **RAG知识库**：Milvus/Weaviate向量库支持
- **MCP工具生态**：标准化工具协议集成
- **流程编排**：可视化工作流设计器
- **多智能体**：基于LangChain4j的Agent框架
---
## 二、项目结构分析
### 2.1 整体架构
```
ruoyi-ai/
├── pom.xml # 父POM，版本统一管理
├── ruoyi-admin/ # 管理后台模块（Spring Boot启动类）
├── ruoyi-common/ # 公共组件库（25个子模块）
│ ├── ruoyi-common-core # 核心工具类
│ ├── ruoyi-common-chat # AI相关公共类
│ ├── ruoyi-common-satoken # Sa-Token认证
│ ├── ruoyi-common-redis # Redis封装
│ ├── ruoyi-common-mybatis # MyBatis Plus封装
│ └── ... # 其他公共模块
├── ruoyi-extend/ # 扩展模块
└── ruoyi-modules/ # 业务模块
├── ruoyi-chat/ # AI核心模块（聊天、知识库、MCP）
├── ruoyi-aiflow/ # 流程编排模块
├── ruoyi-workflow/ # 工作流模块
├── ruoyi-system/ # 系统管理模块
└── ruoyi-generator/ # 代码生成器
```
### 2.2 模块依赖关系
```
ruoyi-admin (启动模块)
├── ruoyi-modules/* (业务模块)
│ └── ruoyi-common/* (公共组件)
```
**设计特点**：
- 采用 Maven 多模块架构
- 父 POM 统一管理依赖版本
- 公共组件高度复用
- 业务模块独立可插拔
---
## 三、关键技术栈分析
### 3.1 核心框架版本
| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 3.5.8 | 应用框架 |
| Spring AI | 2.0+ | AI抽象层 |
| LangChain4j | 1.11.0 | LLM开发框架 |
| LangGraph4j | 1.5.3 | 工作流引擎 |
| MyBatis Plus | 3.5.14 | ORM框架 |
| Sa-Token | 1.44.0 | 认证授权 |
| Redisson | 3.51.0 | Redis客户端 |
### 3.2 AI相关依赖
```xml
1.11.0
1.11.0-beta19
1.5.3
1.19.6
1.0.7
```
---
## 四、核心模块详解
### 4.1 ruoyi-chat 模块（AI核心）
#### 4.1.1 功能架构
```
ruoyi-chat/
├── controller/
│ ├── chat/ # 聊天会话管理
│ ├── knowledge/ # 知识库管理
│ └── mcp/ # MCP工具管理
├── agent/ # 智能体实现
│ ├── SqlAgent.java # SQL数据库Agent
│ ├── WebSearchAgent.java # 网页搜索Agent
│ └── tool/ # Agent工具集
├── service/ # 业务服务层
└── enums/ # 枚举定义
```
#### 4.1.2 SQL Agent实现分析
**设计模式**：基于 LangChain4j 的声明式 Agent
```java
public interface SqlAgent extends Agent {
@SystemMessage("""
This agent is designed for MySQL 5.7
You are an intelligent database query assistant...
CRITICAL REQUIREMENT:
- You MUST ALWAYS use queryAllTables first
- Only after understanding the database schema can you...
""")
@UserMessage("Answer the following question: {{query}}")
@Agent("Intelligent database query assistant...")
String getData(@V("query") String query);
}
```
**关键设计点**：
1. **SystemMessage**：定义Agent角色和约束
2. **工具声明**：明确可用工具及其使用顺序
3. **类型安全**：通过接口定义输入输出
### 4.2 ruoyi-aiflow 模块（流程编排）
#### 4.2.1 架构设计
基于 **LangGraph4j** 的状态图执行引擎：
```
工作流定义 (t_workflow)
↓
工作流节点 (t_workflow_node)
↓
工作流边 (t_workflow_edge)
↓
图构建器 (WorkflowGraphBuilder)
↓
状态图 (StateGraph)
↓
执行引擎 (WorkflowEngine)
```
#### 4.2.2 节点类型
| 类型 | 节点 | 功能 |
|------|------|------|
| 基础 | Start/End | 工作流入口/出口 |
| AI | Answer | 大模型问答 |
| AI | Dalle3/Tongyiwanx | 图像生成 |
| 数据处理 | KnowledgeRetrieval | 知识库检索 |
| 控制流 | Switcher | 条件分支 |
| 交互 | HumanFeedback | 人机交互 |
| 集成 | HttpRequest/MailSend | 外部调用 |
#### 4.2.3 流式响应机制
**SSE事件类型**：
- `NODE_RUN_节点UUID`：节点执行开始
- `NODE_INPUT_节点UUID`：节点输入数据
- `NODE_OUTPUT_节点UUID`：节点输出数据
- `NODE_CHUNK_节点UUID`：流式内容块
- `NODE_WAIT_FEEDBACK_BY_节点UUID`：等待用户输入
### 4.3 MCP工具模块
#### 4.3.1 架构设计
**MCP（Model Context Protocol）**：标准化工具协议
```
MCP工具类型：
├── LOCAL # 本地工具
├── REMOTE # 远程HTTP工具
└── BUILTIN # 内置工具
```
#### 4.3.2 API设计
**核心接口**：
- `GET /api/mcp/tool/list`：工具列表
- `POST /api/mcp/tool/{id}/test`：连接测试
- `GET /api/mcp/market/{marketId}/tools`：市场工具
- `POST /api/mcp/market/tool/{toolId}/load`：加载工具
---
## 五、数据库设计分析
### 5.1 核心表结构
| 表名 | 用途 |
|------|------|
| t_chat_session | 聊天会话 |
| t_chat_message | 聊天消息 |
| t_knowledge_info | 知识库信息 |
| t_knowledge_fragment | 知识库片段（向量存储）|
| t_mcp_tool | MCP工具定义 |
| t_workflow | 工作流定义 |
| t_workflow_node | 工作流节点 |
| t_workflow_edge | 工作流边 |
| t_workflow_runtime | 工作流运行时 |
### 5.2 知识库RAG设计
**文档处理流程**：
```
文档上传 → 格式解析 → 文本分割 → 向量化 → Milvus存储
```
**检索流程**：
```
用户查询 → 向量化 → 向量检索 → 重排序 → 上下文构建 → LLM生成
```
---
## 六、安全设计
### 6.1 认证授权
- **Sa-Token**：轻量级权限认证框架
- **JWT**：Token令牌机制
- **双重保障**：Sa-Token + JWT 组合
### 6.2 多租户支持
```xml
com.ruoyi
ruoyi-common-tenant
```
---
## 七、HZHub借鉴点
### 7.1 架构设计借鉴
| 方面 | RuoYi-AI实践 | HZHub应用 |
|------|-------------|-----------|
| 模块化 | 25个common子模块 | 提取ERP适配公共组件 |
| 多模块 | modules独立部署 | AI/ERP/Gateway分离 |
| 版本管理 | 父POM统一管理 | 统一Spring Boot 4.0版本 |
| Agent框架 | LangChain4j声明式 | ERP智能助手Agent |
### 7.2 功能复用建议
**可直接复用**：
- 多模型接入配置（OpenAI/DeepSeek/通义）
- 知识库RAG实现（Milvus向量检索）
- MCP工具框架（标准化工具协议）
- 流程编排引擎（LangGraph4j）
**需要改造**：
- SQL Agent：从MySQL适配到SQL Server 2008 R2
- 工作流节点：增加ERP业务节点
- 知识库：增加ERP文档类型支持
### 7.3 代码组织借鉴
```
推荐HZHub模块结构：
hzhub-ai/
├── common/ # 公共组件
│ ├── hzhub-common-core
│ ├── hzhub-common-erp # ERP连接公共类
│ └── hzhub-common-chat # AI公共类
├── modules/
│ ├── hzhub-chat/ # AI聊天（复用ruoyi-chat）
│ ├── hzhub-erp/ # ERP服务（新增）
│ └── hzhub-aiflow/ # 流程编排（复用ruoyi-aiflow）
└── hzhub-admin/ # 启动模块
```
---
## 八、技术风险与建议
### 8.1 已知风险
| 风险 | 说明 | 建议 |
|------|------|------|
| Spring Boot版本 | 实际3.5.8，非4.0 | 升级至4.0需测试兼容性 |
| LangChain4j版本 | 1.11.0较新 | 关注API稳定性 |
| SQL Server支持 | 原生支持MySQL | ERP服务需自定义JDBC |
### 8.2 升级建议
1. **保持RuoYi-AI版本**：使用当前稳定版3.5.8
2. **独立ERP服务**：避免双数据源复杂性
3. **逐步迁移**：先复用chat模块，再扩展ERP功能
---
## 九、总结
### 9.1 核心收获
1. **架构成熟**：多模块设计合理，公共组件复用度高
2. **AI能力完整**：模型接入、RAG、Agent、工作流全覆盖
3. **代码质量高**：规范清晰，文档完善
4. **扩展性强**：MCP协议、流程编排支持自定义
### 9.2 下一步行动
1. 复用 `ruoyi-chat` 模块作为 `hzhub-ai` 基础
2. 复用 `ruoyi-aiflow` 模块作为流程编排引擎
3. 开发 `hzhub-erp` 模块，参考SQL Agent模式
4. 整合三个模块，构建HZHub完整后端
---
**审查完成时间**：2026-03-26 08:30 UTC
**审查人**：大壮