docs: 完善项目说明和协作规则

.codex/skills/readme-structure-sync/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: readme-structure-sync
+description: Use this skill when changing files, folders, package scripts, routes, API modules, or project conventions in role-admin; it ensures README.md stays synchronized with the current repository structure.
+---
+
+# README Structure Sync
+
+Use this skill whenever a task changes repository structure, important entry files, package scripts, routes, API modules, environment variables, or collaboration conventions.
+
+## Workflow
+
+1. Inspect the touched files and decide whether they affect `README.md`.
+2. If directories or key files were added, removed, renamed, or moved, update the `README.md` directory map.
+3. If `package.json` scripts changed, update the `README.md` important scripts table.
+4. If business modules, API contracts, routes, or environment variables changed, update the matching README section.
+5. Keep README descriptions short and operational: what the file or directory does, not a generic framework explanation.
+
+## Touch-Up Rule
+
+Do not scan the whole repository only for this skill. When a task already touches applicable files, fix obvious README drift in the same pass. If full cleanup is larger than the request, update the current workflow and top-level declarations, then call out the remaining gap.

AGENTS.md

@@ -0,0 +1 @@
+@RTK.md

README.en-US.md

@@ -1,39 +1,106 @@
-<h1>vue-pure-admin Lite Edition（no i18n version）</h1>
+# role-admin
-
-[![license](https://img.shields.io/github/license/pure-admin/vue-pure-admin.svg)](LICENSE)
 
 **English** | [中文](./README.md)
 
-## Introduce
+Store employee access-management admin UI, based on the `pure-admin-thin` template and customized for store, role, and employee CRUD workflows.
 
-The simplified version is based on the shelf extracted from [vue-pure-admin](https://github.com/pure-admin/vue-pure-admin), which contains main functions and is more suitable for actual project development. The packaged size is introduced globally [element-plus](https://element-plus.org) is still below `2.3MB`, and the full version of the code will be permanently synchronized. After enabling `brotli` compression and `cdn` to replace the local library mode, the package size is less than `350kb`
+## Stack
 
-## Supporting video
+- `Vue 3` + `TypeScript`
+- `Vite`
+- `Element Plus`
+- `Pinia`
+- `Vue Router`
+- `Axios`
 
-[Click me to view UI design](https://www.bilibili.com/video/BV17g411T7rq)  
+## Requirements
-[Click me to view the rapid development tutorial](https://www.bilibili.com/video/BV1kg411v7QT)
 
-## Nanny-level documents
+- `Node.js`: `^20.19.0 || >=22.13.0`
+- `pnpm`: `>=9`
+- Local backend: `/Users/mac033/Desktop/my-project/access-manage`
 
-[Click me to view vue-pure-admin documentation](https://pure-admin.cn/)  
+## Local Development
-[Click me to view @pureadmin/utils documentation](https://pure-admin-utils.netlify.app)
 
-## Premium service
+Start the backend first:
 
-[Click me to view details](https://pure-admin.cn/pages/service/)
+```bash
+cd /Users/mac033/Desktop/my-project/access-manage
+pnpm mysql:up
+pnpm db:migrate
+pnpm dev
+```
 
-## Preview
+Then start this admin UI:
 
-[Click me to view the preview station](https://pure-admin-thin.netlify.app/#/login)
+```bash
+cd /Users/mac033/Desktop/my-project/role-admin
+pnpm install
+pnpm dev
+```
 
-## Maintainer
+Open:
 
-[xiaoxian521](https://github.com/xiaoxian521)
+```text
+http://localhost:8848/
+```
 
-## ⚠️ Attention
+## Project Structure
 
-The Lite version does not accept any issues and prs. If you have any questions, please go to the full version [issues](https://github.com/pure-admin/vue-pure-admin/issues/new/choose) to mention, thank you!
+```text
+.
+├── .codex/skills/           # Repository-local skill for keeping README.md in sync
+├── .husky/                  # Git hooks for lint-staged and commitlint
+├── build/                   # Vite plugin, CDN, compression, and build helpers
+├── mock/                    # Template mock data for login and async routes
+├── public/                  # Static assets and runtime platform config
+├── src/
+│   ├── api/                 # HTTP API wrappers; business APIs live in access.ts
+│   ├── assets/              # Images, SVG files, and iconfont assets
+│   ├── components/          # Shared template components
+│   ├── config/              # Runtime config loader
+│   ├── directives/          # Custom Vue directives
+│   ├── layout/              # Admin layout, menu, tabs, navbar, and hooks
+│   ├── plugins/             # Plugin registration
+│   ├── router/              # Static routes, remaining routes, router instance, guards
+│   ├── store/               # Pinia stores
+│   ├── style/               # Global styles and themes
+│   ├── utils/               # Auth, HTTP, storage, message, progress, and tree helpers
+│   └── views/               # Pages; business pages live in employees, roles, stores
+├── types/                   # Global TypeScript declarations
+├── AGENTS.md                # Agent entrypoint that delegates to RTK.md
+├── RTK.md                   # Repository collaboration rules
+├── package.json             # Dependencies, scripts, engines, and pnpm guard
+└── vite.config.ts           # Vite dev proxy, plugins, and build output config
+```
 
-## License
+This repository is not a monorepo and has no `packages/` directory. Important scripts are defined in `package.json`.
 
-[MIT © 2020-present, pure-admin](./LICENSE)
+## Important Scripts
+
+| Script               | Purpose                                            |
+| -------------------- | -------------------------------------------------- |
+| `pnpm dev`           | Start the Vite dev server on the configured port   |
+| `pnpm build`         | Clean `dist` and build for production              |
+| `pnpm build:staging` | Build with staging mode                            |
+| `pnpm report`        | Build and open a Rollup visualizer report          |
+| `pnpm preview`       | Preview an existing `dist` build                   |
+| `pnpm preview:build` | Build first, then preview                          |
+| `pnpm typecheck`     | Run TypeScript and Vue type checks                 |
+| `pnpm lint`          | Run ESLint, Prettier, and Stylelint fixes          |
+| `pnpm svgo`          | Compress SVG files recursively                     |
+| `pnpm clean:cache`   | Reinstall dependencies after clearing local caches |
+
+## Backend Proxy
+
+Development mode proxies `/api` to `VITE_API_PROXY_TARGET`, defaulting to `http://localhost:3500`. The relevant files are `.env.development` and `vite.config.ts`.
+
+## Documentation Sync Rule
+
+When files, folders, package scripts, API modules, route modules, or key config files change, update `README.md` in the same change. The local skill is stored at `.codex/skills/readme-structure-sync/SKILL.md`.
+
+## Verification
+
+```bash
+pnpm typecheck
+pnpm build
+```

README.md

@@ -1,16 +1,22 @@
 # role-admin
 
-门店员工权限管理后台，基于 `pure-admin-thin` 精简模板二次开发。
+门店员工权限管理后台，基于 `pure-admin-thin` 精简模板二次开发。当前业务聚焦门店、角色、员工三类基础数据管理，并通过 Vite 代理对接本地 `access-manage` 后端服务。
 
 ## 技术栈
 
-- Vue 3
+- `Vue 3` + `TypeScript`
-- Vite
+- `Vite`
-- TypeScript
+- `Element Plus`
-- Element Plus
+- `Pinia`
-- Pinia
+- `Vue Router`
-- Vue Router
+- `Axios`
-- Axios
+- `@pureadmin/table` / `@pureadmin/utils`
+
+## 环境要求
+
+- `Node.js`: `^20.19.0 || >=22.13.0`
+- `pnpm`: `>=9`
+- 本地后端：`/Users/mac033/Desktop/my-project/access-manage`
 
 ## 本地启动
 
@@ -37,9 +43,71 @@ pnpm dev
 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` 转发到 `http://localhost:3500`，配置位于：
+开发环境通过 Vite 代理把 `/api` 转发到 `VITE_API_PROXY_TARGET`，默认值为 `http://localhost:3500`。相关配置位于：
 
 - `.env.development`
 - `vite.config.ts`
@@ -63,6 +131,23 @@ http://localhost:8848/
 - `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

RTK.md

@@ -0,0 +1,20 @@
+# role-admin 协作规则
+
+## 基本约定
+
+- 使用 `pnpm`，不要引入 `npm`、`yarn` 或 `bun` 锁文件。
+- 业务接口统一放在 `src/api/access.ts`，页面层不要直接拼接后端 URL。
+- 权限管理菜单集中在 `src/router/modules/employees.ts`，默认标签页入口集中在 `src/layout/types.ts`。
+- 页面注释只解释业务边界、接口契约、状态流转和容易误改的模板机制，不做机械逐行注释。
+
+## README 同步要求
+
+- 只要新增、删除、移动目录或关键入口文件，就必须同步更新 `README.md` 的「目录说明」。
+- 只要新增、删除、重命名 `package.json` 中的关键脚本，就必须同步更新 `README.md` 的「重要脚本」。
+- 只要新增业务模块、接口模块、路由模块或环境配置，就必须同步更新 `README.md` 的对应说明。
+- 如果一次任务只触达局部文件，也要至少补齐当前任务相关的 README 内容；大范围遗留问题需要在交付说明里明确。
+
+## 验证
+
+- 文档或注释改动至少执行 `pnpm typecheck`。
+- 涉及源码、路由、构建配置或依赖脚本时，同时执行 `pnpm build`。

src/api/access.ts

@@ -1,10 +1,18 @@
 import { http } from "@/utils/http";
 
+/**
+ * 门店权限后台的业务接口层。
+ *
+ * 页面只依赖这里导出的类型和方法，避免在视图组件中散落接口路径、
+ * 响应结构和状态枚举。后端统一挂在 `/api` 前缀下，由 Vite 代理转发。
+ */
 const API_PREFIX = "/api";
 
+/** 后端员工与门店共用的启停状态枚举。 */
 export type EmployeeStatus = "ACTIVE" | "INACTIVE";
 export type StoreStatus = "ACTIVE" | "INACTIVE";
 
+/** 员工列表中展示的角色摘要。 */
 export interface RoleSummary {
   id: number;
   code: string;
@@ -49,6 +57,7 @@ export interface Role extends RoleOption {
   updatedAt: string;
 }
 
+/** 员工列表是服务端分页，门店和角色当前由前端做轻量筛选。 */
 export interface EmployeeListParams {
   storeId?: number;
   status?: EmployeeStatus;
@@ -83,6 +92,7 @@ export interface EmployeePayload {
   roleIds: number[];
 }
 
+/** access-manage 后端普通响应包裹结构。 */
 export interface ApiResult<T> {
   success: boolean;
   data: T;
@@ -100,6 +110,7 @@ export interface PaginatedData<T> {
   pagination: Pagination;
 }
 
+/** 门店接口：管理门店基础资料，并给员工下拉选项提供数据源。 */
 export const listStores = (params?: StoreListParams) => {
   return http.request<ApiResult<Store[]>>("get", `${API_PREFIX}/stores`, {
     params
@@ -130,6 +141,7 @@ export const deleteStore = (id: number) => {
   return http.request<void>("delete", `${API_PREFIX}/stores/${id}`);
 };
 
+/** 角色接口：维护员工可绑定的权限角色。 */
 export const getRole = (id: number) => {
   return http.request<ApiResult<Role>>("get", `${API_PREFIX}/roles/${id}`);
 };
@@ -150,6 +162,7 @@ export const deleteRole = (id: number) => {
   return http.request<void>("delete", `${API_PREFIX}/roles/${id}`);
 };
 
+/** 员工接口：员工列表由后端分页，编辑时按 id 重新拉取完整角色绑定。 */
 export const listEmployees = (params: EmployeeListParams) => {
   return http.request<ApiResult<PaginatedData<Employee>>>(
     "get",

src/layout/types.ts

@@ -1,5 +1,11 @@
 import type { FunctionalComponent } from "vue";
 
+/**
+ * 登录后默认打开的标签页。
+ *
+ * 这里要和 `src/router/modules/employees.ts` 的业务页面保持一致，
+ * 否则登出重置标签页或首次进入后台时会出现空标签/错入口。
+ */
 export const routerArrays: Array<RouteConfigs> = [
   {
     path: "/stores",

src/router/modules/employees.ts

@@ -1,5 +1,11 @@
 const Layout = () => import("@/layout/index.vue");
 
+/**
+ * 权限管理业务菜单。
+ *
+ * 三个子页面都是静态路由，菜单展示顺序由这里的 children 决定；
+ * 默认访问该模块时进入员工管理，保证和登录/登出后的主工作流一致。
+ */
 export default {
   path: "/access",
   name: "AccessManagement",

src/router/modules/home.ts

@@ -1,5 +1,11 @@
 const Layout = () => import("@/layout/index.vue");
 
+/**
+ * pure-admin 模板要求保留 Home 根路由。
+ *
+ * 当前业务首页是员工管理，所以根路径直接重定向到 `/employees`；
+ * `/welcome` 只作为隐藏工作台占位页保留。
+ */
 export default {
   path: "/",
   name: "Home",

src/views/employees/index.vue

@@ -34,10 +34,12 @@ defineOptions({
   name: "EmployeeManagement"
 });
 
+/** 表单状态复用后端员工 payload，id 用来切换创建/更新接口。 */
 type EmployeeFormState = EmployeePayload & {
   id?: number;
 };
 
+/** 员工手机号按中国大陆手机号做前端第一层校验，最终唯一性仍由后端保证。 */
 const phonePattern = /^1[3-9]\d{9}$/;
 const tableLoading = ref(false);
 const catalogLoading = ref(false);
@@ -56,6 +58,7 @@ const query = reactive({
   pageSize: 20
 });
 
+/** 员工列表由后端分页，这里只保存当前查询返回的分页摘要。 */
 const pagination = reactive({
   total: 0,
   totalPages: 0
@@ -130,6 +133,7 @@ function resetFormState() {
   formRef.value?.clearValidate();
 }
 
+/** 清理提交数据，避免把仅包含空格的备注写入后端。 */
 function buildPayload(): EmployeePayload {
   return {
     storeId: form.storeId,
@@ -141,6 +145,7 @@ function buildPayload(): EmployeePayload {
   };
 }
 
+/** 门店和角色是员工表单的基础字典，打开弹窗前必须先加载。 */
 async function fetchCatalog() {
   catalogLoading.value = true;
   try {
@@ -157,6 +162,7 @@ async function fetchCatalog() {
   }
 }
 
+/** 员工列表筛选、分页都交给后端，前端只传递当前查询条件。 */
 async function fetchEmployees() {
   tableLoading.value = true;
   try {
@@ -207,6 +213,7 @@ function openCreateDialog() {
   dialogVisible.value = true;
 }
 
+/** 编辑前重新拉详情，确保角色绑定不是来自列表摘要的过期数据。 */
 async function openEditDialog(row: Employee) {
   try {
     const result = await getEmployee(row.id);

src/views/roles/index.vue

@@ -25,10 +25,12 @@ defineOptions({
   name: "RoleManagement"
 });
 
+/** 表单状态与角色 payload 对齐，id 只在编辑已有角色时存在。 */
 type RoleFormState = RolePayload & {
   id?: number;
 };
 
+/** 角色编码用于权限判断，限制为稳定的小写标识，避免展示名变更影响授权逻辑。 */
 const codePattern = /^[a-z][a-z0-9_]*$/;
 const tableLoading = ref(false);
 const submitLoading = ref(false);
@@ -65,6 +67,7 @@ const rules: FormRules<RoleFormState> = {
   ]
 };
 
+/** 角色列表当前不分页，搜索在前端完成，降低简单维护场景的交互成本。 */
 const filteredRoles = computed(() => {
   const keyword = query.keyword.trim().toLowerCase();
 
@@ -119,6 +122,7 @@ function resetFormState() {
   formRef.value?.clearValidate();
 }
 
+/** 空说明统一转为 null，和后端可选字段语义保持一致。 */
 function buildPayload(): RolePayload {
   const description = form.description?.trim();
 
@@ -129,6 +133,7 @@ function buildPayload(): RolePayload {
   };
 }
 
+/** 角色是员工绑定的基础字典，页面加载和保存后都需要刷新。 */
 async function fetchRoles() {
   tableLoading.value = true;
   try {

src/views/stores/index.vue

@@ -28,6 +28,7 @@ defineOptions({
   name: "StoreManagement"
 });
 
+/** 表单状态与后端 payload 基本一致，额外用 id 区分新增和编辑。 */
 type StoreFormState = StorePayload & {
   id?: number;
 };
@@ -62,6 +63,7 @@ const rules: FormRules<StoreFormState> = {
   status: [{ required: true, message: "请选择门店状态", trigger: "change" }]
 };
 
+/** 门店数据量预计较小，列表一次性拉取后在前端做状态和关键词筛选。 */
 const filteredStores = computed(() => {
   const keyword = query.keyword.trim().toLowerCase();
 
@@ -117,6 +119,7 @@ function resetFormState() {
   formRef.value?.clearValidate();
 }
 
+/** 提交前统一清理空字符串，保持后端收到的是 null 而不是空值。 */
 function buildPayload(): StorePayload {
   const address = form.address?.trim();
   const phone = form.phone?.trim();
@@ -129,6 +132,7 @@ function buildPayload(): StorePayload {
   };
 }
 
+/** 拉取包含停用门店的完整列表，便于后台直接做启停管理。 */
 async function fetchStores() {
   tableLoading.value = true;
   try {