diff --git a/docs/登录功能与页面渲染框架-移植清单.md b/docs/登录功能与页面渲染框架-移植清单.md new file mode 100644 index 00000000..6ef9b099 --- /dev/null +++ b/docs/登录功能与页面渲染框架-移植清单.md @@ -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 自动回写**、`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
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` | **顶部容器**:`` + 快捷键区 + **页签(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 语言)+ `` | +| `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」**,但 `