优化
This commit is contained in:
79
monisuo-admin/.agents/skills/shadcn-vue-admin/SKILL.md
Normal file
79
monisuo-admin/.agents/skills/shadcn-vue-admin/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: shadcn-vue-admin
|
||||
description: Build and maintain the shadcn-vue-admin Vue 3 + Vite + TypeScript admin dashboard with shadcn-vue, Tailwind, Pinia, Vue Router, i18n, and TanStack Query. Use for UI/layout changes, page additions, routing updates, theme/auth work, and component integration in this repo.
|
||||
license: MIT
|
||||
metadata:
|
||||
repository: Whbbit1999/shadcn-vue-admin
|
||||
package-manager: pnpm
|
||||
framework: vue
|
||||
language: typescript
|
||||
---
|
||||
|
||||
## Purpose and scope
|
||||
|
||||
Maintain this Vue 3 admin dashboard repository: pages and layouts, component integration, routing/auth, theming and i18n, data tables, and form validation.
|
||||
|
||||
## Codebase map
|
||||
|
||||
- App entry: `src/main.ts`, `src/App.vue`
|
||||
- Routing: `src/router/`
|
||||
- Layouts and pages: `src/layouts/`, `src/pages/`
|
||||
- Components: `src/components/` (including shadcn-vue style UI)
|
||||
- State: `src/stores/`
|
||||
- Composables: `src/composables/`
|
||||
- Utils and constants: `src/utils/`, `src/lib/`, `src/constants/`
|
||||
- Plugins: `src/plugins/`
|
||||
|
||||
## References
|
||||
|
||||
- System knowledge map: [references/SYSTEM_KNOWLEDGE_MAP.md](references/SYSTEM_KNOWLEDGE_MAP.md)
|
||||
- Testing strategy: [references/testing-strategy.md](references/testing-strategy.md)
|
||||
|
||||
## Standard workflow
|
||||
|
||||
1. Read existing implementations in the target directory and reuse established patterns and styles.
|
||||
2. Prefer existing shadcn-vue components and shared utilities to avoid duplication.
|
||||
3. Only change public APIs when necessary; avoid large-scale formatting unrelated code.
|
||||
|
||||
## Commands and checks
|
||||
|
||||
- Dev server: `pnpm dev`
|
||||
- Build (CI-like check): `pnpm build`
|
||||
- Lint fix: `pnpm lint:fix`
|
||||
|
||||
Requirements:
|
||||
|
||||
- Run `pnpm build` for any non-copy-only change.
|
||||
- Run `pnpm lint:fix` after code changes.
|
||||
- If you modify core logic (`src/lib/**`, `src/utils/**`, `src/composables/**`, `src/services/**`, `src/router/**`, `src/stores/**`):
|
||||
- If test scripts exist (e.g. `pnpm test`/`pnpm test:unit`), add/update tests and run them.
|
||||
- If no test scripts exist, tests are optional but recommended; include “Testing Notes” in the change description.
|
||||
|
||||
## Design and implementation conventions
|
||||
|
||||
- Use Vue 3 Composition API with TypeScript.
|
||||
- Prefer vee-validate + zod for form validation.
|
||||
- Follow existing theming strategy in `src/assets/` and `src/stores/theme.ts`.
|
||||
- Follow the existing structure for i18n in `src/plugins/i18n/`.
|
||||
|
||||
## Common task guides
|
||||
|
||||
### Add a page
|
||||
|
||||
1. Create a page component under `src/pages/`.
|
||||
2. Register routing/menu via `src/router/` if needed.
|
||||
3. Use existing layouts and shared components for consistent spacing and typography.
|
||||
|
||||
### Add a component
|
||||
|
||||
1. Reuse `src/components/ui/` and existing shadcn-vue components first.
|
||||
2. If it should be shared, place it under `src/components/` to avoid page-level duplication.
|
||||
|
||||
### Update theme/styles
|
||||
|
||||
1. Prefer Tailwind and theme files in `src/assets/`.
|
||||
2. Avoid heavy inline styles; keep components maintainable.
|
||||
|
||||
### Output requirements
|
||||
|
||||
After changes, provide a concise summary and list any commands run (if any).
|
||||
@@ -0,0 +1,118 @@
|
||||
# System Knowledge Map (for agents)
|
||||
|
||||
> This is a “navigation index”. It only keeps the high-level structure and key entry files so AI can locate things quickly.
|
||||
|
||||
## Project Overview
|
||||
|
||||
- Stack: Vue 3 + Vite + TypeScript + TailwindCSS
|
||||
- Routing: `vue-router` (v5+ with automatic routes from `src/pages`) + `vite-plugin-vue-layouts`
|
||||
- State: Pinia (with persistedstate)
|
||||
- Data: Axios + @tanstack/vue-query
|
||||
- Forms: vee-validate + zod
|
||||
- UI: shadcn-vue / reka-ui / lucide-vue-next / vue-sonner
|
||||
|
||||
## Startup Flow
|
||||
|
||||
- `index.html`
|
||||
- `src/main.ts`: creates the app, registers plugins, imports global CSS, loads `src/utils/env`
|
||||
- `src/App.vue`: `<router-view />` + `<Suspense>`, initializes `useSystemTheme()`
|
||||
|
||||
## Build / Generation (Vite)
|
||||
|
||||
- `vite.config.ts`
|
||||
- Alias: `@` -> `src/`
|
||||
- Route generation: `vue-router/vite` (types: `src/types/route-map.d.ts`)
|
||||
- Layouts: `vite-plugin-vue-layouts` (default: `default`)
|
||||
- Auto-import: `src/composables` / `src/constants` / `src/stores` (types: `src/types/auto-import.d.ts`)
|
||||
- Components: `src/components` (types: `src/types/auto-import-components.d.ts`)
|
||||
|
||||
## Routing & Layouts
|
||||
|
||||
- Pages (route source): `src/pages/**`
|
||||
- Router (assembly / scroll behavior / HMR): `src/router/index.ts`
|
||||
- Guards: `src/router/guard/*` (includes auth + nprogress)
|
||||
- Layouts: `src/layouts/*.vue` (default / blank / marketing)
|
||||
|
||||
In page files you can use `<route lang="yaml">` to define meta (commonly: layout/auth). Example YAML:
|
||||
|
||||
```yaml
|
||||
meta:
|
||||
# layout can be: false | blank | marketing
|
||||
layout: blank
|
||||
auth: true
|
||||
```
|
||||
|
||||
## State & Theme
|
||||
|
||||
- Stores: `src/stores/*` (`auth.ts`, `theme.ts`)
|
||||
- Theme: `src/composables/use-system-theme.ts` + `src/assets/themes.css`
|
||||
- Dark/Light/System: `src/components/toggle-theme.vue`
|
||||
|
||||
## Data Fetching / API
|
||||
|
||||
- Axios: `src/composables/use-axios.ts`
|
||||
- Vue Query plugin: `src/plugins/tanstack-vue-query/setup.ts`
|
||||
- API modules: `src/services/api/*.api.ts`
|
||||
- Shared response types: `src/services/types/response.type.ts`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
When adding environment variables, make sure to validate/types them in `src/utils/env.ts`.
|
||||
|
||||
## Third-party Plugin Setup
|
||||
|
||||
Plugin initialization entry: `src/plugins/index.ts`
|
||||
|
||||
1. When introducing a third-party plugin that needs configuration, put the setup in `src/plugins/[plugin-name]/setup.ts`.
|
||||
2. Import/register it from `src/plugins/index.ts`.
|
||||
|
||||
## Form Validation
|
||||
|
||||
- Validators: `src/pages/**/validators/*.validator.ts` (zod)
|
||||
- Forms: `src/pages/**/components/*-form.vue` (commonly: `toTypedSchema` + `useForm`)
|
||||
|
||||
## UI Component Directories
|
||||
|
||||
- Base UI: `src/components/ui/**`
|
||||
- Layout components: `src/components/global-layout/**`
|
||||
- Sidebar: `src/components/app-sidebar/**`
|
||||
- Command palette: `src/components/command-menu-panel/**`
|
||||
|
||||
## Page / Module Directory Convention
|
||||
|
||||
> Routes are generated automatically from the file structure.
|
||||
|
||||
- Pages: `src/pages/**/*.vue`
|
||||
- Page components: `src/pages/**/components/**/*.vue`
|
||||
- Validators: `src/pages/**/validators/*.validator.ts`
|
||||
- For data-display pages, table configuration should live in: `src/pages/**/data/**`
|
||||
|
||||
## Key Conventions
|
||||
|
||||
- Routing is file-based: do NOT hand-edit route tables; add/rename/remove pages under `src/pages/**`.
|
||||
- Prefer `<route lang="yaml">` meta over ad-hoc logic (commonly: `meta.layout`, `meta.auth`).
|
||||
- Keep env vars strictly typed/validated in `src/utils/env.ts` before use.
|
||||
- Prefer `@/` (alias to `src/`) imports to avoid brittle relative paths.
|
||||
|
||||
## Common Tasks (Where to Change)
|
||||
|
||||
- Add a new page/route: create `src/pages/<name>.vue` (or `src/pages/<name>/index.vue`) + optional `<route lang="yaml">` meta.
|
||||
- Add/modify a layout: edit `src/layouts/*.vue`, then set `meta.layout` in the page.
|
||||
- Add a plugin: create `src/plugins/<plugin>/setup.ts`, then register it in `src/plugins/index.ts`.
|
||||
- Add an API module: create `src/services/api/*.api.ts`; put shared request/response types in `src/services/types/*` or `src/services/api/types/*`.
|
||||
- Add data fetching: use Axios (`src/composables/use-axios.ts`) + Vue Query (setup: `src/plugins/tanstack-vue-query/setup.ts`).
|
||||
- Add a form: define a zod validator in `src/pages/**/validators/*.validator.ts`, then use it from `src/pages/**/components/*-form.vue`.
|
||||
- Add a store: create `src/stores/*.ts` (Pinia; persistedstate is enabled).
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- Auto-generated types/routes: when pages change, TypeScript/IDE may need a restart to pick up updated generated types (e.g. `src/types/route-map.d.ts`).
|
||||
- Auto-imported symbols: composables/constants/stores are auto-imported; name collisions can silently change which symbol you get.
|
||||
- Layout meta values: ensure `meta.layout` matches an actual layout filename (and understand what `layout: false` does in this project).
|
||||
- Env vars: Vite uses `import.meta.env`; do not bypass `src/utils/env.ts` validation.
|
||||
|
||||
## Quick Verification
|
||||
|
||||
- Dev: `pnpm dev`
|
||||
- Lint: `pnpm lint:fix`
|
||||
- Build: `pnpm build`
|
||||
@@ -0,0 +1,36 @@
|
||||
# Testing Strategy
|
||||
|
||||
## Current State
|
||||
|
||||
- This repo currently has no dedicated test runner configured (no `pnpm test` script in `package.json`).
|
||||
- For now, treat `pnpm build` (typecheck + Vite build) as the primary safety net.
|
||||
|
||||
## Policy (Strong Constraints)
|
||||
|
||||
- If you change logic in any of the following areas:
|
||||
- `src/lib/**`, `src/utils/**`
|
||||
- `src/composables/**`
|
||||
- `src/services/**`
|
||||
- `src/router/**`
|
||||
- `src/stores/**`
|
||||
- With a test runner available: automated tests are required in the same change, and you must run the relevant test command.
|
||||
- Without a test runner: tests are optional but strongly recommended; you must include “Testing Notes” in the PR/commit description explaining risk and manual/alternative checks.
|
||||
- Pure UI layout/styling changes may skip tests, but must still pass `pnpm build`.
|
||||
|
||||
## Agent Checklist (When Changing Code)
|
||||
|
||||
1. Run `pnpm lint:fix`.
|
||||
2. Run `pnpm build` to catch TypeScript + build-time issues.
|
||||
3. If a test script exists (e.g. `test`, `test:unit`, `test:e2e`), run the relevant command(s).
|
||||
4. For core logic changes, add/adjust tests (see Policy).
|
||||
|
||||
## What To Test (If Adding Tests Later)
|
||||
|
||||
- Pure logic/utils: unit tests (fast, deterministic).
|
||||
- Composables: unit tests with mocked dependencies.
|
||||
- UI components/pages: component tests only for critical interactions; prefer testing behavior over implementation details.
|
||||
|
||||
## Recommended Tooling (Optional)
|
||||
|
||||
- Unit/component: Vitest + @vue/test-utils
|
||||
- E2E (only if needed): Playwright
|
||||
Reference in New Issue
Block a user