签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,91 +1,69 @@
 # 9.1 前端工程概述

 :::tip 概述
-前端基于 Vue 3 + TypeScript + Vite + ElementPlus 构建，采用 Pinia 状态管理，支持动态菜单和权限控制。通过 Axios 封装统一处理请求/响应/错误，通过 v-perm 指令实现按钮级权限控制。
+前端为独立 Vite 工程（`ui/`）：Vue3 + TypeScript + ElementPlus + Pinia。核心机制包括 axios 信封解包、动态菜单路由、权限指令与 28 个公共组件。本章按"工程基础 → 核心机制 → 公共组件 → 开发实践"组织。
 :::

-## 技术栈
+## 技术构成

-| 类别 | 技术 | 版本 | 说明 |
-|------|------|------|------|
-| 框架 | 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 |
+| 层 | 选型 |
+|---|---|
+| 框架 | Vue 3.4（Composition API）+ TypeScript 4.9 |
+| 构建 | Vite 3（开发端口 8001，/api 代理到 8000） |
+| UI | ElementPlus 2.7 + @element-plus/icons |
+| 状态 | Pinia（7 个 store 模块） |
+| 路由 | vue-router 4（静态 + 动态菜单生成） |
+| HTTP | axios 0.27（自研拦截器封装层） |
+| 富文本 | TinyMCE / vue-quill（双引擎） |
+| 其他 | echarts、xlsx、cropperjs、ali-oss、dayjs、lodash |

-## 核心特性
-
-### 动态路由
-
-从后端 `/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` 时自动跳转登录页
-
-### 组件库
-
-内置 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/              # 页面视图
+├── api/          接口模块（按业务域分组）
+├── components/   公共组件（28 个）
+├── directives/   指令（perm/perms/scrollBar/clickOutside）
+├── enums/        枚举常量
+├── hooks/        组合式函数（core/event/setting/web 分组）
+├── layout/       布局系统
+├── router/       静态路由 + 动态生成器 + 守卫
+├── store/        Pinia（user/asyncRoute/tabsView/design/project/lockscreen/ossConfig）
+├── styles/       全局样式与主题变量
+├── settings/     应用默认设置
+├── utils/        工具（http/auth/validate/date/file...）
+└── views/        页面（按业务域分目录）
 ```

-## 开发命令
+## 与后端的协作形态
+
+```text
+登录 → GetMenus（动态路由）→ 页面渲染
+     → api 模块发起请求（http 封装加前缀/Token）
+     → 拦截器解包信封（0 成功 / 401 刷新或跳登录 / 其余弹 msg）
+     → v-perm 控制按钮显隐 / 字典接口驱动下拉
+```
+
+## 阅读路线
+
+| 目标 | 页面 |
+|---|---|
+| 了解工程结构 | 9.2 目录结构详解 |
+| 接后端接口 | 9.4 HTTP 封装 + 9.14 API 模块编写规范 |
+| 做页面 | 9.13 新增页面开发步骤 |
+| 排查登录/权限问题 | 9.5 路由与动态菜单 + 9.7 权限控制 + 9.8 登录流程 |
+| 用公共组件 | 9.9–9.12 组件四篇 |
+
+## 命令

 ```bash
-pnpm install        # 安装依赖
-pnpm dev            # 启动开发服务器
-pnpm build          # 构建生产版本
-pnpm preview        # 预览构建结果
-pnpm lint:eslint    # ESLint 检查
-pnpm lint:prettier  # Prettier 格式化
-```
+cd ui
+pnpm dev            # 开发
+pnpm build          # 生产构建
+pnpm type:check     # 类型检查
+pnpm lint:eslint    # ESLint
+```
+
+## 下一步
+
+→ [9.2 目录结构详解](/zh/frontend/directory.html)