153 lines
4.4 KiB
Markdown
153 lines
4.4 KiB
Markdown
|
# 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.
|