hzhub/docs/learnings/03-ruoyi-web-user-frontend-review.md

HZHub-Web 用户前端审查报告

审查时间：2026-03-26 项目路径：/data/hzhub-ai/hzhub-portal/

---

一、项目概述

1.1 基本信息

属性	内容
项目名称	HZHub-Web
定位	企业级AI助手平台 - 用户前端
技术栈	Vue 3 + TypeScript + Element Plus X
构建工具	Vite 6.x
包管理	pnpm

1.2 核心功能

• AI对话：多模型聊天、流式响应
• 知识库问答：RAG检索、文档对话
• 工作流执行：可视化流程运行
• 智能体交互：Agent工具调用
• 多模态：文本、图片、文件上传

---

二、项目结构分析

2.1 整体架构

hzhub-portal/
├── 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的差异

方面	hzhub-admin	hzhub-portal
架构	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模型
• 模型列表动态加载
• 默认模型自动设置

实现：

<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 状态管理设计

模块划分：

// 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 流式响应处理

// 使用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. 接收流式结果

代码示例：

<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 架构设计借鉴

方面	HZHub-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 启动命令

# 安装依赖
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. 复用 hzhub-portal 的组件和模式
2. 改造AI聊天为ERP智能助手对话
3. 开发公司门户和经销商门户
4. 集成AI能力到业务流程中

---

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