# 4.4 前端分层架构

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

## 前端分层视图

```text
┌─────────────────────────────────────────────────────────┐
│ 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（守卫）                                │
└─────────────────────────────────────────────────────────┘
```

## 数据流（以列表页为例）

```text
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 |

## 与后端的契约对齐

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

对齐是联调问题的高发区，联调自检清单见 [3.9 前端联调指引](../guide/frontend-integration)。