# role-admin

**English** | [中文](./README.md)

Store employee access-management admin UI, based on the `pure-admin-thin` template and customized for store, role, and employee CRUD workflows.

## Stack

- `Vue 3` + `TypeScript`
- `Vite`
- `Element Plus`
- `Pinia`
- `Vue Router`
- `Axios`

## Requirements

- `Node.js`: `^20.19.0 || >=22.13.0`
- `pnpm`: `>=9`
- Local backend: `/Users/mac033/Desktop/my-project/access-manage`

## Local Development

Start the backend first:

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

Then start this admin UI:

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

Open:

```text
http://localhost:8848/
```

## Project Structure

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

This repository is not a monorepo and has no `packages/` directory. Important scripts are defined in `package.json`.

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