# 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模型
- 模型列表动态加载
- 默认模型自动设置

**实现**：
```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 架构设计借鉴

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

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

---

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