# AGENTS.md — Saber3 (BladeX Frontend)

Compact orientation for OpenCode sessions. When in doubt, also read `CLAUDE.md` in the same directory.

---

## Project Type

Vue 3 + Element Plus + Avue CRUD enterprise admin SPA. Vite build. Pure JavaScript (no TypeScript). Uses pnpm.

---

## Commands

| Command | Purpose |
|---------|---------|
| `pnpm run dev` | Vite dev server on **port 2888** |
| `pnpm run build` | Dev build (esbuild minify) |
| `pnpm run build:prod` | Production build (terser, drops `console`/`debugger`, strips comments) |
| `pnpm run serve` | Preview production build |

No test runner, no lint command, no typecheck.

---

## Path Aliases

Defined in `vite.config.mjs`:

- `@` → `./src`
- `~` → `./`
- `components` → `./src/components`
- `styles` → `./src/styles`
- `utils` → `./src/utils`

---

## Code Style

Prettier config (`.prettierrc.json`):

- `printWidth: 100`, `tabWidth: 2`, `semi: true`, `singleQuote: true`, `arrowParens: "avoid"`

No ESLint. No TypeScript. Follow the existing file’s style when editing.

---

## Vue API Style

**Both Options API and Composition API coexist.** Do not mix styles in one file.

- **Editing existing pages**: keep the original style.
- **New standard CRUD pages**: prefer Options API (project mainstream).
- **New complex interactive pages**: may use Composition API + `<script setup>`.

Reference implementations:
- Options API: `src/views/system/dict.vue`
- Composition API: `src/views/desk/notice-composition.vue`

---

## Adding a New Page (Standard CRUD)

Create three files with **isomorphic module paths**:

1. API: `src/api/{module}/{name}.js`
2. Option: `src/option/{module}/{name}.js` (Avue table/form config)
3. View: `src/views/{module}/{name}.vue`

Reuse existing components/utilities from `src/components/` and `src/utils/`; avoid reinventing.

---

## Global Registration

Components registered in `main.js` are usable in templates without importing:

`basic-container`, `basic-block`, `highlight`, `code-editor`, `cron-editor`, `flow-design`, `flow-design-step`, `third-register`, `code-setting`, `form-setting`, `tenant-package`, `tenant-datasource`

Global properties (Options API via `this`):

- `this.website` — config from `src/config/website.js`
- `this.$dayjs` — dayjs instance
- `this.getScreen` / `this.findColumn` — utilities

---

## Routing

- **Static routes**: `src/router/page/` + `src/router/views/`
- **Dynamic routes**: backend menu JSON is transformed by `src/router/avue-router.js` into Vue Router routes at runtime.
- Deep nesting is flattened to two levels for `keep-alive` compatibility.
- External URLs become iframe routes; token/user info is injected via `${token}`, `${userId}`, etc.

---

## Auth / HTTP

- Token header: `Blade-Auth: bearer {token}`
- Storage keys: `saber3-access-token`, `saber3-refresh-token`
- `src/axios.js` handles 401 → automatic token refresh with request queueing.
- OAuth2 client credentials sent as `Basic` header (Base64).
- Login password encrypted with SM2.

---

## Dev Proxy

Vite dev server proxies `/api` to `http://localhost`. Adjust `vite.config.mjs` → `server.proxy` if your backend runs on a different port.

---

## Build Differences

- **Dev**: esbuild minify, no code splitting.
- **Prod**: terser minify, drops `console`/`debugger`, strips comments, manual chunks for `element-plus` and `@smallwei/avue`, optional gzip/brotli compression.

---

## Git Commits

Use Gitmoji style with Chinese description. Preferred emojis:

- `:sparkles:` new feature
- `:bug:` bugfix
- `:zap:` performance / quick fix
- `:lipstick:` style
- `:recycle:` refactor
- `:wrench:` config
- `:memo:` docs
- `:fire:` delete

---

## SCSS

Global variables from `src/styles/variables.scss` are auto-injected into every component via Vite `css.preprocessorOptions.scss.additionalData`. Prefer variables/mixins over hardcoded values.

---

## Tenant Mode

Controlled by `website.tenantMode` (`src/config/website.js`). Management tenant id is `000000`. Backend passes tenant info via headers automatically.

---

## Notes for Agents

- Before writing new code, check the same module for existing patterns and copy style.
- Do not write alternative implementations if an existing one in `src/components/` or `src/utils/` already meets the need.
- If introducing a new dependency, verify no conflict with existing packages, then run `pnpm install` → `pnpm run build` to confirm.
- All user-facing output should be in Chinese.