175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
[根目录](../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 | 初始化模块文档 |
|