# vbenadmin

**Repository Path**: ejiaxiu/vbenadmin

## Basic Information

- **Project Name**: vbenadmin
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastDev Admin — Frontend

Vue 3 + TypeScript + Vite + Element Plus admin SPA. Talks to the ThinkPHP 8 backend under `../backend/`.

> **Scaffold flavor**: thin, hand-rolled Vite + Vue 3 project with Vben-style conventions (`src/api/`, `src/store/modules/`, `src/router/routes/`, `src/directives/`, `src/layouts/`). We deliberately did **not** start from the upstream `vue-vben-admin` monorepo — fewer files to delete, full control over what ships.

## Tech stack

- **Framework**: Vue 3.5 + `<script setup>` + TypeScript (strict)
- **Build**: Vite 8
- **Router**: Vue Router 4 with static + dynamic routes built from `/auth/me`
- **State**: Pinia
- **UI**: Element Plus 2.x (auto-imported by `unplugin-vue-components`)
- **HTTP**: axios with single-flight 401 → refresh interceptor
- **i18n**: vue-i18n (single `zh-CN` locale in v1)
- **Tests**: Vitest + @vue/test-utils + jsdom

## Prerequisites

- Node.js **20+** (tested with 22)
- pnpm **9+**

## Quickstart

```bash
# 1. Install
pnpm install

# 2. Copy env
cp .env.example .env

# 3. Dev server (proxies /api/admin/* to VITE_API_BASE_URL)
pnpm dev
```

Open `http://localhost:5173/`. The app boots, redirects to `/login`, and after successful auth calls `GET /api/admin/auth/me` to populate roles + permissions + menus.

## Scripts

| Command | What it does |
|---|---|
| `pnpm dev` | Vite dev server with HMR |
| `pnpm build` | Type-check + production bundle to `dist/` |
| `pnpm preview` | Preview the production bundle |
| `pnpm test` | Run Vitest once |
| `pnpm test:watch` | Vitest in watch mode |
| `pnpm test:coverage` | Coverage report on `src/store`, `src/directives`, `src/utils` |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier write |

## Environment variables

Set in `.env` (Vite reads any var prefixed with `VITE_`):

| Var | Default | Purpose |
|---|---|---|
| `VITE_API_BASE_URL` | `http://localhost:8000` | Backend origin |
| `VITE_API_PREFIX` | `/api/admin` | Backend route prefix |
| `VITE_APP_TITLE` | `FastDev Admin` | Browser title / login header |
| `VITE_DEFAULT_LOCALE` | `zh-CN` | vue-i18n locale |
| `VITE_TOKEN_STORAGE_KEY` | `fastdev_admin_auth` | localStorage key for refresh token |

## Project structure

```
src/
  api/           # Typed wrappers around backend endpoints
    auth.ts
    user.ts
    role.ts
    permission.ts
    types.ts
  directives/    # v-permission
  layouts/       # BasicLayout + Sidebar + Header + UserDropdown
  locales/       # vue-i18n messages (zh-CN in v1)
  router/
    routes/
      static.ts   # /login, /dashboard, /system/*, error pages
      dynamic.ts  # builds menu routes from /auth/me response
    guard.ts      # auth + permission guard
    index.ts
  store/
    modules/
      auth.ts     # tokens, user, roles, permissions, menus
      app.ts      # sidebar collapsed, etc.
    index.ts
  styles/
    index.css    # Global styles + admin-shell primitives
  utils/
    http.ts       # axios + single-flight refresh
    auth.ts       # localStorage helpers for refresh token
  views/
    login/
    dashboard/
    profile/
    error/        # 403, 404, 500
    system/
      users/
      roles/
      permissions/
  App.vue
  main.ts
  test-setup.ts   # Vitest global setup (jsdom, env defaults)
```

## How `v-permission` works

```vue
<el-button v-permission="['user:create']">New User</el-button>
<el-button v-permission="'user:delete'">Delete</el-button>
```

- Accepts a string (single code) or array (user must have ALL listed codes).
- Users with the `super-admin` role bypass the check.
- If the check fails the element is **removed from the DOM** (more reliable than `display:none` for security-sensitive UI like destructive actions).
- Driven by `useAuthStore().permissions` which is populated from `GET /auth/me`.

## How authentication flows

1. `useAuthStore().login()` → `POST /auth/login` → store `accessToken` in memory, persist `refreshToken` in `localStorage`.
2. `axios` request interceptor attaches `Authorization: Bearer <accessToken>` to every request.
3. On 401 (any non-refresh endpoint), the response interceptor calls `POST /auth/refresh` **once** and queues concurrent failures behind a shared promise.
4. On refresh success, the original request retries with the new token. On failure, auth state is cleared and the user is bounced to `/login?redirect=...`.
5. The route guard calls `fetchMe()` on first authenticated navigation to populate `user`, `roles`, `permissions`, `menus`. Menu routes are then registered with the router via `registerDynamicRoutes()`.

## Adding a new page

1. Create `src/views/<feature>/index.vue`.
2. Add a static route to `src/router/routes/static.ts` with `meta.requiresPermission`.
3. Add a matching menu row via `POST /api/admin/permissions` (type `menu`, `path: '/<feature>'`, `component: '<feature>/index'`).
4. Map the `component` string to a loader in `src/router/routes/dynamic.ts` (`componentMap`).
5. Add the permission code to a role via `POST /api/admin/roles/{id}/permissions`.

## Tests

```bash
pnpm test
```

Current suite: 14 tests covering `auth` store, `v-permission` directive, `http` access-token helpers, and a `LoginView` smoke test.

## What's intentionally NOT here

- OAuth/social login — separate capability
- Multi-tenant — single tenant in v1
- i18n beyond zh-CN — single locale; `vue-i18n` is wired so adding locales is config-only
- Production deployment artifacts (Dockerfile, CI) — out of scope