refactor: 重命名 ruoyi 目录和文件为 hzhub
This commit is contained in:
370
docs/learnings/02-hzhub-admin-frontend-review.md
Normal file
370
docs/learnings/02-hzhub-admin-frontend-review.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# HZHub-Admin 管理后台审查报告
|
||||
|
||||
> 审查时间：2026-03-26
|
||||
> 项目路径：/data/hzhub-ai/hzhub-admin/
|
||||
|
||||
---
|
||||
|
||||
## 一、项目概述
|
||||
|
||||
### 1.1 基本信息
|
||||
|
||||
| 属性 | 内容 |
|
||||
|------|------|
|
||||
| 项目名称 | HZHub-AI Admin |
|
||||
| 定位 | 企业级AI助手平台 - 管理后台 |
|
||||
| 技术栈 | Vue 3 + Vben Admin + Ant Design Vue |
|
||||
| 构建工具 | Vite + pnpm + Turbo |
|
||||
| 包管理 | pnpm workspace (monorepo) |
|
||||
|
||||
### 1.2 核心功能
|
||||
|
||||
- **系统管理**：用户、角色、菜单、部门、岗位、字典
|
||||
- **AI配置**：模型管理、知识库管理、流程编排
|
||||
- **MCP工具**：工具管理、市场管理
|
||||
- **工作流**：流程设计、审批管理
|
||||
- **监控运维**：在线用户、操作日志、登录日志
|
||||
|
||||
---
|
||||
|
||||
## 二、项目结构分析
|
||||
|
||||
### 2.1 Monorepo架构
|
||||
|
||||
```
|
||||
hzhub-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 架构设计借鉴
|
||||
|
||||
| 方面 | HZHub-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. **保持结构一致**：遵循hzhub-admin的目录规范
|
||||
|
||||
---
|
||||
|
||||
## 九、总结
|
||||
|
||||
### 9.1 核心收获
|
||||
|
||||
1. **架构先进**：Monorepo + pnpm + Turbo，适合大型项目
|
||||
2. **组件丰富**：Vben生态提供完整的后台管理组件
|
||||
3. **AI功能完整**：流程编排、知识库、MCP工具管理齐全
|
||||
4. **代码规范**：目录结构清晰，组件封装模式统一
|
||||
|
||||
### 9.2 下一步行动
|
||||
|
||||
1. 复用 `hzhub-admin` 作为 `hzhub-admin` 基础
|
||||
2. 保留系统管理、权限控制等通用功能
|
||||
3. 改造AI管理模块为ERP管理模块
|
||||
4. 复用流程编排设计器，增加ERP业务节点
|
||||
|
||||
---
|
||||
|
||||
**审查完成时间**：2026-03-26 08:45 UTC
|
||||
**审查人**：大壮
|
||||
Reference in New Issue
Block a user