# role-admin 门店员工权限管理后台，基于 `pure-admin-thin` 精简模板二次开发。当前业务聚焦门店、角色、员工三类基础数据管理，并通过 Vite 代理对接本地 `access-manage` 后端服务。 ## 技术栈 - `Vue 3` + `TypeScript` - `Vite` - `Element Plus` - `Pinia` - `Vue Router` - `Axios` - `@pureadmin/table` / `@pureadmin/utils` ## 环境要求 - `Node.js`: `^20.19.0 || >=22.13.0` - `pnpm`: `>=9` - 本地后端：`/Users/mac033/Desktop/my-project/access-manage` ## 本地启动 先启动后端项目： ```bash cd /Users/mac033/Desktop/my-project/access-manage pnpm mysql:up pnpm db:migrate pnpm dev ``` 再启动后台： ```bash cd /Users/mac033/Desktop/my-project/role-admin pnpm install pnpm dev ``` 访问地址： ```text http://localhost:8848/ ``` ## 目录说明 ```text . ├── .codex/skills/ # 仓库内协作 skill，约束结构变更后同步 README ├── .husky/ # Git hooks，提交前执行 lint-staged，提交信息走 commitlint ├── .vscode/ # VS Code 推荐配置与 Vue 代码片段 ├── build/ # Vite 插件、CDN、压缩、构建信息与工具函数 ├── docs/ # 项目需求和后台扩展说明 │ └── C_APP_ADMIN_REQUIREMENTS.md # C 端正式版管理后台需求文档 ├── public/ # 静态资源与运行时平台配置 ├── src/ # 前端源码 │ ├── api/ # HTTP API 封装，业务接口集中在 access.ts │ ├── assets/ # 图片、SVG、iconfont 等静态资源 │ ├── components/ # 模板沉淀的通用组件 │ ├── config/ # 读取 public/platform-config.json 的运行时配置 │ ├── directives/ # 自定义指令，如权限、复制、长按、波纹 │ ├── layout/ # 后台布局、菜单、标签页、导航栏与布局 hooks │ ├── plugins/ # Element Plus、ECharts 等插件注册入口 │ ├── router/ # 静态路由、剩余路由、路由实例与守卫 │ ├── store/ # Pinia store，含用户、权限、标签页、主题等模块 │ ├── style/ # 全局样式、主题、暗色模式、侧边栏和过渡样式 │ ├── utils/ # 鉴权、HTTP、缓存、消息、进度条、树处理等工具 │ └── views/ # 页面视图，当前业务页在 employees、roles、stores、permissions 和员工工作台运营模块 ├── types/ # 全局类型声明、组件声明、路由声明和 Vue shim ├── AGENTS.md # Codex/Agent 入口规则，转到 RTK.md ├── RTK.md # 本仓库协作规则与 README 同步要求 ├── Dockerfile # 容器构建入口 ├── package.json # 依赖、脚本、engines 与 pnpm preinstall 限制 ├── pnpm-lock.yaml # pnpm 锁文件 ├── tsconfig.json # TypeScript 编译配置 └── vite.config.ts # Vite 开发代理、插件、构建输出配置 ``` > 当前仓库不是 monorepo，没有 `packages/` 目录；重要脚本集中在 `package.json` 的 `scripts` 字段。 ## 重要脚本 | 脚本 | 作用 | 使用场景 | | --------------------- | ----------------------------------------------------------------------- | -------------------- | | `pnpm dev` | 启动 Vite 开发服务，默认端口来自 `.env.development` 的 `VITE_PORT=8848` | 本地开发 | | `pnpm serve` | `pnpm dev` 的别名 | 兼容习惯命令 | | `pnpm build` | 清理 `dist` 后执行生产构建，内存上限设为 8192MB | 发布前打包 | | `pnpm build:staging` | 使用 `staging` mode 构建 | 预发布环境验证 | | `pnpm report` | 构建并打开 Rollup 可视化分析报告 | 分析包体积 | | `pnpm preview` | 预览已有 `dist` 构建产物 | 构建后本地验收 | | `pnpm preview:build` | 先构建再预览 | 一步完成打包验收 | | `pnpm typecheck` | 执行 `tsc --noEmit` 和 `vue-tsc --noEmit --skipLibCheck` | 类型检查 | | `pnpm lint` | 依次执行 ESLint、Prettier、Stylelint 自动修复 | 提交前整理代码 | | `pnpm lint:eslint` | 对 `src`、`build` 下 JS/TS/Vue 做 ESLint 修复 | 脚本或逻辑代码调整后 | | `pnpm lint:prettier` | 格式化 `src` 下常见源码与文档格式 | 样式统一 | | `pnpm lint:stylelint` | 修复 HTML/Vue/CSS/SCSS 样式规则 | 样式文件调整后 | | `pnpm svgo` | 递归压缩 SVG | SVG 资源变更后 | | `pnpm clean:cache` | 删除缓存、锁文件、依赖并重新安装 | 依赖状态异常时 | ## 业务模块 - `src/views/stores/index.vue`: 门店管理，筛选、重置、启停、删除后都会重新调用接口，支持新增、编辑、详情员工列表和移除员工。 - `src/views/roles/index.vue`: 角色管理，搜索、重置、删除和保存后都会重新调用接口，支持角色编码校验。 - `src/views/employees/index.vue`: 员工管理，门店/状态/关键词筛选、重置、分页、启停、临时密码重置、删除和保存后都会重新调用接口，并展示员工状态标签；重置成功后只在弹窗内显示一次性临时密码。 - `src/views/permissions/index.vue`: 权限策略，支持查看角色权限、按角色勾选权限点并保存到后端。 - `src/views/announcements/index.vue`: 公告管理，支持状态/级别/关键词筛选、分页、新建、编辑、保存草稿、发布和归档。 - `src/views/tasks/index.vue`: 任务管理，支持门店/员工/状态/优先级/关键词筛选、分页、新建、编辑、取消任务和流转记录展示。 - `src/views/shifts/index.vue`: 排班管理，支持门店/员工/日期范围筛选、分页、新增、编辑和取消排班，选择门店后刷新员工选项。 - `src/views/credential-audits/index.vue`: 凭据审计，展示操作者、目标员工、动作、时间、IP、User-Agent 和原因，支持操作者/目标员工/门店/时间筛选。 - `src/api/access.ts`: 门店、角色、员工、权限策略、员工工作台运营和角色权限分配接口类型与 HTTP 方法封装，并集中完成运营模块正式后端字段适配。 - `src/api/user.ts`: 登录、当前用户和当前权限菜单接口封装。 - `src/router/modules/employees.ts`: 权限管理和员工工作台运营菜单入口，挂载门店、角色、员工、权限策略、公告、任务、排班和凭据审计页面。 - `src/store/modules/user.ts`: 保存 JWT 登录态、当前用户、权限码和后端菜单动作权限。 - `docs/C_APP_ADMIN_REQUIREMENTS.md`: C 端正式版管理后台需求文档，定义公告、任务、排班、密码重置和凭据审计等新增后台能力。 ## 后端对接 开发环境通过 Vite 代理把 `/api` 转发到 `VITE_API_PROXY_TARGET`，默认值为 `http://localhost:3500`。相关配置位于： - `.env.development` - `vite.config.ts` 当前已对接接口： - `POST /api/auth/admin/login` - `GET /api/auth/me` - `GET /api/permissions/me` - `GET /api/permissions/policies` - `GET /api/stores`，门店管理列表会携带 `page`、`pageSize`，筛选时会携带 `status`、`keyword` - `GET /api/stores/:id` - `POST /api/stores` - `PATCH /api/stores/:id` - `DELETE /api/stores/:storeId/employees/:employeeId` - `DELETE /api/stores/:id` - `GET /api/roles`，角色管理列表会携带 `page`、`pageSize`，筛选时会携带 `keyword`、`isSystem` - `GET /api/roles/:id` - `POST /api/roles` - `PATCH /api/roles/:id` - `DELETE /api/roles/:id` - `GET /api/employees`，列表会携带 `page`、`pageSize`，筛选时会携带 `storeId`、`status`、`keyword` - `GET /api/employees/:id` - `POST /api/employees` - `PATCH /api/employees/:id` - `PATCH /api/employees/:id/status` - `PATCH /api/employees/:id/password` - `POST /api/admin/employees/:id/password/reset`，需要 `credential:reset`，请求体携带重置原因，响应只返回一次性临时密码 - `DELETE /api/employees/:id` - `GET /api/admin/announcements`，公告管理列表会携带 `page`、`pageSize`，筛选时会把页面 `importance` 转为后端 `level`，并携带 `status`、`keyword` - `POST /api/admin/announcements`，页面 `importance`、`targetScope` 和目标 ID 数组会转为后端 `level`、`targetType`、`targets` - `PATCH /api/admin/announcements/:id`，使用同一套公告字段转换 - `POST /api/admin/announcements/:id/publish` - `POST /api/admin/announcements/:id/archive` - `GET /api/admin/tasks`，任务管理列表会携带 `page`、`pageSize`，筛选时会携带 `storeId`、`employeeId`、`status`、`priority`、`keyword`，并统一使用后端 `CANCELLED` - `POST /api/admin/tasks`，页面 `deadlineAt` 会转为后端 `dueAt`，后端 `assignees` 会回填为页面 `assigneeIds`、`assigneeNames` - `PATCH /api/admin/tasks/:id`，使用同一套任务字段转换 - `POST /api/admin/tasks/:id/cancel` - `GET /api/admin/shifts`，排班管理列表会携带 `page`、`pageSize`，筛选时会携带 `storeId`、`employeeId`、`startDate`、`endDate` - `POST /api/admin/shifts`，页面 `position` 会转为后端 `roleName` - `PATCH /api/admin/shifts/:id`，使用同一套排班字段转换 - `DELETE /api/admin/shifts/:id` - `GET /api/admin/credential-audits`，凭据审计列表会携带 `page`、`pageSize`，筛选时会携带 `operatorId`、`targetEmployeeId`、`storeId`、`startDate`、`endDate`，并把后端 `actorName`、`createdAt` 转为页面 `operatorName`、`operatedAt` 接口响应统一在 `src/api/access.ts` 中使用 `ApiResult` 或 `PaginatedData` 描述，页面层只消费 `result.data`，避免在视图里重复拼接接口路径。门店、角色、员工、公告、任务、排班和凭据审计列表的搜索、重置、分页和状态变更后的刷新都应通过接口层完成，不直接依赖页面内存里的旧列表。公告、任务、排班和凭据审计的后端正式字段统一在接口层转换，页面继续使用 `importance`、`targetScope`、`deadlineAt`、`assigneeIds`、`assigneeNames`、`position`、`operatorName`、`operatedAt` 等展示和表单字段。员工对象会消费后端返回的 `statusTags`；所属门店停用时展示“门店被禁用”标签。 ## 登录与鉴权流程 1. 登录页调用 `POST /api/auth/admin/login`，支持超级管理员用户名和具备后台权限的员工手机号。 2. 前端保存后端返回的 `data.token`，并按 `expiresIn` 换算本地过期时间。 3. 登录成功后立即调用 `GET /api/auth/me` 校验当前账号，再调用 `GET /api/permissions/me` 获取权限码、菜单和动作权限。 4. 路由守卫会在刷新页面后重新拉取当前用户和权限，未登录或 token 过期会跳回 `/login`。 5. 菜单按路由 `meta.menuKey`、`meta.permission` 与 `/api/permissions/me` 返回的后端菜单过滤；按钮按后端菜单 `actions` 和对应权限码控制新增、编辑、启停、删除、运营管理和凭据重置显隐。 6. 凭据安全不提供查看当前明文密码入口；后台只调用 `POST /api/admin/employees/:id/password/reset` 生成一次性临时密码，前端不写入本地存储、日志或 URL，弹窗关闭后立即清空。 7. 后端当前没有 refresh-token 接口，收到 `401` 或本地 token 过期时直接清理登录态并要求重新登录。 ## 配置说明 - `.env`: 全局默认配置，目前包含端口和是否隐藏首页。 - `.env.development`: 开发环境端口、路由模式、API 代理目标。 - `.env.staging`: 预发布构建配置，可开启 CDN。 - `.env.production`: 生产构建配置。 - `public/platform-config.json`: pure-admin 运行时平台配置，例如标题、布局、主题、标签页和菜单搜索历史。 ## 协作与文档同步 - 文件结构、入口文件、业务模块、脚本或关键配置发生变化时，必须同步更新本 README 的「目录说明」「重要脚本」或对应说明段落。 - 仓库内提供 `.codex/skills/readme-structure-sync/SKILL.md`，用于提醒 Agent 在结构变更后维护 README。 - `AGENTS.md` 指向 `RTK.md`，后续 Codex/Agent 进入仓库时应先遵守其中的协作规则。 - 注释优先解释业务边界、接口契约、路由挂载、状态流转和容易误改的模板机制；不要给显而易见的语句堆叠无价值注释。 ## 验证命令 ```bash pnpm typecheck pnpm build ```