109 lines
3.8 KiB
Markdown
109 lines
3.8 KiB
Markdown
# 9.1 前端工程概述
|
||
|
||
:::tip 概述
|
||
前端基于 Vue 3 + TypeScript + Vite + NaiveUI 构建，采用 Pinia 状态管理，支持动态菜单和权限控制。通过 Axios 封装统一处理请求/响应/错误，通过 `v-perm` 指令实现按钮级权限控制。前端为本仓库 **`ui/` 目录**内的 NaiveVue 管理后台，与本后端通过 API 对接。
|
||
:::
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术 | 版本 | 说明 |
|
||
|------|------|------|------|
|
||
| 框架 | Vue | 3.5+（实际 ^3.5.1） | 核心 UI 框架 |
|
||
| 语言 | TypeScript | 4.9+（实际 ^4.9.5） | 类型安全 |
|
||
| UI 库 | NaiveUI | 2.40+（实际 ^2.40.0） | 组件库 |
|
||
| 构建 | Vite | 5.4+（实际 ^5.4.3） | 开发服务器与构建 |
|
||
| 状态 | Pinia | 2.2+（实际 ^2.2.2） | 全局状态管理 |
|
||
| 路由 | Vue Router | 4.4+（实际 ^4.4.3） | 路由管理 |
|
||
| HTTP | Axios | 1.7+（实际 ^1.7.7） | HTTP 请求 |
|
||
| 富文本 | TinyMce / Quill | 5.10+ | 富文本编辑器 |
|
||
| 图表 | ECharts | 5.5+ | 数据可视化 |
|
||
| CSS | TailwindCSS + Less | 3.4+ | 原子化 CSS 与预处理 |
|
||
|
||
（版本以前端仓库 `package.json` 为准。）
|
||
|
||
## 核心特性
|
||
|
||
### 动态路由
|
||
|
||
从后端 `/api/index/getMenus` 接口获取菜单数据，自动生成前端路由，无需手动维护路由表。
|
||
|
||
```text
|
||
后端菜单数据 → generator-routers.ts → Vue Router 动态路由
|
||
```
|
||
|
||
### 权限控制
|
||
|
||
`v-perm` / `v-perms` 指令控制按钮级权限：
|
||
|
||
```vue
|
||
<n-button v-perm="['sys:user:add']">新增</n-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)。
|
||
:::
|