zcui/saber3/AGENTS.md

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.