# much-admin **Repository Path**: chenhang0612/much-admin ## Basic Information - **Project Name**: much-admin - **Description**: 基于 Vue 3 + TypeScript + Vite 的后台管理前端，对接网关下的 认证（/auth）、系统（/system）、会员（/member） 等接口 - **Primary Language**: JavaScript - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-01 - **Last Updated**: 2026-05-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Much Admin 基于 **Vue 3 + TypeScript + Vite** 的后台管理前端，对接网关下的 **认证（/auth）**、**系统（/system）**、**会员（/member）** 等接口；菜单与路由由 **`/system/permission/getUserPermissionList`** 返回的权限树动态生成。 --- ## 技术栈 | 类别 | 说明 | |------|------| | 框架 | Vue 3、Vue Router 4、Vuex 4 | | UI | Element Plus（`@element-plus/icons-vue`） | | 构建 | Vite 2、Sass（全局注入 `variables.scss`） | | HTTP | Axios（`src/utils/request.ts`） | --- ## 环境要求 - **Node.js**：建议 LTS（与 Vite 2 / 当前依赖兼容即可） - **后端网关**：默认开发代理到 `http://localhost:8080`（可在 `vite.config.ts` 修改） --- ## 快速开始 ```bash npm install npm run dev ``` 浏览器访问开发服务器（默认 `http://localhost:3000`，具体以终端输出为准）。 ```bash npm run build # 生产构建 npm run preview # 本地预览构建结果 npm run lint # ESLint（当前脚本指向 App.vue，可按需扩展） npm run prettier # Prettier 格式化 src ``` --- ## 环境变量 | 变量 | 说明 | |------|------| | `VITE_APP_BASE_URL` | 接口根地址。**开发**建议留空，走 Vite 代理，避免跨域；**生产**填网关完整地址（如 `http://localhost:8080`）。 | | `VITE_PERMISSION_ROOT_ID` | 调用 `getUserPermissionList` 时请求体中的菜单树根节点 **id**，默认 `1`。 | 对应文件：`.env.development`、`.env.production`。 --- ## 开发代理与跨域 `vite.config.ts` 中 `server.proxy` 将以下前缀转发到网关（默认 `8080`）： - `/auth` - `/system` - `/member` 开发环境下 `VITE_APP_BASE_URL` 为空时，请求发到当前 Vite 端口，由代理转发，避免浏览器直连网关触发 CORS。 --- ## 鉴权与请求约定 - **Token**：登录成功后写入本地缓存；请求头 **`token`** 由拦截器自动带上（见 `request.ts`）。 - **响应**：兼容常见 `Result` 形态（如 `message` / `msg`、业务 `data`）。 - **登录**：`/auth/sso/login`（`src/api/user.ts`），与网关路由对齐。 --- ## 路由与菜单 ### 静态路由 - 根布局 **`/`** → 重定向 **`/workbench`**（工作台）。 - 固定业务子路由：如 `/permission/*/edit`、`/organize/department/edit`、登录页、404 等（见 `src/router/index.ts`）。 ### 动态路由 1. 登录后 `permission` 守卫拉取用户信息，再请求 **`/system/permission/getUserPermissionList`**（请求体含 `userId` 与树根 **`id`**，来自 `VITE_PERMISSION_ROOT_ID` / `src/config/permission.ts`）。 2. `permissionAdapter` 将后端 **PermissionDto**（`sonList`）转为旧版菜单结构；**`type === 9`** 视为按钮，**不参与侧栏**，但仍参与 **`collectPermissionCodes`** 供 `v-perm` 等使用。 3. `filterAsyncRoutes` + `createRouteRecord`（`src/core/lib/router.ts`）生成 `vue-router` 记录；**菜单类型**：`0` 目录、`1` 菜单、其余为按钮（侧栏已过滤 `type=9`）。 4. **页面组件**：菜单上的 **`component`** 需对应 `src/views/**/*.vue` 路径；`loadRouteView` 按路径匹配组件，未命中时使用 **`src/views/system/common/dynamic-placeholder.vue`** 占位。 侧栏点击使用 **`sub-menu`** 中的路径拼接规则，与路由注册的嵌套 **`path`** 保持一致。 --- ## 目录结构（摘要） ``` src/ api/ # 接口封装（user、auth、dict、log、member、organize 等） components/ # 通用组件（如 admin-page、pagination、popup） config/ # 应用配置、权限树根、主题预设等 core/ # 路由生成、权限适配、hooks、指令 layout/ # 整体布局、侧栏、顶栏 permission.ts # 全局路由守卫（登录态、动态路由注册） plugins/ # Element Plus 等 router/ # 静态路由表 store/ # Vuex 模块（user、permission、app） styles/ # 全局样式与 SCSS 变量 utils/ # 请求封装、主题应用、缓存等 views/ # 页面视图（含 system、permission、organize、member 等） ``` --- ## 主题 顶栏支持多套 **主色** 预设（写入 `document.documentElement` 的 CSS 变量及侧栏高亮变量），选择保存在 **`localStorage`**（键名见 `src/config/theme.ts`）。启动时在 `main.ts` 中调用 **`initTheme()`** 恢复上次选择。 --- ## 与后端对齐检查清单 - [ ] 网关地址、端口与 `vite.config.ts` 代理、`VITE_APP_BASE_URL` 一致 - [ ] `getUserPermissionList` 的树根 **`id`** 与 `VITE_PERMISSION_ROOT_ID` 一致 - [ ] 菜单 **`path` / `component`** 与 `src/views` 下实际文件一致，避免动态页 404 - [ ] 按钮权限 **`type`** 与前端过滤逻辑一致（当前侧栏过滤 **`type === 9`**；若后端使用其它值，需改 `permissionAdapter.ts` 中 **`isButtonType`**） --- ## 常见问题 **登录成功但白屏或 404** - 确认动态路由已注册且 URL 与菜单 **path** 一致。 - 确认 **`component`** 能在 `src/views` 中解析到对应 `.vue` 文件。 **接口跨域失败** - 开发环境优先使用 **空 `VITE_APP_BASE_URL` + Vite 代理**；若改为直连网关，需在网关配置 **CORS** 允许前端来源。 --- ## 许可证 以项目仓库或组织约定为准（本 README 未指定 SPDX 标识时，请补充 `LICENSE` 文件）。