345 lines
9.2 KiB
Markdown
345 lines
9.2 KiB
Markdown
# HZHub-AI 后端项目审查报告
|
||
|
||
> 审查时间：2026-03-26
|
||
> 项目路径：/data/hzhub-ai/hzhub-ai/
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 基本信息
|
||
|
||
| 属性 | 内容 |
|
||
|------|------|
|
||
| 项目名称 | HZHub-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 整体架构
|
||
|
||
```
|
||
hzhub-ai/
|
||
├── pom.xml # 父POM，版本统一管理
|
||
├── hzhub-admin/ # 管理后台模块（Spring Boot启动类）
|
||
├── hzhub-common/ # 公共组件库（25个子模块）
|
||
│ ├── hzhub-common-core # 核心工具类
|
||
│ ├── hzhub-common-chat # AI相关公共类
|
||
│ ├── hzhub-common-satoken # Sa-Token认证
|
||
│ ├── hzhub-common-redis # Redis封装
|
||
│ ├── hzhub-common-mybatis # MyBatis Plus封装
|
||
│ └── ... # 其他公共模块
|
||
├── hzhub-extend/ # 扩展模块
|
||
└── hzhub-modules/ # 业务模块
|
||
├── ruoyi-chat/ # AI核心模块（聊天、知识库、MCP）
|
||
├── hzhub-aiflow/ # 流程编排模块
|
||
├── ruoyi-workflow/ # 工作流模块
|
||
├── ruoyi-system/ # 系统管理模块
|
||
└── ruoyi-generator/ # 代码生成器
|
||
```
|
||
|
||
### 2.2 模块依赖关系
|
||
|
||
```
|
||
hzhub-admin (启动模块)
|
||
├── hzhub-modules/* (业务模块)
|
||
│ └── hzhub-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
|
||
<!-- LangChain4j核心 -->
|
||
<langchain4j.version>1.11.0</langchain4j.version>
|
||
|
||
<!-- LangChain4j社区版（扩展模型支持） -->
|
||
<langchain4j.community.version>1.11.0-beta19</langchain4j.community.version>
|
||
|
||
<!-- 工作流图引擎 -->
|
||
<langgraph4j.version>1.5.3</langgraph4j.version>
|
||
|
||
<!-- 向量数据库 -->
|
||
<weaviate.version>1.19.6</weaviate.version>
|
||
|
||
<!-- Dify平台集成 -->
|
||
<dify.version>1.0.7</dify.version>
|
||
```
|
||
|
||
---
|
||
|
||
## 四、核心模块详解
|
||
|
||
### 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 hzhub-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
|
||
<dependency>
|
||
<groupId>com.ruoyi</groupId>
|
||
<artifactId>hzhub-common-tenant</artifactId>
|
||
</dependency>
|
||
```
|
||
|
||
---
|
||
|
||
## 七、HZHub借鉴点
|
||
|
||
### 7.1 架构设计借鉴
|
||
|
||
| 方面 | HZHub-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/ # 流程编排（复用hzhub-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. **保持HZHub-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. 复用 `hzhub-aiflow` 模块作为流程编排引擎
|
||
3. 开发 `hzhub-erp` 模块，参考SQL Agent模式
|
||
4. 整合三个模块，构建HZHub完整后端
|
||
|
||
---
|
||
|
||
**审查完成时间**：2026-03-26 08:30 UTC
|
||
**审查人**：大壮
|