[根目录](../CLAUDE.md) > **web**

# web - Vue3 前端模块

## 模块职责

基于 Vue 3 + Naive UI 构建的管理后台，提供：用户/角色/权限/菜单/部门的系统管理，三平台招聘数据的浏览与搜索，数据采集趋势与来源分布的统计看板（ECharts），定向数据清洗操作，关键词与代理 IP 管理。

---

## 入口与启动

| 文件 | 说明 |
|------|------|
| `web/src/main.js` | Vue 应用入口，依次初始化 Store、Router、指令、i18n，挂载到 `#app` |
| `web/src/App.vue` | 根组件 |
| `web/src/router/index.js` | Vue Router 配置，含路由守卫（认证、页面 Loading、标题） |
| `web/src/store/index.js` | Pinia Store 入口 |

### 本地开发

```bash
cd web
pnpm install
pnpm dev      # Vite dev server，默认 http://localhost:5173
pnpm build    # 构建到 web/dist/
pnpm lint     # ESLint 检查
```

---

## 页面路由结构

| 路由路径 | 视图文件 | 说明 |
|----------|----------|------|
| `/login` | `views/login/index.vue` | 登录页 |
| `/analytics` | `views/analytics/index.vue` | 数据分析看板（ECharts 趋势 + 来源饼图） |
| `/recruitment/qcwy` | `views/recruitment/qcwy/index.vue` | 前程无忧数据浏览 |
| `/recruitment/zhilian` | `views/recruitment/zhilian/index.vue` | 智联招聘数据浏览 |
| `/recruitment/boss` | `views/recruitment/boss/index.vue` | Boss 直聘数据浏览 |
| `/cleaning/targeted` | `views/cleaning/index.vue` | 定向数据清洗 |
| `/cleaning/monitor` | `views/cleaning/monitor.vue` | 清洗任务监控 |
| `/keyword` | `views/keyword/index.vue` | 关键词管理 |
| `/profile` | `views/profile/index.vue` | 个人中心 |
| `/system/user` | `views/system/user/index.vue` | 用户管理 |
| `/system/role` | `views/system/role/index.vue` | 角色管理 |
| `/system/menu` | `views/system/menu/index.vue` | 菜单管理 |
| `/system/api` | `views/system/api/index.vue` | API 权限管理 |
| `/system/dept` | `views/system/dept/index.vue` | 部门管理 |
| `/system/auditlog` | `views/system/auditlog/index.vue` | 审计日志 |
| `/system/proxy` | `views/system/proxy/index.vue` | 代理 IP 管理 |
| `/system/token` | `views/system/token/index.vue` | Boss Token 管理 |

---

## 对外接口（API 调用层）

前端 API 模块位于 `web/src/api/`，通过 axios 封装：

| 文件 | 接口对象 | 说明 |
|------|----------|------|
| `api/index.js` | 所有系统接口 | 用户、角色、菜单、部门、API 管理等 |
| `api/analytics.js` | `getOverview` / `getVolumeTrend` / `getSourceDistribution` | 数据分析统计接口 |
| `api/keyword.js` | keyword CRUD | 关键词管理 |
| `api/proxy.js` | proxy CRUD | 代理 IP 管理 |
| `api/token.js` | token CRUD | Boss Token 管理 |

HTTP 工具层：`web/src/utils/http/`（基于 axios，含拦截器）

认证：JWT Token 存储于 localStorage，通过请求拦截器自动注入 `Authorization` 头。

---

## 关键依赖与配置

```json
{
  "主框架": "vue@^3.3.4",
  "UI 库": "naive-ui@^2.34.4",
  "状态管理": "pinia@^2.1.6",
  "路由": "vue-router@^4.2.4",
  "图表": "echarts@^6.0.0",
  "HTTP": "axios@^1.4.0",
  "图标": "@iconify/vue + @iconify/json",
  "工具": "@vueuse/core, lodash-es, dayjs",
  "构建": "vite@^4.4.6",
  "原子 CSS": "unocss@^66.5.10"
}
```

Vite 配置：`web/vite.config.js`（含 `@vitejs/plugin-vue`, `unocss`, `unplugin-icons`）。

---

## 数据模型（前端状态）

Pinia Store 模块（`web/src/store/modules/`）：

| Store 模块 | 说明 |
|------------|------|
| `user` | 当前登录用户信息、Token |
| `permission` | 动态路由权限（菜单权限列表） |
| `app` | 全局 UI 状态（侧边栏折叠、主题等） |
| `tags` | 多页签（Keep-Alive 页签管理） |

---

## 数据分析看板关键实现

`web/src/views/analytics/index.vue` 使用 ECharts 渲染：
- **趋势折线图**：按 hour/day/week/month 粒度，分 boss/qcwy/zhilian 三条折线，支持 dataZoom 交互
- **来源饼图**：环形饼图展示各平台数据占比
- **时间预设**：近 24h / 7d / 30d / 90d / 6m / 12m / 全部 / 自定义

---

## 测试与质量

- 当前无自动化测试文件（缺口）。
- 代码规范：ESLint (`@zclzone` + `@unocss` 配置) + `prettier`。
- 建议补充：Vitest 单元测试（工具函数）和 Playwright E2E 测试（登录、数据查看流程）。

---

## 常见问题 (FAQ)

**Q: 前端无法连接后端 API？**
A: 检查 `web/src/utils/http/index.js` 中的 `baseURL` 配置，或在 Vite 配置中设置代理（`vite.config.js` 的 `server.proxy`）。

**Q: 动态路由/菜单不更新？**
A: 登出后重新登录会重新拉取后端菜单树。如果菜单在后端已新增，前端 permission store 会在下次路由守卫拦截时重新请求。

**Q: 图表不显示？**
A: 检查 ClickHouse 是否可达（后端 `/api/v1/analytics/overview` 是否返回数据），以及图表容器 `div` 的高度是否为 0。

---

## 相关文件清单

```
web/src/
├── main.js                    # 应用入口
├── App.vue                    # 根组件
├── api/                       # API 调用层
│   ├── analytics.js
│   ├── keyword.js
│   ├── proxy.js
│   └── token.js
├── components/                # 公共组件（CrudTable, CrudModal, QueryBar 等）
├── layout/                    # 布局（侧边栏、顶栏、标签页）
├── router/                    # 路由配置与守卫
├── store/                     # Pinia Store
├── utils/
│   ├── auth/                  # JWT Token 工具
│   ├── http/                  # axios 封装
│   └── storage/               # localStorage 封装
└── views/
    ├── analytics/             # 数据分析看板
    ├── cleaning/              # 数据清理页面
    ├── keyword/               # 关键词管理
    ├── recruitment/           # 三平台数据浏览
    │   ├── boss/
    │   ├── qcwy/
    │   └── zhilian/
    └── system/                # 系统管理（用户/角色/菜单/部门/代理/Token/审计）
```

---

## 变更记录 (Changelog)

| 日期 | 说明 |
|------|------|
| 2026-03-20 | 初始化模块文档 |