AI_Team/hzhub
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Initial commit: HZHub project setup with RuoYi-AI base

Browse Source
This commit is contained in:
大壮
2026-03-26 09:47:46 +00:00
commit 3584e491cc
5005 changed files with 318595 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
docs/learnings/01-ruoyi-ai-backend-review.md Normal file
View File

@@ -0,0 +1,344 @@
# 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
<!-- 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 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
<dependency>
<groupId>com.ruoyi</groupId>
<artifactId>ruoyi-common-tenant</artifactId>
</dependency>
```
---
## 七、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
**审查人**：大壮

370
docs/learnings/02-ruoyi-admin-frontend-review.md Normal file
View File

@@ -0,0 +1,370 @@
# RuoYi-Admin 管理后台审查报告
> 审查时间：2026-03-26
> 项目路径：/data/ruoyi-ai/ruoyi-admin/
---
## 一、项目概述
### 1.1 基本信息
| 属性 | 内容 |
|------|------|
| 项目名称 | RuoYi-AI Admin |
| 定位 | 企业级AI助手平台 - 管理后台 |
| 技术栈 | Vue 3 + Vben Admin + Ant Design Vue |
| 构建工具 | Vite + pnpm + Turbo |
| 包管理 | pnpm workspace (monorepo) |
### 1.2 核心功能
- **系统管理**：用户、角色、菜单、部门、岗位、字典
- **AI配置**：模型管理、知识库管理、流程编排
- **MCP工具**：工具管理、市场管理
- **工作流**：流程设计、审批管理
- **监控运维**：在线用户、操作日志、登录日志
---
## 二、项目结构分析
### 2.1 Monorepo架构
```
ruoyi-admin/ # 根目录
├── apps/ # 应用目录
│ └── web-antd/ # Ant Design Vue版本（主应用）
├── packages/ # 共享包目录
│ ├── @core/ # 核心功能包
│ ├── effects/ # 副作用包（请求、权限等）
│ ├── icons/ # 图标库
│ ├── locales/ # 国际化
│ ├── preferences/ # 偏好设置
│ ├── stores/ # Pinia状态管理
│ ├── styles/ # 样式系统
│ ├── types/ # TypeScript类型
│ └── utils/ # 工具函数
├── internal/ # 内部工具
├── package.json # 根package.json
├── pnpm-workspace.yaml # pnpm工作区配置
└── turbo.json # Turbo构建配置
```
### 2.2 主应用结构
```
apps/web-antd/
├── src/
│ ├── api/ # API接口定义
│ ├── assets/ # 静态资源
│ ├── components/ # 业务组件
│ ├── composables/ # Vue组合式函数
│ ├── layouts/ # 布局组件
│ ├── router/ # 路由配置
│ ├── stores/ # 状态管理
│ ├── styles/ # 样式文件
│ ├── views/ # 页面视图
│ │ ├── aiflow/ # AI流程编排
│ │ ├── chat/ # AI聊天管理
│ │ │ ├── message/ # 消息管理
│ │ │ ├── model/ # 模型管理
│ │ │ └── provider/ # 提供商管理
│ │ ├── knowledge/ # 知识库管理
│ │ │ ├── attach/ # 附件管理
│ │ │ ├── fragment/ # 片段管理
│ │ │ └── info/ # 知识库信息
│ │ ├── mcp/ # MCP工具管理
│ │ │ ├── market/ # MCP市场
│ │ │ └── tool/ # MCP工具
│ │ ├── nodeManage/ # 节点管理
│ │ ├── system/ # 系统管理
│ │ ├── workflow/ # 工作流管理
│ │ └── ...
│ ├── App.vue
│ └── main.ts
├── package.json
├── vite.config.mts
└── ...
```
---
## 三、技术栈详解
### 3.1 核心框架
| 技术 | 版本/说明 | 用途 |
|------|----------|------|
| Vue | 3.x | 前端框架 |
| TypeScript | 5.x | 类型系统 |
| Vite | 6.x | 构建工具 |
| pnpm | 10.x | 包管理器 |
| Turbo | latest | 构建加速 |
### 3.2 UI组件库
| 组件库 | 说明 |
|--------|------|
| Ant Design Vue | 主UI组件库 |
| @vue-flow/core | 流程图/节点编辑器 |
| @antv/g6 | 图可视化 |
| echarts | 图表库 |
| tinymce | 富文本编辑器 |
### 3.3 状态与请求
| 库 | 用途 |
|----|------|
| Pinia | 状态管理 |
| Vue Router | 路由管理 |
| Axios | HTTP请求（封装在@vben/request）|
### 3.4 Vben生态
```
@vben/* 命名空间下的包：
├── @vben/access # 权限控制
├── @vben/common-ui # 通用UI组件
├── @vben/constants # 常量定义
├── @vben/hooks # Vue hooks
├── @vben/icons # 图标
├── @vben/layouts # 布局组件
├── @vben/locales # 国际化
├── @vben/plugins # 插件
├── @vben/preferences # 偏好设置
├── @vben/request # 请求封装
├── @vben/stores # 状态管理
├── @vben/styles # 样式
├── @vben/types # 类型定义
└── @vben/utils # 工具函数
```
---
## 四、核心功能实现分析
### 4.1 流程编排设计器 (aiflow)
**技术栈**：@vue-flow/core + 自定义节点
**核心组件**：
- `workflow-designer.vue`：流程设计器主组件
- `workflow-modal.vue`：工作流编辑弹窗
- 节点类型组件：Answer、Switcher、HumanFeedback等
**数据流**：
```
工作流定义 → 节点配置 → 边连接 → 保存到后端
↑ ↓
渲染展示 ← 图引擎构建 ← JSON解析
```
### 4.2 知识库管理 (knowledge)
**功能模块**：
- 知识库信息管理（info）
- 文档附件管理（attach）
- 知识片段管理（fragment）
**核心功能**：
- 文档上传（支持PDF、Word、Excel）
- 分段策略配置
- 向量化处理状态跟踪
### 4.3 MCP工具管理 (mcp)
**功能模块**：
- MCP工具列表（tool）
- MCP市场（market）
**核心功能**：
- 本地/远程/内置工具管理
- 工具连接测试
- 市场工具导入
### 4.4 AI聊天管理 (chat)
**功能模块**：
- 模型提供商管理（provider）
- 模型配置管理（model）
- 消息记录管理（message）
---
## 五、代码组织与规范
### 5.1 目录命名规范
```
views/ # 页面视图
├── [module]/ # 模块名（小写）
│ ├── index.vue # 列表页
│ ├── [page]/ # 子页面
│ │ └── index.vue
│ ├── data.ts # 表格/表单配置
│ └── [component].vue # 业务组件
```
### 5.2 API组织
```
api/
├── aiflow.ts # 流程编排API
├── chat.ts # 聊天API
├── knowledge.ts # 知识库API
├── mcp.ts # MCP工具API
├── system.ts # 系统管理API
└── ...
```
### 5.3 组件封装模式
**列表页标准结构**：
```vue
<script setup lang="ts">
// 1. 导入依赖
import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { workflowApi } from '#/api/aiflow';
// 2. 表格配置
const gridOptions: VxeGridProps = {
columns,
proxyConfig: {
ajax: {
query: async ({ page }, formValues) => {
const result = await workflowApi.workflowPage({...});
return { rows: result.records, total: result.total };
},
},
},
};
// 3. 使用封装组件
const [BasicTable, tableApi] = useVbenVxeGrid({
formOptions,
gridOptions,
});
</script>
```
---
## 六、HZHub借鉴点
### 6.1 架构设计借鉴
| 方面 | RuoYi-Admin实践 | HZHub应用 |
|------|-----------------|-----------|
| Monorepo | pnpm workspace + Turbo | hzhub-admin采用同样结构 |
| 组件封装 | useVbenVxeGrid通用表格 | 复用或参考实现ERP表格 |
| 权限控制 | @vben/access权限库 | 复用权限系统 |
| 状态管理 | Pinia + Stores分层 | 复用状态管理方案 |
| 请求封装 | @vben/request Axios封装 | 复用请求层 |
### 6.2 功能复用建议
**可直接复用**：
- 系统管理模块（用户、角色、菜单、部门）
- 权限控制组件
- 通用表格/表单组件
- 布局系统
**需要改造**：
- AI管理模块 → 改为ERP管理模块
- 流程编排 → 改为业务流程编排
- 知识库 → 改为ERP文档库
### 6.3 hzhub-admin推荐结构
```
hzhub-admin/
├── apps/
│ └── web/ # 主应用
├── packages/
│ ├── @core/ # 核心（复用vben）
│ ├── effects/ # 副作用（复用vben）
│ └── ...
└── ...
apps/web/src/views/
├── erp/ # ERP管理（新增）
│ ├── table/ # 表管理
│ ├── procedure/ # 存储过程管理
│ └── config/ # ERP配置
├── system/ # 系统管理（复用）
├── ai/ # AI管理（复用ruoyi）
└── ...
```
---
## 七、开发环境配置
### 7.1 环境变量
```
.env.development # 开发环境
.env.production # 生产环境
关键配置：
- VITE_API_URL：后端API地址
- VITE_APP_TITLE：应用标题
```
### 7.2 启动命令
```bash
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 生产构建
pnpm build:prod
# 类型检查
pnpm check:type
```
---
## 八、技术风险与建议
### 8.1 已知风险
| 风险 | 说明 | 建议 |
|------|------|------|
| pnpm版本 | 要求>=9.12.0 | 统一开发环境 |
| Node版本 | 要求>=20.10.0 | 使用nvm管理 |
| 组件库版本 | Ant Design Vue版本锁定 | 注意兼容性 |
### 8.2 集成建议
1. **复用Vben生态**：直接使用@vben/*包，减少重复开发
2. **渐进式迁移**：先复用系统管理，再扩展ERP功能
3. **保持结构一致**：遵循ruoyi-admin的目录规范
---
## 九、总结
### 9.1 核心收获
1. **架构先进**：Monorepo + pnpm + Turbo，适合大型项目
2. **组件丰富**：Vben生态提供完整的后台管理组件
3. **AI功能完整**：流程编排、知识库、MCP工具管理齐全
4. **代码规范**：目录结构清晰，组件封装模式统一
### 9.2 下一步行动
1. 复用 `ruoyi-admin` 作为 `hzhub-admin` 基础
2. 保留系统管理、权限控制等通用功能
3. 改造AI管理模块为ERP管理模块
4. 复用流程编排设计器，增加ERP业务节点
---
**审查完成时间**：2026-03-26 08:45 UTC
**审查人**：大壮

390
docs/learnings/03-ruoyi-web-user-frontend-review.md Normal file
View File

@@ -0,0 +1,390 @@
# RuoYi-Web 用户前端审查报告
> 审查时间：2026-03-26
> 项目路径：/data/ruoyi-ai/ruoyi-web/
---
## 一、项目概述
### 1.1 基本信息
| 属性 | 内容 |
|------|------|
| 项目名称 | RuoYi-Web |
| 定位 | 企业级AI助手平台 - 用户前端 |
| 技术栈 | Vue 3 + TypeScript + Element Plus X |
| 构建工具 | Vite 6.x |
| 包管理 | pnpm |
### 1.2 核心功能
- **AI对话**：多模型聊天、流式响应
- **知识库问答**：RAG检索、文档对话
- **工作流执行**：可视化流程运行
- **智能体交互**：Agent工具调用
- **多模态**：文本、图片、文件上传
---
## 二、项目结构分析
### 2.1 整体架构
```
ruoyi-web/
├── src/
│ ├── api/ # API接口定义
│ ├── assets/ # 静态资源
│ ├── components/ # 业务组件
│ │ ├── ModelSelect/ # 模型选择器
│ │ ├── FilesSelect/ # 文件选择器
│ │ ├── DeepThinking/ # 深度思考组件
│ │ ├── LoginDialog/ # 登录弹窗
│ │ └── ...
│ ├── config/ # 配置文件
│ ├── constants/ # 常量定义
│ ├── hooks/ # Vue组合式函数
│ ├── layouts/ # 布局组件
│ │ ├── LayoutVertical/ # 垂直布局
│ │ └── LayoutMobile/ # 移动端布局
│ ├── pages/ # 页面视图
│ │ └── chat/ # 聊天页面
│ │ ├── index.vue # 入口
│ │ └── layouts/ # 聊天布局
│ │ ├── chatDefaul/ # 默认聊天
│ │ └── chatWithId/ # 指定会话聊天
│ ├── routers/ # 路由配置
│ ├── stores/ # Pinia状态管理
│ │ ├── modules/ # 状态模块
│ │ │ ├── chat.ts # 聊天状态
│ │ │ ├── model.ts # 模型状态
│ │ │ ├── session.ts # 会话状态
│ │ │ └── files.ts # 文件状态
│ │ └── index.ts
│ ├── styles/ # 样式文件
│ ├── utils/ # 工具函数
│ ├── App.vue
│ └── main.ts
├── package.json
├── vite.config.mts
├── uno.config.ts # UnoCSS配置
└── ...
```
### 2.2 与Admin的差异
| 方面 | ruoyi-admin | ruoyi-web |
|------|-------------|-----------|
| 架构 | Monorepo (多包) | Single Repo (单包) |
| UI库 | Ant Design Vue | Element Plus X |
| 样式 | Tailwind CSS | UnoCSS |
| 目标用户 | 管理员 | 普通用户 |
| 功能侧重 | 配置管理 | AI交互体验 |
---
## 三、技术栈详解
### 3.1 核心框架
| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.5.17 | 前端框架 |
| TypeScript | 5.8.3 | 类型系统 |
| Vite | 6.0.0 | 构建工具 |
| pnpm | latest | 包管理 |
### 3.2 UI组件库
| 组件库 | 说明 |
|--------|------|
| Element Plus | 基础UI组件 |
| vue-element-plus-x | Element Plus扩展组件（Sender等） |
| @element-plus/icons-vue | 图标库 |
### 3.3 状态与请求
| 库 | 用途 |
|----|------|
| Pinia | 状态管理 |
| pinia-plugin-persistedstate | 状态持久化 |
| vue-router | 路由管理 |
| hook-fetch | HTTP请求封装 |
### 3.4 样式方案
| 技术 | 说明 |
|------|------|
| UnoCSS | 原子化CSS引擎 |
| sass-embedded | SCSS预处理器 |
---
## 四、核心功能实现分析
### 4.1 聊天组件架构
**核心组件**：vue-element-plus-x 的 Sender 组件
```
聊天页面 (pages/chat/index.vue)
↓
├── 默认聊天 (chatDefaul/index.vue)
│ └── Sender组件 + 欢迎页
└── 会话聊天 (chatWithId/index.vue)
└── Sender组件 + 消息列表
```
**Sender组件功能**：
- 多行文本输入
- 文件上传（图片、文档）
- 快捷操作（知识库选择、工作流选择）
- 发送按钮
### 4.2 模型选择器 (ModelSelect)
**功能**：
- 下拉选择AI模型
- 模型列表动态加载
- 默认模型自动设置
**实现**：
```vue
<script setup>
const modelStore = useModelStore();
onMounted(async () => {
await modelStore.requestModelList();
// 设置默认模型
if (modelStore.modelList.length > 0) {
modelStore.setCurrentModelInfo(modelStore.modelList[0]);
}
});
</script>
```
### 4.3 文件选择器 (FilesSelect)
**功能**：
- 支持多文件上传
- 文件类型限制
- 上传进度显示
- 文件预览
### 4.4 深度思考组件 (DeepThinking)
**功能**：
- 显示AI思考过程
- 流式内容展示
- 可折叠/展开
### 4.5 状态管理设计
**模块划分**：
```typescript
// stores/modules/chat.ts
export const useChatStore = defineStore('chat', {
state: () => ({
messages: [], // 消息列表
isLoading: false, // 加载状态
error: null, // 错误信息
}),
actions: {
async sendMessage(content) { ... },
async streamResponse(sessionId) { ... },
},
});
// stores/modules/session.ts
export const useSessionStore = defineStore('session', {
state: () => ({
sessions: [], // 会话列表
currentSession: null,
}),
actions: {
async createSession() { ... },
async loadHistory(sessionId) { ... },
},
});
```
---
## 五、AI交互设计
### 5.1 流式响应处理
```typescript
// 使用EventSource接收SSE流
const eventSource = new EventSource(`/api/chat/stream?sessionId=${id}`);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
// 处理流式内容
chatStore.appendMessage(data);
};
```
### 5.2 工作流执行
**流程**：
1. 选择工作流
2. 输入参数
3. 执行工作流
4. 接收流式结果
**代码示例**：
```vue
<script setup>
const workFlowRunner = ref({
uuid: '',
inputs: [],
});
async function runWorkflow() {
const response = await fetch('/api/workflow/run', {
method: 'POST',
body: JSON.stringify(workFlowRunner.value),
});
// 处理流式响应
}
</script>
```
### 5.3 知识库选择
**功能**：
- 弹窗选择知识库
- 多知识库支持
- 知识库搜索
---
## 六、HZHub借鉴点
### 6.1 架构设计借鉴
| 方面 | RuoYi-Web实践 | HZHub应用 |
|------|---------------|-----------|
| 单包架构 | 简单清晰，适合用户端 | hzhub-portal采用同样结构 |
| 组件封装 | ModelSelect、FilesSelect等 | 复用或参考实现ERP组件 |
| 状态管理 | Pinia模块化 | 复用状态管理方案 |
| 流式响应 | EventSource + SSE | 复用AI聊天流式处理 |
### 6.2 功能复用建议
**可直接复用**：
- 模型选择器组件
- 文件上传组件
- 流式响应处理逻辑
- 登录弹窗组件
**需要改造**：
- AI聊天 → ERP智能助手对话
- 知识库选择 → ERP文档选择
- 工作流执行 → ERP业务流程执行
### 6.3 hzhub-portal推荐结构
```
hzhub-portal-company/ # 公司门户
├── src/
│ ├── components/
│ │ ├── ErpQueryBuilder/ # ERP查询构建器
│ │ ├── DocSelector/ # 文档选择器
│ │ └── AiChatEmbed/ # AI聊天嵌入组件
│ ├── pages/
│ │ ├── dashboard/ # 工作台
│ │ ├── approval/ # 审批流程
│ │ ├── crm/ # 销售CRM
│ │ └── ai/ # AI助手
│ └── stores/
│ └── modules/
│ ├── erp.ts # ERP状态
│ └── ai.ts # AI状态
hzhub-portal-dealer/ # 经销商门户
├── src/
│ ├── components/
│ │ ├── OrderForm/ # 开单表单
│ │ ├── InventoryQuery/ # 库存查询
│ │ └── AiMaterialGen/ # AI素材生成
│ └── pages/
│ ├── order/ # 自助开单
│ ├── inventory/ # 进销存
│ └── material/ # 营销素材
```
---
## 七、开发环境配置
### 7.1 环境变量
```
.env.development
.env.production
关键配置：
- VITE_API_BASE_URL：后端API地址
```
### 7.2 启动命令
```bash
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 生产构建
pnpm build
# 代码检查
pnpm lint
```
---
## 八、技术风险与建议
### 8.1 已知风险
| 风险 | 说明 | 建议 |
|------|------|------|
| Element Plus X版本 | vue-element-plus-x 1.3.0较新 | 关注API稳定性 |
| UnoCSS配置 | 与Tailwind CSS不同 | 团队需要学习成本 |
| 单包架构 | 代码量大时维护困难 | 考虑后期拆分为monorepo |
### 8.2 集成建议
1. **复用组件**：直接复用ModelSelect、FilesSelect等组件
2. **改造聊天**：将AI聊天改为ERP智能助手对话
3. **统一风格**：保持与公司门户UI风格一致
4. **状态隔离**：公司门户和经销商门户状态独立
---
## 九、总结
### 9.1 核心收获
1. **架构简洁**：单包架构，适合用户端快速开发
2. **组件丰富**：vue-element-plus-x提供AI交互专用组件
3. **流式处理成熟**：SSE流式响应处理完善
4. **状态管理清晰**：Pinia模块化，易于维护
### 9.2 下一步行动
1. 复用 `ruoyi-web` 的组件和模式
2. 改造AI聊天为ERP智能助手对话
3. 开发公司门户和经销商门户
4. 集成AI能力到业务流程中
---
**审查完成时间**：2026-03-26 09:00 UTC
**审查人**：大壮

344
docs/learnings/04-summary-analysis.md Normal file
View File

@@ -0,0 +1,344 @@
# RuoYi-AI 三项目综合分析报告
> 分析时间：2026-03-26
> 分析对象：ruoyi-ai（后端）、ruoyi-admin（管理后台）、ruoyi-web（用户前端）
---
## 一、整体架构总览
### 1.1 三项目关系图
```
┌─────────────────────────────────────────────────────────────────┐
│ RuoYi-AI 生态系统 │
├─────────────────┬─────────────────┬─────────────────────────────┤
│ ruoyi-web │ ruoyi-admin │ ruoyi-ai │
│ (用户前端) │ (管理后台) │ (后端服务) │
├─────────────────┼─────────────────┼─────────────────────────────┤
│ · AI对话界面 │ · 系统管理 │ · 多模型接入 │
│ · 知识库问答 │ · 模型配置 │ · RAG知识库 │
│ · 工作流执行 │ · 知识库管理 │ · MCP工具框架 │
│ · 智能体交互 │ · 流程编排设计 │ · 流程编排引擎 │
│ │ · MCP工具管理 │ · 多智能体框架 │
│ │ · 工作流管理 │ · 企业微信SDK │
└─────────────────┴─────────────────┴─────────────────────────────┘
│ │ │
└────────────────┴────────────────────┘
│
┌─────────┴─────────┐
│ 数据存储层 │
│ MySQL + Milvus │
└───────────────────┘
```
### 1.2 技术栈对比
| 层级 | ruoyi-web | ruoyi-admin | ruoyi-ai |
|------|-----------|-------------|----------|
| **框架** | Vue 3 | Vue 3 | Spring Boot 3.5.8 |
| **UI库** | Element Plus X | Ant Design Vue | - |
| **样式** | UnoCSS | Tailwind CSS | - |
| **状态** | Pinia | Pinia | - |
| **请求** | hook-fetch | @vben/request | Spring AI |
| **AI** | SSE流式 | 流程设计器 | LangChain4j |
| **构建** | Vite | Vite + Turbo | Maven |
| **架构** | Single Repo | Monorepo | 多模块Maven |
---
## 二、各项目深度分析
### 2.1 ruoyi-ai（后端）- 核心引擎
**架构评分**：⭐⭐⭐⭐⭐（5/5）
**优势**：
- 模块化设计清晰（25个common子模块）
- AI能力完整（模型接入、RAG、Agent、工作流）
- 技术栈先进（LangChain4j、Spring AI）
- 扩展性强（MCP协议、流程编排）
**不足**：
- Spring Boot版本实际为3.5.8（非宣称的4.0）
- SQL Server支持需自行开发
- 文档有些地方不够详细
**核心资产**：
| 模块 | 价值 | HZHub复用度 |
|------|------|-------------|
| ruoyi-chat | AI聊天、知识库、MCP | 90% |
| ruoyi-aiflow | 流程编排引擎 | 90% |
| ruoyi-system | 系统管理 | 80% |
| ruoyi-common | 公共组件库 | 85% |
### 2.2 ruoyi-admin（管理后台）- 配置中心
**架构评分**：⭐⭐⭐⭐⭐（5/5）
**优势**：
- Monorepo架构先进（pnpm + Turbo）
- Vben生态丰富（@vben/*包）
- 组件封装规范（useVbenVxeGrid等）
- 权限控制完善
**不足**：
- 学习曲线较陡（Vben生态复杂）
- 构建依赖较多
- 定制需要理解Monorepo机制
**核心资产**：
| 功能 | 价值 | HZHub复用度 |
|------|------|-------------|
| 系统管理 | 用户、角色、菜单 | 95% |
| 流程编排设计器 | @vue-flow/core | 90% |
| 知识库管理 | 文档、片段管理 | 85% |
| MCP工具管理 | 工具、市场 | 80% |
### 2.3 ruoyi-web（用户前端）- 交互界面
**架构评分**：⭐⭐⭐⭐（4/5）
**优势**：
- 架构简洁（Single Repo）
- Element Plus X组件专业（Sender等）
- 流式响应处理成熟
- 代码易于理解
**不足**：
- 功能相对单一（主要是聊天）
- 单包架构扩展性有限
- 与Admin技术栈不一致（Element Plus vs Ant Design）
**核心资产**：
| 组件 | 价值 | HZHub复用度 |
|------|------|-------------|
| ModelSelect | 模型选择器 | 90% |
| FilesSelect | 文件选择器 | 90% |
| Sender | 聊天输入组件 | 85% |
| 流式处理 | SSE实现 | 95% |
---
## 三、HZHub整合策略
### 3.1 复用矩阵
| RuoYi资产 | HZHub目标 | 复用策略 | 工作量 |
|-----------|-----------|----------|--------|
| ruoyi-chat模块 | hzhub-ai | 直接复用 | 低 |
| ruoyi-aiflow模块 | hzhub-ai | 直接复用 | 低 |
| ruoyi-system模块 | hzhub-admin | 直接复用 | 低 |
| ruoyi-admin整体 | hzhub-admin | 改造AI模块为ERP模块 | 中 |
| ruoyi-web组件 | hzhub-portal-* | 复用组件，改造业务 | 中 |
| SQL Agent | hzhub-erp | 改造为SQL Server版 | 高 |
### 3.2 推荐技术路线
```
HZHub 技术栈决策：
后端 (hzhub-ai / hzhub-erp / hzhub-gateway)
├── Spring Boot 3.5.8（与ruoyi-ai一致，暂不用4.0）
├── LangChain4j 1.11.0
├── MyBatis Plus 3.5.14
├── Sa-Token 1.44.0
└── 复用ruoyi-ai的common模块
管理后台 (hzhub-admin)
├── Vue 3 + TypeScript
├── Vben Admin（复用ruoyi-admin架构）
├── Ant Design Vue
├── pnpm workspace + Turbo
└── 复用ruoyi-admin的packages
门户前端 (hzhub-portal-company / hzhub-portal-dealer)
├── Vue 3 + TypeScript
├── Element Plus X（复用ruoyi-web组件）
├── UnoCSS
├── Pinia
└── 复用ruoyi-web的组件模式
```
### 3.3 开发优先级
| 优先级 | 模块 | 依赖 | 预计工期 |
|--------|------|------|----------|
| P0 | hzhub-ai | 复用ruoyi-chat | 1周 |
| P0 | hzhub-admin | 复用ruoyi-admin | 1周 |
| P1 | hzhub-erp | 自研SQL Server适配 | 2-3周 |
| P1 | hzhub-portal-company | 复用+改造 | 2周 |
| P2 | hzhub-portal-dealer | 复用+改造 | 2周 |
| P2 | 流程编排ERP节点 | 扩展aiflow | 1周 |
---
## 四、关键设计决策
### 4.1 后端架构决策
**决策1：Spring Boot版本**
- 选择：3.5.8（与ruoyi-ai一致）
- 理由：稳定性优先，4.0升级成本未知
**决策2：ERP服务独立**
- 选择：独立hzhub-erp服务
- 理由：隔离SQL Server 2008 R2兼容性风险
**决策3：AI服务复用**
- 选择：直接复用ruoyi-chat
- 理由：功能完整，改造成本低
### 4.2 前端架构决策
**决策1：管理后台框架**
- 选择：Vben Admin（Ant Design Vue）
- 理由：功能强大，生态完善
**决策2：门户前端框架**
- 选择：Element Plus X
- 理由：ruoyi-web组件可直接复用
**决策3：样式方案**
- 选择：Admin用Tailwind，门户用UnoCSS
- 理由：与各自复用源码保持一致
### 4.3 数据库决策
**决策1：向量数据库**
- 选择：Milvus
- 理由：ruoyi-ai原生支持，性能优秀
**决策2：ERP数据源**
- 选择：直连SQL Server 2008 R2
- 理由：无WebService接口，需JDBC直连
---
## 五、风险评估
### 5.1 技术风险
| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| SQL Server 2008 R2兼容性 | 高 | 预留双数据源，可切换 |
| LangChain4j API变化 | 中 | 锁定版本1.11.0 |
| 前端技术栈不一致 | 中 | 文档化两套UI规范 |
| 企业微信多实体对接 | 中 | 抽象配置层 |
### 5.2 项目风险
| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| 工期估算不准 | 中 | 分阶段交付，每阶段验收 |
| ERP数据结构不明 | 高 | 先做数据架构调研 |
| 团队学习成本 | 中 | 文档+培训 |
---
## 六、实施建议
### 6.1 第一阶段（1-2周）
**目标**：搭建基础框架
**任务**：
1. 创建Gitea仓库，初始化项目结构
2. 复制ruoyi-ai代码到hzhub-ai
3. 复制ruoyi-admin代码到hzhub-admin
4. 验证基础功能运行
**产出**：
- 可运行的基础框架
- 开发环境搭建文档
### 6.2 第二阶段（3-4周）
**目标**：ERP服务开发
**任务**：
1. 开发hzhub-erp服务（SQL Server连接）
2. 实现基础数据查询API
3. 开发SQL Agent（SQL Server版）
4. 集成到hzhub-admin
**产出**：
- ERP服务可用
- 基础数据查询功能
### 6.3 第三阶段（5-6周）
**目标**：门户开发
**任务**：
1. 开发hzhub-portal-company
2. 开发hzhub-portal-dealer
3. 集成AI组件到门户
4. 企业微信对接
**产出**：
- 公司门户可用
- 经销商门户可用
### 6.4 第四阶段（7-8周）
**目标**：流程编排与优化
**任务**：
1. 扩展流程编排ERP节点
2. 性能优化
3. 安全加固
4. 文档完善
**产出**：
- 完整业务流程跑通
- 上线准备就绪
---
## 七、总结
### 7.1 RuoYi-AI价值评估
| 维度 | 评分 | 说明 |
|------|------|------|
| 技术先进性 | ⭐⭐⭐⭐⭐ | Spring AI、LangChain4j、流程编排 |
| 代码质量 | ⭐⭐⭐⭐⭐ | 规范清晰，文档完善 |
| 功能完整性 | ⭐⭐⭐⭐⭐ | AI能力全覆盖 |
| 可复用性 | ⭐⭐⭐⭐⭐ | 模块化设计，易于复用 |
| 社区活跃度 | ⭐⭐⭐⭐ | 较新项目，发展迅速 |
**总体评价**：RuoYi-AI是构建HZHub的**理想基础**，可以大幅缩短开发周期（估计节省3-4个月）。
### 7.2 HZHub建设路径
```
基于RuoYi-AI构建HZHub的核心策略：
1. 复用为主（70%）
- 直接复用ruoyi-chat、ruoyi-aiflow
- 直接复用ruoyi-admin系统管理
- 复用ruoyi-web组件
2. 改造为辅（20%）
- 改造AI模块为ERP模块
- 改造SQL Agent为SQL Server版
- 改造门户为业务门户
3. 自研补充（10%）
- ERP数据适配层
- 企业微信多实体对接
- 业务流程节点
```
### 7.3 下一步行动
1. **立即执行**：创建Gitea仓库，初始化项目
2. **本周完成**：复制ruoyi-ai和ruoyi-admin代码
3. **下周开始**：ERP服务开发
4. **持续进行**：文档更新和团队培训
---
**分析完成时间**：2026-03-26 09:15 UTC
**分析师**：大壮