# 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
**审查人**：大壮
