This commit is contained in:
yin 2026-09-18 18:37:15 +08:00
parent 216d23ef5f
commit 6b073283bf

View File

@ -0,0 +1,187 @@
# 登录功能 + 页面渲染框架 · 文件清单与移植指南
> 目的:把本项目的「登录功能」与「后台菜单驱动的页面渲染框架」完整搬到新项目。
> 范围约定:**不含** `userPreference.ts`(用户偏好)、`frontBrand.ts`(域名品牌)、语言切换(`LangSelect` + `lang/` 全量词条)。
---
## 0. 依赖包
```jsonc
{
"vue": "^3",
"vue-router": "^4",
"pinia": "^2",
"axios": "^1",
"element-plus": "^2",
"nprogress": "^0.2", // 路由进度条(permission.ts)
"js-cookie": "^3", // token 存 Cookie(utils/auth.ts)
"path-browserify": "^1", // 页签路径拼接(TaskView)
"@vueuse/core": "^10", // useWindowSize / useFullscreen
"dayjs": "^1", // 顶栏有效期天数计算
"qrcode": "^1", // 登录页扫码二维码(若不需要扫码登录可去掉)
"sass": "^1" // 布局 SCSS
}
```
`vite.config.ts` 需要 `@` → `src` 别名,`tsconfig` 需同步 `paths`。
---
## 1. 登录功能
| # | 文件 | 职责 | 关键点 |
|---|---|---|---|
| 1 | `src/views/login/index.vue` | 登录页:账号密码登录、注册、微信扫码登录 | 登录成功 → `router.push(redirect \|\| '/')`;扫码成功后 `setToken` + `userStore.$patch({token})` |
| 2 | `src/stores/modules/user.ts` | **登录核心 store** | `login / register / getInfo / changeRole / logout / resetToken / updateToken / checkPermission` |
| 3 | `src/api/user/user.ts` | 登录相关接口 | `user.login`、`user.loginByCode`、`user.register`、`user.info`、`user.changeRole`、`user.logout`、`user.getLoginWechatCode`(扫码)、`user.getBindWechatCode` / `user.unbindWechat`(绑定) |
| 4 | `src/utils/auth.ts` | token 存取(Cookie,key=`token`) | `getToken / setToken / removeToken` |
| 5 | `src/utils/request.ts` | axios 封装 | 请求头 `platform/project`、注入 `Authorization: Bearer <token>`、**响应头新 token 自动回写**、`401/50008/50012/50014` → 弹窗重登 |
| 6 | `src/permission.ts` | 路由守卫(登录准入 + 动态路由) | 白名单、getToken 判定、`getInfo()` 拉菜单、失败 `resetToken()` |
| 7 | `src/router/index.ts` | `/login`、`/redirect` 常量路由 | `/login` 在 `constantRoutes` 且 `meta.hidden` |
| 8 | `src/layout/component/Navbar.vue` | 退出登录入口 | `await userStore.logout(); router.push('/login?redirect=' + route.fullPath)` |
| 9 | `.env.development` / `.env.staging` / `.env.production` | `VITE_APP_BASE_API`(后端地址) | `request.ts` 的 `baseURL` |
| 10 | `src/lang/zh-CN.ts` / `en-US.ts`(若做 i18n) | `login.*` 文案 | 不做 i18n 时改为硬编码中文 |
| 11 | `src/views/redirect/index.vue` | `/redirect` 软刷新中转(登出/刷新链路相关) | 见 2.2 |
### 登录链路
```mermaid
flowchart LR
A[访问页面] --> B{permission.ts<br/>getToken?}
B -- 无 --> C[/login?redirect=xxx/]
C --> D[views/login/index.vue]
D --> E[userStore.login]
E --> F[api/user: user.login]
F --> G[utils/request.ts POST /system]
G --> H[auth.ts setToken Cookie]
H --> I[router.push redirect]
I --> B
B -- 有 --> J[userStore.getInfo → user.info]
J --> K[permissionStore.generateRoutes menus]
```
---
## 2. 页面渲染框架
> 核心思想:**后端菜单(`user.menus`)→ `transformMenusToRoutes` → `router.addRoute` → Layout 渲染 → Sidebar/TaskView 消费 `permissionStore.routes`**。
### 2.1 路由层(4 个文件,框架心脏)
| 文件 | 职责 |
|---|---|
| `src/router/index.ts` | `constantRoutes`(`/redirect`、`/login`、`/admin/land`、`/`→dashboard、`/workorder`、`/inbox`、`/profile`、`/download`)、`notFoundRoute`、`notFoundPage`、`transformMenusToRoutes()`、`resolveComponent()`、`resolveViewFromGlob()`、`ParentView`、`createRouter` |
| `src/router/map.ts` | `componentMap`:**后端菜单 `component` 字段 → 页面组件** 的静态映射表(避免 Vite 动态 import 报错) |
| `src/stores/modules/permission.ts` | `routes` / `addRoutes` / `hasAddRoutes`;`generateRoutes(menus)` → 末尾追加 404 |
| `src/permission.ts` | `beforeEach`:白名单 → 取用户信息 → `generateRoutes` → 逐条 `router.addRoute` → `return { ...to, replace: true }` 重进;`afterEach` `NProgress.done()` |
### 2.2 布局层(Layout / 顶栏 / 页签)
| 文件 | 职责 |
|---|---|
| `src/layout/index.vue` | 外壳:`sidebar`(非 top-bottom 模式)+ `fixed-header`(`task-view`)+ `main-box`(`app-main`);响应式 992px 切 `device=mobile` |
| `src/layout/component/AppMain.vue` | **页面渲染出口**:`router-view` + `transition` + `keep-alive`;`wrapRouteComponent()` 把路由组件包装成 `name = route.name` 以让 `include` 生效;`:key="route.name ?? route.path"` |
| `src/layout/component/TaskView/index.vue` | **顶部容器**:`<navbar>` + 快捷键区 + **页签(tags-view)**;`watch(route)` → `tagsViewStore.addView(route)`;右键菜单刷新/关闭/关闭其他/全部关闭 |
| `src/layout/component/TaskView/ScrollPane.vue` | 页签横向滚动容器(横向滚轮) |
| `src/layout/component/Navbar.vue` | **顶部导航栏**:Logo、Breadcrumb(sidebar 模式)、TopMenu(top-bottom 模式)、右侧 有效期/全屏/工单角标/语言/AI、**头像下拉(切换角色 + 个人中心 + 退出登录)** |
| `src/layout/component/TopMenu.vue` | 顶部横向菜单(`layoutMode === 'top-bottom'` 时使用) |
| `src/layout/component/Sidebar/index.vue` | 左侧菜单容器(`el-menu` + `SidebarItem`) |
| `src/layout/component/Sidebar/SidebarItem.vue` | 递归菜单项(唯一子项拍平逻辑) |
| `src/layout/component/Sidebar/Item.vue` / `SubItem.vue` / `Link.vue` | 菜单项渲染 / 子项模板 / 内外链跳转 |
| `src/components/Breadcrumb/index.vue` | 面包屑(依赖 `permissionStore.routes` + `route.matched`) |
| `src/components/SvgIcon/index.vue` | 图标组件(`svg-icon` 全局注册;依赖 `vite-plugin-svg-icons` 的 `virtual:svg-icons-register`) |
| `src/views/redirect/index.vue` | `/redirect/:path(.*)` 中转页(页签"刷新"软刷新) |
| `src/views/404.vue` | 兜底页(动态路由找不到组件时也指向它) |
### 2.3 状态层(Pinia)
| 文件 | 职责 | 是否必需 |
|---|---|---|
| `src/stores/modules/permission.ts` | 动态路由表 | ✅ 必需 |
| `src/stores/modules/app.ts` | `sidebar{opened,withoutAnimation}`、`device`、`toggleDevice/toggleSideBar/closeSideBar` | ✅ 必需 |
| `src/stores/modules/settings.ts` | `fixedHeader`、`layoutMode('sidebar'\|'top-bottom')`、`shortcutExpanded`(`changeSetting`) | ✅ 必需 |
| `src/stores/modules/tagsView.ts` | `visitedViews` / `cachedViews` + `add/del/update` | ✅ 必需(页签 + keep-alive) |
| `src/stores/modules/shortcuts.ts` | 快捷键区数据 | ⚠️ 可选(TaskView 引用,可删) |
| `src/stores/modules/experimental.ts` | `pageCacheEnabled` / `pageCacheMax` | ⚠️ 可选(AppMain 引用,可给默认值) |
| `src/stores/modules/user.ts` | 登录态 | ✅ 必需(见第 1 节) |
### 2.4 样式层
`src/styles/index.scss`、`variables.scss`、`variables.module.scss`(Sidebar 用 JS 取色)、`mixin.scss`(`clearfix` 等)、`sidebar.scss`、`transition.scss`(`fade-transform` 过渡)、`element-ui.scss`。
### 2.5 入口与配置
| 文件 | 职责 |
|---|---|
| `src/main.ts` | `createApp` → `pinia` → `router` → `ElementPlus`;`import './permission'`;注册全局 `svg-icon`;`app.mount('#app')`;`document.title` 统一设置 |
| `src/App.vue` | `el-config-provider`(Element 语言)+ `<router-view />` |
| `src/settings.ts` | `title`、`fixedHeader`、`sidebarLogo`、`shortcutExpanded`、`toolbarMode` 等默认值 |
| `src/utils/get-page-title.ts` | 页面标题拼接 |
| `src/utils/validate.js` | `isExternal`(Sidebar/TaskView/SvgIcon 依赖) |
| `.env.*` | `VITE_APP_BASE_API` 等 |
| `index.html` | `#app` 挂载点 + favicon |
| `vite.config.ts` | `@` alias、`vite-plugin-svg-icons` |
---
## 3. 渲染调用链
```mermaid
flowchart TD
A["后端 user.info → user.menus"] --> B["stores/permission.ts generateRoutes(menus)"]
B --> C["router/index.ts transformMenusToRoutes()"]
C --> D{"menu.component 是什么?"}
D -- "Layout" --> E["Layout (layout/index.vue)"]
D -- "字符串" --> F["componentMap (router/map.ts)"]
F --> G["命中 → 直接返回 lazy loader"]
F --> H["未命中 → import.meta.glob('@/views/**/*.vue') 兜底"]
H --> I["再未命中 → views/404.vue"]
C --> J["permission.ts: router.addRoute(route)"]
J --> K["Layout 渲染"]
K --> L["Sidebar / TopMenu ← permissionStore.routes"]
K --> M["TaskView 页签 ← route 变化 addView"]
K --> N["AppMain router-view + keep-alive ← tagsView.cachedViews"]
```
---
## 4. 照搬不能改的契约(最容易踩坑)
1. **`componentMap` 的 key 必须与后端菜单 `component` 字段一致**(如 `order/waveOrder`、`system/setting/role/index`);不一致时靠 `import.meta.glob` 兜底,再不一致落到 404。
2. **禁止多段路径的模板字符串动态 import**:Vite 生产构建会报 `unknown variable dynamic import`。只能用 `componentMap` 或 `import.meta.glob`。单段路径(如 `warehouse`)才允许 `import(\`@/views/${p}/index.vue\`)`。
3. **keep-alive 的 `include` 用「路由 name」**,但 `<script setup>` 页面组件无 `name` → 必须用 `AppMain.vue` 的 `wrapRouteComponent()` 包装成同名组件,否则缓存完全失效。
4. **keep-alive 必须常驻**(不能放 `v-if` 里),访问 `/login`、`/404` 等 Layout 外页面会卸载 Layout 并清空缓存,这是正常的。
5. **路由 name 冲突**:子路由 name 与父路由相同 → `transformMenusToRoutes` 自动改名为 `${name}_Child`,不要依赖原始 name 做缓存 key 匹配。
6. **顶层路由 path 必须以 `/` 开头**(Vue Router 4 要求,代码已自动补)。
7. **`notFoundPage` / `notFoundRoute` 必须最后追加**,否则会抢先匹配动态路由。
8. `generateRoutes` 后必须 `return { ...to, replace: true }` 让导航重跑一次,否则首次进入白屏。
9. **`permission.ts` 判定登录态用 `userStore.user.employees_name`**(不是只用 token),配合 `getToken()`。
10. **token 双写**:Cookie(`utils/auth.ts`)+ Pinia(`user.ts`);`request.ts` 收到响应头 `Authorization`/`new-authorization` 会回写两者(续期场景)。
---
## 5. 移植步骤建议
1. **初始化**:装依赖 §0,配 `vite.config.ts` 的 `@` 别名 + `vite-plugin-svg-icons`(指向 `src/icons/svg`),`tsconfig` 配 `paths`。
2. **拷贝样式**:`src/styles/*` + `src/icons/` + `src/components/SvgIcon/`。
3. **拷贝工具**:`utils/auth.ts`、`utils/request.ts`、`utils/validate.js`、`utils/get-page-title.ts`、`settings.ts`、`App.vue`。
4. **拷贝状态**:`stores/modules/{app,settings,tagsView,permission,user}.ts`(`app.ts` 里的 `device` 需保留,登录接口要传)。
5. **拷贝路由**:`router/{index,map}.ts`(**删掉业务页面路由,只留 `/redirect`、`/login`、`/404`、dashboard 占位**;`map.ts` 按新项目页面重写)。
6. **拷贝布局**:`layout/**` + `components/Breadcrumb/`。
7. **拷贝登录**:`views/login/index.vue` + `api/user/user.ts`。
8. **接守卫**:`main.ts` 里 `import './permission'`。
9. **改常量**:`.env` 的 `VITE_APP_BASE_API`、`settings.ts` 的 `title`。
10. **验证顺序**:未登录访问任意页 → 跳 `/login`;登录后 `user.info` 拿到 `menus` → 侧边栏出现菜单;点菜单能渲染;开页签;切页签不白屏不重复请求(缓存生效);点退出回登录页。
---
## 6. 本次明确排除(新项目按需自行决定)
| 项目 | 关联文件 | 排除后的副作用 |
|---|---|---|
| 用户偏好 | `stores/modules/userPreference.ts` | 删掉 `permission.ts` 里 `prefs.load()` 三处调用 |
| 域名品牌 | `stores/modules/frontBrand.ts`、`api/frontconfig/` | 删掉 `main.ts` 的 `loadBrandByDomain()`、`Login` 页品牌 computed、`Navbar` 的 `mainLogo` 改用固定图 |
| 语言切换 | `components/LangSelect/`、`lang/`、`vue-i18n`、`App.vue` 的 `el-config-provider` | ⚠️ **注意**:布局里 `tMenu()` 与 `$t()` 大量出现(`Navbar`、`TaskView`、`Sidebar/Item|SubItem`、`Breadcrumb`、`main.ts`),排除 i18n 后这些调用点要改成纯文本 |
| 打印组件 / AI / 工单角标 | `stores/modules/printerComponent.ts`、`layout/component/AiChat/`、`Navbar` 的 `afterSaleWorkCount` | `permission.ts` 的 `ensurePrinterConnectionsAfterLogin()`、`user.ts` 的 `usePrinterComponentStore()` 需一并删除 |
| 快捷键 | `stores/modules/shortcuts.ts` | 删 `TaskView` 里的快捷键区块 |