# AGENTS.md

## Commands

- `npm run dev` — Vite dev server on port 5173. Dev proxy forwards `/api` to `http://localhost:8080` and strips the prefix.
- `npm run build` — the only automated check: `vue-tsc -b && vite build`. There are no test or lint scripts.
- `npm run api:gen` — regenerates the Orval client from `http://localhost:8080/v3/api-docs`; the backend must be running. `clean: true` deletes/recreates `src/api`, so never hand-edit `src/api/**`.
- `VITE_API_BASE_URL` overrides the axios base URL (defaults to `/api`); create `.env.local` to call a non-proxied backend.

## Architecture

- Vue 3 + TypeScript + Vite + Element Plus (zh-CN) + Pinia with persisted state.
- Entry: `src/main.ts`. Routes and auth guards: `src/router/index.ts`. `@` aliases to `src/`.
- Generated API controllers live in `src/api/*-controller.ts`, models in `src/api/models/`. They call the mutator `customAxiosInstance` from `src/util/axios-instance.ts`.
- Layouts: `src/layout/UserLayout.vue` (public) and `src/layout/AdminLayout.vue` (admin/coach). Route meta: `requiresAdmin` (admin only), `requiresCoach` (admin and coach). Roles: `admin`, `coach`, `user`, `guest`.

## HTTP conventions

- The response interceptor returns `response.data`, i.e. the `Response<T>` wrapper. Use results as `res.code`, `res.message`, `res.data`.
- Success means `code === 0 || code === 200`.
- Error messages are centralized in `src/util/axios-instance.ts`. Views keep local validation messages and their own `ElMessage.success` for operation feedback.
- Do not add `ElMessage.error` for API failures in views, and do not add success toasts in the interceptor. Duplicating these layers caused every API call to show repeated messages.
- The backend success `message` is always `"success"`; it is not user-facing text.
- Token lives in `localStorage.token`; the request interceptor injects `Authorization: Bearer <token>`. HTTP 401 shows a message and redirects to `/login`.

## Workflow

- Commit to the local repository after completing each work point (one coherent change, fix, or feature) before starting the next.
- Keep each commit scoped to that work point; do not batch unrelated changes.

## Gotchas

- `tsconfig.app.json` enables `strict`, `noUnusedLocals`, and `noUnusedParameters`; remove unused imports or `npm run build` fails.
- `dist/` is build output and `src/api/**` is generated output; neither should be edited manually.