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

197 lines
13 KiB
Markdown
Raw Permalink 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`
## 本地启动
先启动后端项目：
```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<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 进入仓库时应先遵守其中的协作规则。
- 注释优先解释业务边界、接口契约、路由挂载、状态流转和容易误改的模板机制；不要给显而易见的语句堆叠无价值注释。
## 验证命令
```bash
pnpm typecheck
pnpm build
```
Reference in New Issue View Git Blame Copy Permalink