# 9.1 前端工程概述

:::tip 概述
前端基于 Vue 3 + TypeScript + Vite + ElementPlus 构建，采用 Pinia 状态管理，支持动态菜单和权限控制。通过 Axios 封装统一处理请求/响应/错误，通过 `v-perm` 指令实现按钮级权限控制。前端为本仓库 **`ui/` 目录**内的 EleVue 管理后台，与本后端通过 API 对接。
:::

## 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | Vue | 3.4+ | 核心 UI 框架 |
| 语言 | TypeScript | 4.9+（实际 ^4.9.5） | 类型安全 |
| UI 库 | ElementPlus | 2.7+ | 组件库 |
| 构建 | Vite | 3.2+（实际 ^3.2.10） | 开发服务器与构建 |
| 状态 | Pinia | 2.1+ | 全局状态管理 |
| 路由 | Vue Router | 4.3+ | 路由管理 |
| HTTP | Axios | 0.27+（实际 ^0.27.2） | HTTP 请求（注：0.27.x 版本较老） |
| 富文本 | TinyMce | 5.10+ | 富文本编辑器 |
| 图表 | ECharts | 5.5+ | 数据可视化 |
| CSS | TailwindCSS | 3.4+ | 原子化 CSS |

（版本以前端仓库 `package.json` 为准。）

## 核心特性

### 动态路由

从后端 `/api/index/getMenus` 接口获取菜单数据，自动生成前端路由，无需手动维护路由表。

```text
后端菜单数据 → generator-routers.ts → Vue Router 动态路由
```

### 权限控制

`v-perm` / `v-perms` 指令控制按钮级权限：

```vue
<el-button v-perm="['sys:user:add']">新增</el-button>
```

### Token 管理

Axios 拦截器自动处理：

- 请求拦截：自动添加 `Authorization: Bearer <token>` 请求头
- 响应拦截：`code === 401` 时弹窗提示并跳转登录页（未内置自动续签，后端刷新能力见 8.6）

### 组件库

内置 20+ 个业务组件：

| 组件 | 说明 |
|------|------|
| BasicTable | 数据表格（分页、排序、搜索） |
| BasicForm | 动态表单（配置驱动） |
| BasicModal | 弹窗（表单弹窗、详情弹窗） |
| BasicUpload | 文件上传 |
| Editor | 富文本编辑器（TinyMce） |
| ImportExcel | Excel 导入 |
| Cropper | 头像裁剪 |
| Region | 行政区划选择 |
| Password | 密码强度检测 |
| Qrcode | 二维码生成 |

## 工程结构

```text
ui/src/
├── api/                # API 接口层（按业务域分组）
├── components/         # 公共组件库
├── directives/         # 自定义指令（v-perm）
├── enums/              # 枚举常量
├── hooks/              # 组合式函数
├── layout/             # 布局组件
├── plugins/            # 插件
├── router/             # 路由配置
├── settings/           # 项目配置
├── store/              # Pinia 状态管理
├── styles/             # 全局样式
├── utils/              # 工具函数
└── views/              # 页面视图
```

## 与后端的对应

| 前端 | 后端 | 说明 |
|------|------|------|
| `src/api/**` | `routes/api.php` | API 函数 ↔ 路由 |
| `src/views/**` | 菜单表 `component` 字段 | 页面组件 ↔ 动态菜单 |
| `v-perm` 指令 | `#[Permission]` 注解 | 按钮级权限 ↔ 接口鉴权 |
| 响应拦截器 `{code,ok,msg,data}` | `App\Support\Result` | 统一响应协议 |
| `records/total/current/size/pages` | `Result::page()` | 分页固定结构 |

## 开发命令

```bash
pnpm install        # 安装依赖（或 npm install）
pnpm dev            # 启动开发服务器（默认 8001）
pnpm build          # 构建生产版本
pnpm preview        # 预览构建结果
pnpm lint:eslint    # ESLint 检查
pnpm lint:prettier  # Prettier 格式化
```

:::tip 快速开始
前端启动与代理配置见 [2.4 前端服务启动](/zh/quickstart/frontend-start.html)；新增页面的完整步骤见 [9.12 新增页面开发步骤](/zh/frontend/new-page.html)。
:::