my-project/role-admin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
ab73565d37447b87927d8a00b2afdc29c29fad7d
role-admin/README.md
T
湛兮 ab73565d37 feat: add employee workspace operations admin
2026-06-02 14:23:31 +08:00

13 KiB
Raw Blame History

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

本地启动

先启动后端项目：

cd /Users/mac033/Desktop/my-project/access-manage
pnpm mysql:up
pnpm db:migrate
pnpm dev

再启动后台：

cd /Users/mac033/Desktop/my-project/role-admin
pnpm install
pnpm dev

访问地址：

http://localhost:8848/

目录说明

.
├── .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<T> 或 PaginatedData<T> 描述，页面层只消费 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 进入仓库时应先遵守其中的协作规则。
  • 注释优先解释业务边界、接口契约、路由挂载、状态流转和容易误改的模板机制；不要给显而易见的语句堆叠无价值注释。

验证命令

pnpm typecheck
pnpm build
Reference in New Issue View Git Blame Copy Permalink