4.4 前端分层架构

概述

前端采用 Vue3 Composition API + TypeScript + Pinia + Element Plus，分层为：views（页面）→ components（公共组件）→ api（接口）→ utils/http（请求封装）→ store（状态）→ router（动态菜单）。本节给出分层视图与协作关系。

前端分层视图

┌─────────────────────────────────────────────────────────┐
│ views/{域}/{模块}/            页面层                     │
│   index.vue / edit.vue / detail.vue                     │
│   columns.ts（表格列）  querySchemas.ts（筛选表单）      │
└──────────────┬──────────────────────────────────────────┘
               │ 组件/指令/组合式函数
┌──────────────▼──────────────────────────────────────────┐
│ components/            公共组件层（25 类）                │
│   Table Form Select Upload Editor Excel ChinaArea …     │
│ directives/            权限指令 v-permission 等           │
│ hooks/                 core / event / setting / web      │
└──────────────┬──────────────────────────────────────────┘
               │ 接口调用
┌──────────────▼──────────────────────────────────────────┐
│ api/{域}/{模块}.ts       接口层（url 对齐 gmeta path）    │
└──────────────┬──────────────────────────────────────────┘
               │ http.request
┌──────────────▼──────────────────────────────────────────┐
│ utils/http/axios         请求封装层                      │
│   baseURL=/api · JWT 注入 · 401 处理 · 信封解包          │
└──────────────┬──────────────────────────────────────────┘
               │ 状态支撑
┌──────────────▼──────────────────────────────────────────┐
│ store/modules/           状态层（Pinia）                 │
│   user（令牌/身份） · asyncRoute（动态菜单）…            │
│ router/                  路由层                          │
│   constant.ts（常量路由） · generator-routers.ts（动态） │
│   router-guards.ts（守卫）                                │
└─────────────────────────────────────────────────────────┘

数据流（以列表页为例）

1. 路由守卫拦到未加载动态路由 → 调 /api/index/getMenus 拉菜单树 → 生成路由
2. 进入页面 index.vue：
   querySchemas.ts 定义筛选表单 → 用户输入 → 拼 params
3. 调 api getExamplePage(params)
   → http 封装注入 Authorization: Bearer <access_token>
   → 后端返回统一信封，拦截器解包出 data（records/total/…）
4. columns.ts 驱动 Table 渲染；枚举列显示 {field}Text
5. 增删改走 edit.vue 表单 → exampleAdd/exampleUpdate → 成功刷新列表

关键机制索引

机制	位置	详见
HTTP 封装（401 跳登录/令牌刷新）	utils/http/	9.4
动态菜单路由	router/generator-routers.ts	9.5
权限指令（按钮级）	directives/permission.ts	9.7
登录多形态（账号/扫码/手机）	views/login/	9.8
三件套规范	views/{域}/{模块}/	9.12 / 12.2
主题与设置	settings/ + styles/	9.14

与后端的契约对齐

api url（无 /api 前缀）  ↔  gmeta path（/api 开头，无 /v1）
querySchemas field       ↔  XxxPageReq json 字段（驼峰）
columns prop             ↔  Item/DetailRes json 字段
权限指令参数             ↔  gmeta permission 权限码
登录读取                 ↔  data.access_token（下划线例外）

对齐是联调问题的高发区，联调自检清单见 3.9 前端联调指引。