|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +BlueKing API Gateway Dashboard Frontend — a Vue 3 + TypeScript SPA for managing API gateways, resources, stages, permissions, plugins, MCP servers, and more. Part of the larger `blueking-apigateway` monorepo under `src/dashboard-front/`. |
| 6 | + |
| 7 | +## Commands |
| 8 | + |
| 9 | +```bash |
| 10 | +# Development (Vite dev server on dev-t.paas3-dev.bktencent.com:8888, basic SSL enabled) |
| 11 | +npm run dev |
| 12 | + |
| 13 | +# Preview (uses index.dev.html) |
| 14 | +npm run preview |
| 15 | + |
| 16 | +# Production build (type-check + vite build, runs in parallel) |
| 17 | +npm run build |
| 18 | + |
| 19 | +# Build without type checking |
| 20 | +npm run build-only |
| 21 | + |
| 22 | +# Type checking only |
| 23 | +npm run type-check # vue-tsc --build |
| 24 | + |
| 25 | +# Lint (runs oxlint then eslint sequentially) |
| 26 | +npm run lint |
| 27 | + |
| 28 | +# Lint individually |
| 29 | +npm run lint:oxlint # oxlint . --fix -D correctness --ignore-path .gitignore |
| 30 | +npm run lint:eslint # eslint . --fix |
| 31 | +``` |
| 32 | + |
| 33 | +No test framework is configured — there are no unit or e2e tests. |
| 34 | + |
| 35 | +## Architecture |
| 36 | + |
| 37 | +### Entry & Bootstrap |
| 38 | + |
| 39 | +- `main.ts` — Creates Vue app, installs Pinia, Vue Router, bkui-vue (full import), vue-i18n, mavon-editor, XSS filter directive, and registers global components (`AgIcon`, `IconButton`, `CopyButton`, `CardContainer`). |
| 40 | +- `App.vue` — Root layout with `BkNavigation` (top-bottom nav), header menu, language toggle, user info. Fetches environment config and user info on route changes. Feature flags control menu visibility. |
| 41 | +- HTML entry points: `index.dev.html` / `index.prod.html` — the `replace-index-html.js` script copies the appropriate one to `index.html` before dev/build (backs up existing `index.html`). |
| 42 | +- Build also includes `default.html` as a secondary Rollup input (see `vite.config.ts`). |
| 43 | + |
| 44 | +### Routing (`src/router/index.ts`) |
| 45 | + |
| 46 | +Each feature module exports its own route factory function (e.g., `getStageManagementRoutes()`). Main structure: |
| 47 | +- `/` — Home (gateway list) |
| 48 | +- `/:id` — Gateway detail layout (`src/layout/my-gateway/`), children: stage-management, resource-management, basic-info, backend-services, permission, operate-data, online-debugging, audit-log, monitor-alarm, mcp-server |
| 49 | +- `/platform-tools`, `/mcp-market`, `/components`, `/docs` — Top-level sections with their own layouts under `src/layout/` |
| 50 | + |
| 51 | +### State Management (`src/stores/`) |
| 52 | + |
| 53 | +Pinia stores, all re-exported from `src/stores/index.ts`: |
| 54 | +- `useEnv` — Environment config (BK_DASHBOARD_URL, site paths) |
| 55 | +- `useUserInfo` — Current user & tenant info |
| 56 | +- `useFeatureFlag` — Feature flag toggles |
| 57 | +- `useGateway` — Current gateway data (central to most views) |
| 58 | +- `useStage`, `usePermission`, `useAccessLog`, `useAuditLog`, `useResourceVersion`, `useResourceSetting`, `useStaff` |
| 59 | + |
| 60 | +### API Layer (`src/services/`) |
| 61 | + |
| 62 | +- `http/index.ts` — Exports an HTTP handler with methods: `get`, `post`, `put`, `patch`, `delete`, `download`. Each call creates a `Request` instance that goes through axios with request/response middleware. |
| 63 | +- `http/lib/request.ts` — Core request class. Supports caching, cancel tokens, upload progress, and permission-based error handling (`page` | `dialog` | `catch`). |
| 64 | +- `source/*.ts` — ~28 service modules (gateway, resource, stage, permission, mcp-server, mcp-market, plugin-manage, etc.). Each defines API functions that call `http.get('/gateways/...', params)`. |
| 65 | + |
| 66 | +### UI Components |
| 67 | + |
| 68 | +Two UI libraries in use: |
| 69 | +- **bkui-vue** (BlueKing UI) — Primary component library, fully imported |
| 70 | +- **tdesign-vue-next** (via `@blueking/tdesign-ui`) — Used for advanced tables and some form components |
| 71 | + |
| 72 | +Custom components in `src/components/` follow `ag-*` naming: `ag-icon`, `ag-editor`, `ag-table`, `ag-dropdown`, `ag-sideslider`, `ag-mcp-card`, etc. |
| 73 | + |
| 74 | +### Hooks (`src/hooks/`) |
| 75 | + |
| 76 | +Composables for common patterns (see `src/hooks/index.ts`): `use-query-list` (paginated data), `use-selection-data` (table selection), `use-table-filter-change`, `use-table-sort-change`, `use-sidebar` (drawer state), `use-gate-way-data` (gateway list with search), `use-max-table-limit` (viewport-based pagination), `use-date-picker`, `use-tdesign-selection`, `use-stage-data`, `use-text-getter`, `use-table-setting`, `use-sticky-bottom`, `use-operation-lock`, `use-mcp-config-divide-ratio`, `use-bk-user-display-name`. |
| 77 | + |
| 78 | +### i18n (`src/locales/`) |
| 79 | + |
| 80 | +vue-i18n with Composition API mode. Locale files live in `src/locales/cn.json` and `src/locales/en.json`, mapped to `zh-cn` (default/fallback) and `en`. Language set via `blueking_language` cookie. Use `t('key')` from the exported `t` function or `useI18n()` (auto-imported). |
| 81 | + |
| 82 | +### Styling |
| 83 | + |
| 84 | +- SCSS for component/global styles (`src/styles/`) |
| 85 | +- UnoCSS with Tailwind v3 preset (`uno.config.ts`) for utility classes |
| 86 | +- CSS class naming: kebab-case (`^[a-z][a-z0-9_-]+$`, enforced by stylelint) |
| 87 | + |
| 88 | +## Code Style Rules |
| 89 | + |
| 90 | +Enforced by ESLint flat config (`eslint.config.ts`) + oxlint + stylelint: |
| 91 | + |
| 92 | +- **Semicolons required**, single quotes, 2-space indent, 120-char max line length |
| 93 | +- **Trailing commas** in multiline (comma-dangle: always-multiline) |
| 94 | +- **Sort imports** (declaration sort ignored, member sort enforced) |
| 95 | +- **No duplicate imports** |
| 96 | +- **Vue**: `<script setup>` with TypeScript. Macro order: `defineOptions` → `defineModel` → `defineProps` → `defineEmits` → `defineSlots`, `defineExpose` last. Emits declared as type-literal. Props destructuring enforced. Multi-word component names rule disabled. |
| 97 | +- **Object/array formatting**: newlines enforced for multiline objects/arrays, consistent bracket newlines |
| 98 | + |
| 99 | +## Commit Conventions |
| 100 | + |
| 101 | +Conventional commits enforced by commitlint. Allowed types: `feat`, `fix`, `perf`, `style`, `docs`, `test`, `refactor`, `build`, `ci`, `chore`, `revert`, `wip`, `workflow`, `types`. |
| 102 | + |
| 103 | +Pre-commit hook runs lint-staged (ESLint --fix on staged `.{js,jsx,ts,tsx,vue}` files). |
| 104 | + |
| 105 | +## Path Aliases |
| 106 | + |
| 107 | +`@` → `./src` (configured in both vite.config.ts and tsconfig.app.json). Also `bkui-lib` → `bkui-vue/lib`. |
| 108 | + |
| 109 | +## Auto-Imports |
| 110 | + |
| 111 | +`vue`, `vue-router`, and `useI18n` from `vue-i18n` are auto-imported via `unplugin-auto-import` — no need to explicitly import `ref`, `computed`, `watch`, `onMounted`, `useRouter`, etc. Type declarations generated at `src/types/auto-imports.d.ts`. |
| 112 | + |
| 113 | +## Key Patterns |
| 114 | + |
| 115 | +- **Service functions** take a base path and call `http.get(url, params, payload)`. The `payload` object can include `cache`, `timeout`, `permission` (error handling strategy), and `onUploadProgress`. |
| 116 | +- **Views** are organized as feature modules in `src/views/<feature>/`, each with its own `route.ts` and sub-components. |
| 117 | +- **Layouts** in `src/layout/` provide the sidebar navigation for each top-level section (my-gateway, platform-tools, mcp-market, etc.). |
| 118 | +- **Global components** registered in `main.ts`: `AgIcon`, `IconButton`, `CopyButton`, `CardContainer` — available without import. |
| 119 | +- **Custom element**: `<bk-user-display-name>` is treated as a custom element (not parsed as Vue component) in the Vue template compiler config. |
0 commit comments