role-admin/README.md

# 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、压缩、构建信息与工具函数
├── mock/                    # pure-admin 模板保留的 mock 登录/路由数据
├── 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
├── 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`、`mock`、`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/api/access.ts`: 门店、角色、员工接口类型与 HTTP 方法封装。
- `src/router/modules/employees.ts`: 权限管理菜单入口，挂载门店、角色、员工三个页面。

## 后端对接

开发环境通过 Vite 代理把 `/api` 转发到 `VITE_API_PROXY_TARGET`，默认值为 `http://localhost:3500`。相关配置位于：

- `.env.development`
- `vite.config.ts`

当前已对接接口：

- `GET /api/stores`
- `GET /api/stores/:id`
- `POST /api/stores`
- `PATCH /api/stores/:id`
- `DELETE /api/stores/:id`
- `GET /api/roles`
- `GET /api/roles/:id`
- `POST /api/roles`
- `PATCH /api/roles/:id`
- `DELETE /api/roles/:id`
- `GET /api/employees`
- `GET /api/employees/:id`
- `POST /api/employees`
- `PATCH /api/employees/:id`
- `PATCH /api/employees/:id/status`
- `DELETE /api/employees/:id`

接口响应统一在 `src/api/access.ts` 中使用 `ApiResult<T>` 或 `PaginatedData<T>` 描述，页面层只消费 `result.data`，避免在视图里重复拼接接口路径。

## 配置说明

- `.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
```