# Wangxuancheng Dev Goravel Admin Goravel Admin

> Goravel Admin Frontend (html/)

- Skill: `tomevault-io/wangxuancheng-dev-goravel-admin-goravel-admin` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/wangxuancheng-dev-goravel-admin-goravel-admin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/wangxuancheng-dev-goravel-admin-goravel-admin/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/wangxuancheng-dev-goravel-admin-goravel-admin

---


# Goravel Admin Frontend (html/)

## Project basics (assume by default)
- Tech stack: Vue 3, Vite, TypeScript, Element Plus, Pinia, Vue Router, vue-i18n.
- Source root: `html/src` with alias `@` configured in `html/vite.config.js`.
 - API modules live in `html/src/api/*.js` and call `request` from `html/src/utils/request.js`.

## Backend response contract (must match)
The frontend request layer expects backend responses shaped like:
- success: `{ code: 200, message: string, data?: any, trace_id?: string }`
- error: `{ code: <http_status>, message: string, error_code: string, trace_id?: string, errors?: object }`

Do not invent new response shapes in frontend code. Handle the contract via the existing wrapper.

## HTTP client conventions (must follow)
Use `html/src/utils/request.js` (axios instance) for all API calls.

### Auth token + headers
- Token storage key: `token` (via `Storage.getItem/setItem`)
- Request header: `Authorization: Bearer <token>`
- Response may refresh token via:
  - response header `authorization` (Bearer ...)
  - or payload `res.data.token`

### i18n + locale headers
- Request sets `Accept-Language` based on `i18n.global.locale` (zh-CN / en-US).

### Timezone header
- Request sets `X-Timezone` from app store or stored timezone, falling back to browser timezone.

### Error handling behavior
The response interceptor already:
- Treats `res.code !== 200` as a business error even if HTTP status is 200.
- Extracts `message`, `error_code`, `code` and tries to translate message by `error_code`:
  - `common.<error_code>` first (e.g. `common.operation_failed`)
  - then `messages.<error_code>`
- Handles 401 (logout + redirect /login) and 403 (debounced message) globally, except for auth endpoints (`/login` `/logout`) which are delegated to the page (e.g. Login view).
- Special-cases 429 for export endpoints: don’t toast automatically; let business code handle it.

Therefore:
- Do not duplicate global toasts in pages when `err.__handled === true`.
- For login/logout pages, expect errors to be unhandled and display them locally.

## API layer conventions
Prefer following the existing pattern used by modules like `html/src/api/user.js`:
- build a base CRUD API with `createCRUDApi(resource)`
- add non-CRUD endpoints via `extendApi(baseApi, { ... })`
- export functions via destructuring with names like `getXList/getXDetail/createX/updateX/deleteX`

Extend with custom methods via `extendApi(baseApi, customMethods)` when needed.

When wiring a page:
- Use `useApiRequest()` for cancellable requests and loading/error state.
- Keep API calls in `html/src/api/...` modules (do not call `request` directly from views unless it’s truly one-off).

## Output expectations (how the agent should report changes)
When implementing frontend changes, always include:
- Changed files (path + purpose)
- API endpoints touched (method + path) and expected response keys used
- UX behavior for errors (what’s global vs what the page shows)
- Test plan (commands + manual steps)

## Additional resources
- For module patterns, API templates, and page wiring examples, see [examples.md](examples.md).
- For response/error-code mapping and i18n keys, see [reference.md](reference.md).

---
> Source: [wangxuancheng-dev/goravel-admin](https://github.com/wangxuancheng-dev/goravel-admin) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-29 -->