# AGENTS.md

## Commands

| Script | Command | Purpose |
|--------|---------|---------|
| `dev` | `vite` | Dev server with HMR, proxies `/api` → `http://localhost:8080` (strips prefix) |
| `build` | `vue-tsc -b && vite build` | Type-check (project references mode) then production build |
| `preview` | `vite preview` | Preview production build locally |
| `api:gen` | `orval` | Generate API client + models from `http://localhost:8080/v3/api-docs` |

Build order matters: `npm run build` runs `vue-tsc -b` before `vite build`. After changes, always run `npm run build` (not just `vue-tsc`).

## Architecture

- **Vue 3** `<script setup>` SFCs, **Vite 6**, **TypeScript 5.8**, **Element Plus 2**, **Pinia 3**, **Vue Router 4**
- Two layouts: `UserLayout` (public, horizontal nav), `AdminLayout` (sidebar + header)
- Router guard checks `meta.requiresAdmin` → must be logged in + role `admin`, else redirect
- Auth: JWT token in `localStorage` key `token`; Pinia `useLoginUserStore` persists via `pinia-plugin-persistedstate`
- Path alias `@` → `./src/*`

## API / Codegen

- `npm run api:gen` fetches OpenAPI spec from live backend at `localhost:8080`, writes to `src/api/`
- Generated controllers (`auth-controller.ts`, `user-controller.ts`) use `customAxiosInstance` from `src/util/axios-instance.ts`
- Custom mutator handles Bearer token injection, response unwrapping, and 401 → `/login` redirect
- Generated models under `src/api/models/` — re-exported via `index.ts`
- Run `api:gen` when backend API changes. `orval` is a runtime dep (unconventional but works).

## Conventions

- **Use Orval-generated API only** — never write raw axios/fetch calls. Re-export from `src/api/` controllers or models as needed.
- **Responsive design** — all views and layouts must work on both PC and mobile. Use Element Plus responsive utilities and CSS media queries.
- **Theme color** is `#e34889` — set as CSS variable `--el-color-primary` and Element Plus primary color. Apply consistently across all components.

## Code quality

- **No test framework, no test files** — do not add or expect tests
- **No ESLint** — only Prettier 3 (defaults, no config), invoked automatically after `api:gen`
- Format manually: `npx prettier --write <file>`
- `tsconfig.app.json`: `strict: true`, `noUnusedLocals: true`, `noUnusedParameters: true`
- Prefer `@/` imports over relative paths

## Known quirks

- `/admin/other` route has `component: AdminLayout` (self-referencing stub — avoid using)
- No `.env` files; base URL defaults to `/api` (Vite proxy). Override via `VITE_API_BASE_URL` env var
- Backend expects JWT. Without a running backend, login/register and API calls will fail