|
@@ -0,0 +1,34 @@
|
|
|
|
|
+# 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.
|
