签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,75 @@
+# 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)。