AI_Team/hzhub

Fork 0

Files

dazhuang f115a793a7 refactor: 将 RuoYi 标记替换为 HZHub

2026-03-27 06:42:14 +00:00

9.2 KiB

Raw Blame History

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相关依赖

<!-- 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

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);
}

关键设计点：

SystemMessage：定义Agent角色和约束
工具声明：明确可用工具及其使用顺序
类型安全：通过接口定义输入输出

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 多租户支持

<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 升级建议

保持HZHub-AI版本：使用当前稳定版3.5.8
独立ERP服务：避免双数据源复杂性
逐步迁移：先复用chat模块，再扩展ERP功能

九、总结

9.1 核心收获

架构成熟：多模块设计合理，公共组件复用度高
AI能力完整：模型接入、RAG、Agent、工作流全覆盖
代码质量高：规范清晰，文档完善
扩展性强：MCP协议、流程编排支持自定义

9.2 下一步行动

复用 ruoyi-chat 模块作为 hzhub-ai 基础
复用 hzhub-aiflow 模块作为流程编排引擎
开发 hzhub-erp 模块，参考SQL Agent模式
整合三个模块，构建HZHub完整后端

审查完成时间：2026-03-26 08:30 UTC 审查人：大壮

9.2 KiB Raw Blame History Unescape Escape