# 9.1 前端工程概述

:::tip 概述
前端为 Vue3 + TypeScript + Vite + Element Plus + Pinia 的标准工程化项目（ui/ 目录），采用 Composition API，核心机制为：动态菜单路由、指令级权限、三件套页面规范（api/columns/querySchemas）、统一封装的 axios。
:::

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | ^3.4.27 | 核心框架（Composition API） |
| TypeScript | ^5.x | 类型系统 |
| Vite | ^5.x | 构建（多环境模式 dev/test/uat/prod） |
| Element Plus | ^2.7.4 | UI 组件库 |
| Pinia | ^2.1.7 | 状态管理 |
| Vue Router | ^4.3.2 | 路由（常量路由 + 动态菜单路由） |
| axios | ^0.27.2 | HTTP（封装于 utils/http/axios，VAxios 类） |
| echarts | ^5.5.0 | 数据可视化（仪表盘） |
| tinymce / vue-quill | 5.10.3 / beta.8 | 富文本编辑器 |
| xlsx | ^0.18.5 | Excel 导入导出 |
| cropperjs / vue-cropper | — | 图片裁剪 |
| dayjs / lodash-es | — | 工具 |

## 工程结构（src 下九层）

```text
api/         接口模块（按域分目录，url 对齐 gmeta path）
components/  公共组件（25 类）
directives/  自定义指令（permission 权限等）
enums/       枚举常量（http/cache/page/permissions/role…）
hooks/       组合式函数（core/event/setting/web…）
layout/      布局系统
router/      路由（constant 常量 + generator-routers 动态 + 守卫）
settings/    全局设置（项目/设计/组件/动画）
store/       Pinia（modules 7 个）
styles/      全局样式与主题变量
utils/       工具库（http 封装/auth/storage/downloadFile…）
views/       页面（按域分目录：system/data/content/monitor/tool…）
```

## 核心机制一览

| 机制 | 说明 | 详见 |
|------|------|------|
| HTTP 封装 | VAxios 类 + transform 链；统一信封解包、401 处理、消息提示 | 9.4 |
| 动态菜单路由 | 登录后拉 /api/index/getMenus 生成路由（generator-routers） | 9.5 |
| 状态管理 | Pinia modules：user/asyncRoute/tabsView/designSetting… | 9.6 |
| 权限控制 | directives/permission 按 permissions 控制按钮 | 9.7 |
| 登录流程 | 多形态（账号/手机/扫码/Qrcode 表单）+ token 存储 | 9.8 |
| 三件套规范 | api + columns.ts + querySchemas.ts 页面开发模式 | 9.12 |

## 与后端的契约

```text
baseURL = /api（Vite 开发代理指向 :8000）
接口 url 无 /v1 版本段（/user/page 而非 /v1/user/page）
响应信封 {code, ok, msg, data}：0 成功解包 / 1 弹 msg / 401 跳登录
登录读 data.access_token（下划线例外）
筛选三件套对齐：querySchemas ↔ PageReq ↔ spec 声明
```

## 常用命令

```sh
pnpm dev            # 开发（Vite 代理 /api → :8000）
pnpm build          # 生产构建
pnpm type:check     # vue-tsc 类型检查
pnpm lint:eslint    # ESLint 修复
pnpm preview        # 构建并预览
```

## 页面与后端模块对应

| 前端目录 | 后端模块 |
|---------|---------|
| views/system/{user,role,menu,dept,level,position,tenant} | system 域七模块 |
| views/system/logger/{loginLog,operLog} | login_log / operation_log |
| views/data/{city,config,dict,notice,param} | data 域五模块 |
| views/content/{article,category,link} | content 域三模块 |
| views/monitor/{online,server,cache,job} | online_user/server_monitor/cache_monitor/job |
| views/tool/{generator,example} | generator / example |
| views/file/fileTemplate | file_template |
| views/setting/{profile,configWeb} | index 个人中心 / config web 接口 |