mirror of
https://github.com/zuiidea/antd-admin
synced 2026-10-22 16:03:53 +00:00
chore: consolidate agent guidance into AGENTS.md
Merge scoped instructions into per-app AGENTS.md, add monorepo AGENTS.md and add-resource skill, and remove template .github Copilot files plus the Cursor app router rule. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zuiidea
Cursor
@@ -1,66 +0,0 @@
|
||||
---
|
||||
description: "Thin Cursor rules for template apps with-lingui / basic — route by path and task to each app's .github/instructions (Approach A, single source of truth)"
|
||||
globs: apps/with-lingui/{src,e2e}/**/*.{ts,tsx,css},apps/basic/{src,e2e}/**/*.{ts,tsx,css},apps/with-lingui/playwright.config.ts,apps/basic/playwright.config.ts
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Template apps — AI rules (thin rule)
|
||||
|
||||
This file at the **monorepo root** is the shared **Cursor thin rule** for `apps/with-lingui` and `apps/basic`. It only maps **which files you edit → which instruction file to follow**. Do **not** duplicate long guidance here.
|
||||
|
||||
**Single source of truth** (on conflict, these win):
|
||||
|
||||
- `apps/with-lingui/.github/instructions/*.instructions.md`
|
||||
- `apps/basic/.github/instructions/*.instructions.md`
|
||||
|
||||
For full text in chat, `@`-reference the path below.
|
||||
|
||||
---
|
||||
|
||||
## General
|
||||
|
||||
- When editing template app source or tests matched by `globs`, pick the row in the tables below, then follow that file’s **Do / Do Not / Validation**.
|
||||
- **with-lingui** includes Lingui i18n; **basic** uses plain string literals in UI (default English; no bundled locale switcher or translation catalogs).
|
||||
- When **frontend** and **refactor** both apply: **refactor intent** (dedupe, naming, structure, no behavior change) is governed by `refactor.instructions.md`; UI/interaction details still follow `frontend.instructions.md`.
|
||||
- If you change an instruction file’s `applyTo`, keep this file’s frontmatter `globs` aligned so both apps’ TS/TSX/CSS/E2E paths stay covered.
|
||||
|
||||
---
|
||||
|
||||
## apps/with-lingui
|
||||
|
||||
| Scenario | Typical paths | Instruction file |
|
||||
| --- | --- | --- |
|
||||
| Frontend (UI, routes, components, styles, Ant Design, i18n copy) | `apps/with-lingui/src/**/*.{ts,tsx,css}` | `apps/with-lingui/.github/instructions/frontend.instructions.md` |
|
||||
| API (clients, Zod, HTTP, MSW handlers) | `apps/with-lingui/src/api/**`, `apps/with-lingui/src/mocks/handlers/**`, `createHandler.ts` | `apps/with-lingui/.github/instructions/api.instructions.md` |
|
||||
| Testing (Playwright, MSW, test config) | `apps/with-lingui/e2e/**`, `apps/with-lingui/src/mocks/**`, `playwright.config.ts` | `apps/with-lingui/.github/instructions/testing.instructions.md` |
|
||||
| Refactor (behavior-preserving) | `apps/with-lingui/src/**/*.{ts,tsx}` | `apps/with-lingui/.github/instructions/refactor.instructions.md` |
|
||||
| Add CRUD resource | `src/api/**`, `src/mocks/**`, `src/routes/_auth/**`, `e2e/**/*.spec.ts` | `apps/with-lingui/.github/instructions/add-resource.instructions.md` (mirror `users`) |
|
||||
|
||||
**@ examples:**
|
||||
|
||||
- `@apps/with-lingui/.github/instructions/frontend.instructions.md`
|
||||
- `@apps/with-lingui/.github/instructions/add-resource.instructions.md`
|
||||
|
||||
See also `apps/with-lingui/AGENTS.md` (Vite+ / `vp` workflow).
|
||||
|
||||
---
|
||||
|
||||
## apps/basic
|
||||
|
||||
| Scenario | Typical paths | Instruction file |
|
||||
| --- | --- | --- |
|
||||
| Frontend (UI, routes, components, styles, Ant Design, English copy) | `apps/basic/src/**/*.{ts,tsx,css}` | `apps/basic/.github/instructions/frontend.instructions.md` |
|
||||
| API | `apps/basic/src/api/**`, `apps/basic/src/mocks/handlers/**`, `createHandler.ts` | `apps/basic/.github/instructions/api.instructions.md` |
|
||||
| Testing | `apps/basic/e2e/**`, `apps/basic/src/mocks/**`, `playwright.config.ts` | `apps/basic/.github/instructions/testing.instructions.md` |
|
||||
| Refactor | `apps/basic/src/**/*.{ts,tsx}` | `apps/basic/.github/instructions/refactor.instructions.md` |
|
||||
|
||||
**@ example:** `@apps/basic/.github/instructions/frontend.instructions.md`
|
||||
|
||||
See also `apps/basic/AGENTS.md`.
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
- Humans and agents should **edit** each app’s `.github/instructions/` first; this file only maintains the routing table and `globs`.
|
||||
- Comment language is still governed by `.cursor/rules/english-only-comments.md` (not UI copy or docs).
|
||||
+1
-1
@@ -42,7 +42,7 @@ yarn-error.log*
|
||||
# Git worktrees
|
||||
.worktrees/
|
||||
|
||||
# Cursor: share project rules only (e.g. .cursor/rules/app.mdx); ignore other local Cursor data (instruction source of truth in each app’s .github/instructions)
|
||||
# Cursor: share project rules only; ignore other local Cursor data (agent rules: each app’s AGENTS.md)
|
||||
.cursor/*
|
||||
!.cursor/rules/
|
||||
!.cursor/rules/**
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# antd-admin (monorepo)
|
||||
|
||||
Enterprise admin templates and docs. **AI and coding rules live in each app’s `AGENTS.md`**, not here.
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Role |
|
||||
| --- | --- |
|
||||
| `apps/basic` | English Vite+ template — see `apps/basic/AGENTS.md` |
|
||||
| `apps/with-lingui` | Lingui i18n template — see `apps/with-lingui/AGENTS.md` |
|
||||
| `apps/docs` | Nextra docs site |
|
||||
| `packages/create` | `init-antd-admin` CLI |
|
||||
|
||||
## Commands (repo root)
|
||||
|
||||
- `pnpm install` — sets `core.hooksPath=.githooks` via `preinstall`
|
||||
- `pnpm dev` / `pnpm build` / `pnpm fmt` / `pnpm lint` — turbo across workspaces
|
||||
|
||||
**Template app work:** `cd apps/basic` or `cd apps/with-lingui`, then use **`vp`** (`vp install`, `vp check`, …). Do not run app `vp staged` from root without that `cd`.
|
||||
|
||||
## Git hooks
|
||||
|
||||
`.githooks/pre-commit` runs checks by staged paths: `pnpm exec vp staged` in `apps/basic` / `apps/with-lingui`, typecheck for `packages/create`, lint for `apps/docs`.
|
||||
@@ -61,9 +61,9 @@ pnpm dlx init-antd-admin@latest my-app --example with-lingui --skip-install
|
||||
|
||||
For detailed CLI behavior, see `[packages/create/README.md](./packages/create/README.md)`.
|
||||
|
||||
### Working in this monorepo (Cursor)
|
||||
### AI / agent guidance
|
||||
|
||||
Template apps ship scoped guidance under each app’s `.github/instructions/` (see each app’s `README.md`). **Monorepo-only:** root [`.cursor/rules/app.mdx`](./.cursor/rules/app.mdx) is a thin router to those files when editing `apps/with-lingui` or `apps/basic`; it is **not** included in `init-antd-admin` output.
|
||||
Each template app keeps **`AGENTS.md`** as the single source of truth (Cursor, Claude Code, Codex, etc.). Monorepo overview: [AGENTS.md](./AGENTS.md) at the repo root.
|
||||
|
||||
Production docs: [https://antd-admin-doc.zuiidea.top](https://antd-admin-doc.zuiidea.top)
|
||||
|
||||
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
# AI Instruction Files
|
||||
|
||||
This directory contains scoped instruction files used by AI coding agents.
|
||||
|
||||
## Files
|
||||
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes
|
||||
- `testing.instructions.md`: Playwright/MSW/test changes
|
||||
- `api.instructions.md`: API client/schema/handler changes
|
||||
- `refactor.instructions.md`: behavior-preserving cleanup and deduplication
|
||||
|
||||
## Authoring Rules
|
||||
|
||||
- Keep each file focused on one domain.
|
||||
- Put trigger phrases in `description` so agents can discover the file.
|
||||
- Use narrow `applyTo` patterns to avoid unnecessary context load.
|
||||
- Keep instructions executable: short Do/Do Not/Validation sections.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
applyTo: "src/api/**/*.ts,src/mocks/handlers/**/*.ts,src/mocks/createHandler.ts"
|
||||
description: "Use when editing API clients, schemas, HTTP behavior, response types, or MSW endpoint handlers. Keywords: api, request, defineApi, schema, zod, handler, endpoint, auth, users."
|
||||
---
|
||||
|
||||
# API Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Maintain strict API contracts and a single call path: **schemas → `defineApi` resource modules → UI**. Transport lives in `src/api/request.ts` (axios + interceptors).
|
||||
|
||||
## Do
|
||||
|
||||
- Define APIs with `defineApi` in `src/api/<resource>.ts` (`method` defaults to `GET`; use `params` / `query` / `body` + `output`).
|
||||
- Keep Zod schemas in `src/api/schemas.ts` as the single contract; parse inputs/outputs inside `defineApi`.
|
||||
- Keep MSW handler envelopes consistent (`code`, `data`, `message`) and aligned with schemas.
|
||||
- Co-locate React Query keys with resource modules (e.g. `userQueryKeys`).
|
||||
- Use `hydrateSession` from `@/api/auth` after login/register or when restoring a session.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not call `axios` or `@/api/request` transport helpers from routes/components — import resource functions only (`listUsers`, `login`, …).
|
||||
- Do not return ad-hoc response shapes for one-off convenience.
|
||||
- Do not bypass schema parsing in new client mutations/queries.
|
||||
- Do not mix unrelated domain endpoints in the same module.
|
||||
|
||||
## Validation
|
||||
|
||||
- Verify TypeScript and schema parsing paths compile cleanly.
|
||||
- Run: `vp check --no-fmt`
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
|
||||
## applyTo: "src/\*_/_.{ts,tsx,css}"
|
||||
|
||||
description: "Use when editing React UI, route pages, components, styles, layout, copy, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd, english copy."
|
||||
|
||||
# Frontend Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
|
||||
## Do
|
||||
|
||||
- Preserve existing route contracts and UI behavior unless explicitly asked.
|
||||
- Prefer reusable components and hooks over copy-paste logic.
|
||||
- Keep styles token-driven using existing theme/store patterns.
|
||||
- For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS.
|
||||
- Keep user-facing copy in English as plain string literals (this template has no i18n layer).
|
||||
- Follow current folder conventions under src/components and src/routes.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not introduce new UI libraries when Ant Design already covers the need.
|
||||
- Do not bypass existing theme/store abstractions with hardcoded global state.
|
||||
- Do not write CSS overrides first when props or semantic `styles` can express the same UI.
|
||||
- Do not refactor unrelated files in the same change.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run: `vp check --no-fmt`
|
||||
- For UI flow changes, run focused e2e where possible.
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
|
||||
## applyTo: "src/_/_.{ts,tsx}"
|
||||
|
||||
description: "Use when refactoring existing code for deduplication, modularization, naming cleanup, or maintainability improvements without behavior changes. Keywords: refactor, cleanup, simplify, deduplicate, maintainability."
|
||||
|
||||
# Refactor Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Reduce duplication while preserving behavior and public contracts.
|
||||
|
||||
## Do
|
||||
|
||||
- Keep refactors incremental and scoped to one concern per change.
|
||||
- Prefer extracting shared utilities/hooks/components over large rewrites.
|
||||
- Preserve existing external behavior and route/store contracts.
|
||||
- Keep diffs reviewable with minimal unrelated formatting churn.
|
||||
- Add or update lightweight comments only when logic is non-obvious.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not change runtime behavior unless explicitly requested.
|
||||
- Do not rename broadly across the codebase without clear benefit.
|
||||
- Do not delete tests that still cover unique critical scenarios.
|
||||
- Do not introduce large dependencies for minor convenience; prefer composition or small utilities.
|
||||
|
||||
## Considerations
|
||||
|
||||
- Bundle: Main app chunk is ~135KB (gzip ~41KB). Ant Design (vendor-antd) and TanStack (vendor-tanstack) are in separate chunks for parallel loading. Avoid adding large UI libraries when Ant Design covers the need.
|
||||
- Type safety: Keep validations at API boundaries (Zod schemas) rather than adding more runtime checks throughout the app.
|
||||
|
||||
## Validation
|
||||
|
||||
- Confirm no new diagnostics in touched files.
|
||||
- Run: `vp check --no-fmt`
|
||||
- For significant changes, verify bundle size impact: `vp build 2>&1 | grep "kB"`
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
|
||||
## applyTo: "tests/**/.ts,tests/**/_.tsx,src/mocks//_.ts,playwright.config.ts"
|
||||
|
||||
description: "Use when adding or editing tests, Playwright cases, MSW handlers, mock data, or test configuration. Keywords: test, e2e, playwright, mock, msw, coverage."
|
||||
|
||||
# Testing Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Keep tests fast, deterministic, and aligned with core business flows.
|
||||
|
||||
## Do
|
||||
|
||||
- Prioritize core flows first (auth, users CRUD, permission gates).
|
||||
- Keep assertions user-visible and behavior-focused.
|
||||
- Reuse existing helper patterns in tests before adding new helpers.
|
||||
- Keep mock handlers and mock data synchronized with API schemas.
|
||||
- Prefer focused test runs over full-suite runs during iteration.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not add brittle selectors tied to unstable DOM internals.
|
||||
- Do not expand fixture data without a clear scenario need.
|
||||
- Do not duplicate scenarios already covered by existing tests.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run focused tests first, then broader checks if needed.
|
||||
- Run: `vp check --no-fmt`
|
||||
+45
-59
@@ -1,84 +1,70 @@
|
||||
# Using Vite+, the Unified Toolchain for the Web
|
||||
# antd-admin-basic
|
||||
|
||||
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`.
|
||||
Vite+ template app (React 19, Ant Design 6, TanStack Router/Query, MSW). Default UI copy is English (no i18n). CLI details: [viteplus.dev](https://viteplus.dev).
|
||||
|
||||
## Vite+ Workflow
|
||||
## Commands
|
||||
|
||||
`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
|
||||
Run from **`apps/basic`** (this directory):
|
||||
|
||||
### Start
|
||||
| Task | Command |
|
||||
| ------------------------- | ---------------------------------------------------- |
|
||||
| Install deps | `vp install` (after every pull) |
|
||||
| Dev / build / preview | `vp dev`, `vp build`, `vp preview` |
|
||||
| Format / lint / typecheck | `vp check`, `vp check --no-fmt`, `vp lint`, `vp fmt` |
|
||||
| Unit tests | `vp test run` |
|
||||
| E2E | `pnpm run test:e2e` (or focused spec via Playwright) |
|
||||
| Add/remove deps | `vp add`, `vp remove` — not raw `pnpm`/`npm`/`yarn` |
|
||||
|
||||
- create - Create a new project from a template
|
||||
- migrate - Migrate an existing project to Vite+
|
||||
- config - Configure hooks and agent integration
|
||||
- staged - Run linters on staged files
|
||||
- install (`i`) - Install dependencies
|
||||
- env - Manage Node.js versions
|
||||
**Pitfalls:** Do not install Vitest/Oxlint/Oxfmt/tsdown directly; use `vp`. Do not run `vp vitest` — use `vp test`. If a `package.json` script name conflicts with a built-in `vp` command, use `vp run <script>`. Import toolchain modules from `vite-plus` (e.g. `defineConfig`, test utils), not standalone `vite`/`vitest` packages.
|
||||
|
||||
### Develop
|
||||
**Before finishing:** `vp check` and `vp test run`; run focused e2e when UI flows change.
|
||||
|
||||
- dev - Run the development server
|
||||
- check - Run format, lint, and TypeScript type checks
|
||||
- lint - Lint code
|
||||
- fmt - Format code
|
||||
- test - Run tests
|
||||
---
|
||||
|
||||
### Execute
|
||||
## Frontend
|
||||
|
||||
- run - Run monorepo tasks
|
||||
- exec - Execute a command from local `node_modules/.bin`
|
||||
- dlx - Execute a package binary without installing it as a dependency
|
||||
- cache - Manage the task cache
|
||||
**Purpose:** Predictable, minimal UI changes under `src/`.
|
||||
|
||||
### Build
|
||||
**Do:** Preserve route/UI contracts unless asked. Reuse components/hooks. Token-driven styles via theme/store. Ant Design styling order: component API → `theme.useToken()` + inline `style` → `className` + CSS. English plain string literals. Follow `src/components` and `src/routes` layout.
|
||||
|
||||
- build - Build for production
|
||||
- pack - Build libraries
|
||||
- preview - Preview production build
|
||||
**Do not:** New UI libs when Ant Design suffices; bypass theme/store; CSS-first overrides when props/`styles` work; unrelated refactors in the same change.
|
||||
|
||||
### Manage Dependencies
|
||||
**Validation:** `vp check --no-fmt`; focused e2e when flows change.
|
||||
|
||||
Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles.
|
||||
---
|
||||
|
||||
- add - Add packages to dependencies
|
||||
- remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies
|
||||
- update (`up`) - Update packages to latest versions
|
||||
- dedupe - Deduplicate dependencies
|
||||
- outdated - Check for outdated packages
|
||||
- list (`ls`) - List installed packages
|
||||
- why (`explain`) - Show why a package is installed
|
||||
- info (`view`, `show`) - View package information from the registry
|
||||
- link (`ln`) / unlink - Manage local package links
|
||||
- pm - Forward a command to the package manager
|
||||
## API
|
||||
|
||||
### Maintain
|
||||
**Purpose:** **schemas → `defineApi` modules → UI**; transport in `src/api/request.ts` only.
|
||||
|
||||
- upgrade - Update `vp` itself to the latest version
|
||||
**Do:** Define APIs with `defineApi` in `src/api/<resource>.ts` (`method` default `GET`; `params`/`query`/`body` + `output`). Zod in `src/api/schemas.ts`. MSW envelopes `{ code, data, message }` aligned with schemas. Co-locate query keys (e.g. `userQueryKeys`). `hydrateSession` from `@/api/auth` after login/register/session restore.
|
||||
|
||||
These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs.
|
||||
**Do not:** Call axios or `@/api/request` from routes/components — use resource functions (`listUsers`, …). Ad-hoc response shapes; skip schema parsing; mix unrelated domains in one module.
|
||||
|
||||
## Common Pitfalls
|
||||
**Validation:** `vp check --no-fmt`.
|
||||
|
||||
- **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
|
||||
- **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead.
|
||||
- **Running scripts:** Vite+ commands take precedence over `package.json` scripts. If there is a `test` script defined in `scripts` that conflicts with the built-in `vp test` command, run it using `vp run test`.
|
||||
- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
|
||||
- **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands.
|
||||
- **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities.
|
||||
- **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box.
|
||||
---
|
||||
|
||||
## Review Checklist for Agents
|
||||
## Testing
|
||||
|
||||
- Run `vp install` after pulling remote changes and before getting started.
|
||||
- Run `vp check` and `vp test` to validate changes.
|
||||
**Purpose:** Fast, deterministic tests for core flows (auth, users CRUD, permissions).
|
||||
|
||||
## AI Instruction Files
|
||||
**Do:** User-visible assertions; reuse test helpers; keep mocks/schemas in sync; focused runs while iterating.
|
||||
|
||||
This repository also uses scoped AI instruction files in `.github/instructions/`.
|
||||
**Do not:** Brittle DOM-internal selectors; bloated fixtures; duplicate scenarios.
|
||||
|
||||
- `frontend.instructions.md` for UI/routes/components/style work
|
||||
- `testing.instructions.md` for Playwright/MSW/test updates
|
||||
- `api.instructions.md` for API/schema/handler changes
|
||||
- `refactor.instructions.md` for behavior-preserving cleanup
|
||||
**Validation:** Focused tests first; `vp check --no-fmt`.
|
||||
|
||||
See `.github/instructions/README.md` for usage and authoring rules.
|
||||
---
|
||||
|
||||
## Refactor
|
||||
|
||||
**Purpose:** Less duplication, same behavior and public contracts.
|
||||
|
||||
**Do:** One concern per change; extract shared utils/hooks/components; reviewable diffs; comments only when non-obvious.
|
||||
|
||||
**Do not:** Behavior changes unless requested; broad renames; drop unique test coverage; heavy deps for tiny wins.
|
||||
|
||||
**Considerations:** Main chunk ~135KB gzip ~41KB; vendor splits for antd/tanstack — avoid large extra UI libs. Validate at API boundaries (Zod), not app-wide runtime checks.
|
||||
|
||||
**Validation:** `vp check --no-fmt`; significant changes → `vp build` and watch chunk sizes in log.
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built with React 19, Ant Design 6, and Vite+. AI-friendly with clear patterns, shared abstractions, scoped AI instructions, and type-safe contracts at every boundary. Default UI language is English; for Lingui i18n (en + zh) out of the box, see [`apps/with-lingui`](../with-lingui/).
|
||||
Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built with React 19, Ant Design 6, and Vite+. AI-friendly with clear patterns, shared abstractions, **`AGENTS.md`** agent rules, and type-safe contracts at every boundary. Default UI language is English; for Lingui i18n (en + zh) out of the box, see [`apps/with-lingui`](../with-lingui/).
|
||||
|
||||
[](https://github.com/ant-design/ant-design)
|
||||
[](https://react.dev)
|
||||
|
||||
@@ -33,4 +33,4 @@ vp dev
|
||||
|
||||
## 权威文档
|
||||
|
||||
完整技术栈表、功能列表、目录树、E2E 子集说明、以及 **Cursor 与 `.github/instructions` 的 AI 指引** 以 **[apps/with-lingui/README.md](https://github.com/zuiidea/antd-admin/blob/master/apps/with-lingui/README.md)** 为准。
|
||||
完整技术栈表、功能列表、目录树、E2E 子集说明、以及 **AI 指引（`AGENTS.md`）** 以 **[apps/with-lingui/README.md](https://github.com/zuiidea/antd-admin/blob/master/apps/with-lingui/README.md)** 为准。
|
||||
|
||||
+3
-3
@@ -1,11 +1,11 @@
|
||||
---
|
||||
applyTo: "src/api/**/*.ts,src/mocks/**/*.ts,src/routes/_auth/**/*.tsx,e2e/**/*.spec.ts"
|
||||
description: "Use when adding a new CRUD resource (roles, tenants, etc.). Keywords: add resource, new resource, scaffold, CRUD page."
|
||||
name: add-resource
|
||||
description: Add a new CRUD resource in with-lingui (mirror users). Use when scaffolding roles, tenants, or any list+form resource with MSW, routes, menu, and e2e.
|
||||
---
|
||||
|
||||
# Add Resource Recipe
|
||||
|
||||
Add a list CRUD flow in `apps/with-lingui` that mirrors **Users** (TanStack Router + Query + MSW + Lingui). There is **no** codegen script: **copy and adapt by hand** using the steps below, or have an Agent follow this checklist. Primary references: `src/routes/_auth/users/` and the matching `e2e/*.spec.ts` files.
|
||||
Add a list CRUD flow that mirrors **Users** (TanStack Router + Query + MSW + Lingui). **No codegen** — copy and adapt by hand. References: `src/routes/_auth/users/` and matching `e2e/*.spec.ts`.
|
||||
|
||||
## 0. Verification commands (after your changes)
|
||||
|
||||
-18
@@ -1,18 +0,0 @@
|
||||
# AI Instruction Files
|
||||
|
||||
This directory contains scoped instruction files used by AI coding agents.
|
||||
|
||||
## Files
|
||||
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes
|
||||
- `testing.instructions.md`: Playwright/MSW/test changes
|
||||
- `api.instructions.md`: API client/schema/handler changes
|
||||
- `refactor.instructions.md`: behavior-preserving cleanup and deduplication
|
||||
- `add-resource.instructions.md`: add a new CRUD resource (manual / Agent checklist; mirror `users`)
|
||||
|
||||
## Authoring Rules
|
||||
|
||||
- Keep each file focused on one domain.
|
||||
- Put trigger phrases in `description` so agents can discover the file.
|
||||
- Use narrow `applyTo` patterns to avoid unnecessary context load.
|
||||
- Keep instructions executable: short Do/Do Not/Validation sections.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
applyTo: "src/api/**/*.ts,src/mocks/handlers/**/*.ts,src/mocks/createHandler.ts"
|
||||
description: "Use when editing API clients, schemas, HTTP behavior, response types, or MSW endpoint handlers. Keywords: api, request, defineApi, schema, zod, handler, endpoint, auth, users."
|
||||
---
|
||||
|
||||
# API Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Maintain strict API contracts and a single call path: **schemas → `defineApi` resource modules → UI**. Transport lives in `src/api/request.ts` (axios + interceptors).
|
||||
|
||||
## Do
|
||||
|
||||
- Define APIs with `defineApi` in `src/api/<resource>.ts` (`method` defaults to `GET`; use `params` / `query` / `body` + `output`).
|
||||
- Keep Zod schemas in `src/api/schemas.ts` as the single contract; parse inputs/outputs inside `defineApi`.
|
||||
- Keep MSW handler envelopes consistent (`code`, `data`, `message`) and aligned with schemas.
|
||||
- Co-locate React Query keys with resource modules (e.g. `userQueryKeys`).
|
||||
- Use `hydrateSession` from `@/api/auth` after login/register or when restoring a session.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not call `axios` or `@/api/request` transport helpers from routes/components — import resource functions only (`listUsers`, `login`, …).
|
||||
- Do not return ad-hoc response shapes for one-off convenience.
|
||||
- Do not bypass schema parsing in new client mutations/queries.
|
||||
- Do not mix unrelated domain endpoints in the same module.
|
||||
|
||||
## Validation
|
||||
|
||||
- Verify TypeScript and schema parsing paths compile cleanly.
|
||||
- Run: `vp check --no-fmt`
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
applyTo: "src/**/*.{ts,tsx,css}"
|
||||
description: "Use when editing React UI, route pages, components, styles, layout, i18n text, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd, i18n."
|
||||
---
|
||||
|
||||
# Frontend Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
|
||||
## Do
|
||||
|
||||
- Preserve existing route contracts and UI behavior unless explicitly asked.
|
||||
- Prefer reusable components and hooks over copy-paste logic.
|
||||
- Keep styles token-driven using existing theme/store patterns.
|
||||
- For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS.
|
||||
- Keep translations compatible with Lingui macros and catalogs.
|
||||
- Follow current folder conventions under src/components and src/routes.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not introduce new UI libraries when Ant Design already covers the need.
|
||||
- Do not bypass existing theme/store abstractions with hardcoded global state.
|
||||
- Do not write CSS overrides first when props or semantic `styles` can express the same UI.
|
||||
- Do not refactor unrelated files in the same change.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run: `pnpm exec vp check --no-fmt`
|
||||
- For UI flow changes, run focused e2e where possible.
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
applyTo: "src/**/*.{ts,tsx}"
|
||||
description: "Use when refactoring existing code for deduplication, modularization, naming cleanup, or maintainability improvements without behavior changes. Keywords: refactor, cleanup, simplify, deduplicate, maintainability."
|
||||
---
|
||||
|
||||
# Refactor Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Reduce duplication while preserving behavior and public contracts.
|
||||
|
||||
## Do
|
||||
|
||||
- Keep refactors incremental and scoped to one concern per change.
|
||||
- Prefer extracting shared utilities/hooks/components over large rewrites.
|
||||
- Preserve existing external behavior and route/store contracts.
|
||||
- Keep diffs reviewable with minimal unrelated formatting churn.
|
||||
- Add or update lightweight comments only when logic is non-obvious.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not change runtime behavior unless explicitly requested.
|
||||
- Do not rename broadly across the codebase without clear benefit.
|
||||
- Do not delete tests that still cover unique critical scenarios.
|
||||
- Do not introduce large dependencies for minor convenience; prefer composition or small utilities.
|
||||
|
||||
## Considerations
|
||||
|
||||
- Bundle: Main app chunk is ~135KB (gzip ~41KB). Ant Design (vendor-antd) and TanStack (vendor-tanstack) are in separate chunks for parallel loading. Avoid adding large UI libraries when Ant Design covers the need.
|
||||
- Type safety: Keep validations at API boundaries (Zod schemas) rather than adding more runtime checks throughout the app.
|
||||
|
||||
## Validation
|
||||
|
||||
- Confirm no new diagnostics in touched files.
|
||||
- Run: `pnpm exec vp check --no-fmt`
|
||||
- For significant changes, verify bundle size impact: `pnpm run build 2>&1 | grep "kB"`
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
|
||||
## applyTo: "e2e/**/\*.ts,e2e/**/_.tsx,src/mocks/\*\*/_.ts,playwright.config.ts"
|
||||
|
||||
description: "Use when adding or editing tests, Playwright cases, MSW handlers, mock data, or test configuration. Keywords: test, e2e, playwright, mock, msw, coverage."
|
||||
|
||||
# Testing Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Keep tests fast, deterministic, and aligned with core business flows.
|
||||
|
||||
## Do
|
||||
|
||||
- Prioritize core flows first (auth, users CRUD, permission gates).
|
||||
- Keep assertions user-visible and behavior-focused.
|
||||
- Reuse existing helper patterns in tests before adding new helpers.
|
||||
- Keep mock handlers and mock data synchronized with API schemas.
|
||||
- Prefer focused test runs over full-suite runs during iteration.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not add brittle selectors tied to unstable DOM internals.
|
||||
- Do not expand fixture data without a clear scenario need.
|
||||
- Do not duplicate scenarios already covered by existing tests.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run focused tests first, then broader checks if needed.
|
||||
- Run: `pnpm exec vp check --no-fmt`
|
||||
- Unit / hook logic (Vitest): `pnpm run test:unit` — tests live under `src/**/*.test.ts`.
|
||||
+52
-62
@@ -1,89 +1,79 @@
|
||||
# Using Vite+, the Unified Toolchain for the Web
|
||||
# antd-admin (with-lingui)
|
||||
|
||||
This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`.
|
||||
Vite+ template app (React 19, Ant Design 6, Lingui i18n, TanStack Router/Query, MSW). CLI details: [viteplus.dev](https://viteplus.dev).
|
||||
|
||||
## Vite+ Workflow
|
||||
## Commands
|
||||
|
||||
`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
|
||||
Run from **`apps/with-lingui`** (this directory):
|
||||
|
||||
### Start
|
||||
| Task | Command |
|
||||
| ------------------------- | ---------------------------------------------------------------------------- |
|
||||
| Install deps | `vp install` (after every pull) |
|
||||
| Dev / build / preview | `vp dev`, `vp build`, `vp preview` |
|
||||
| Format / lint / typecheck | `vp check`, `vp check --no-fmt`, `vp lint`, `vp fmt` |
|
||||
| Unit tests | `vp test run` (`src/**/*.test.ts`) |
|
||||
| E2E | `pnpm run test:e2e` / `test:e2e:core` |
|
||||
| i18n | `pnpm run i18n:extract && pnpm run i18n:compile` after new translatable copy |
|
||||
| Add/remove deps | `vp add`, `vp remove` — not raw `pnpm`/`npm`/`yarn` |
|
||||
|
||||
- create - Create a new project from a template
|
||||
- migrate - Migrate an existing project to Vite+
|
||||
- config - Configure hooks and agent integration
|
||||
- staged - Run linters on staged files
|
||||
- install (`i`) - Install dependencies
|
||||
- env - Manage Node.js versions
|
||||
**Pitfalls:** Do not install Vitest/Oxlint/Oxfmt/tsdown directly; use `vp`. Do not run `vp vitest` — use `vp test`. If a `package.json` script name conflicts with a built-in `vp` command, use `vp run <script>`. Import toolchain modules from `vite-plus`, not standalone `vite`/`vitest` packages.
|
||||
|
||||
### Develop
|
||||
**Before finishing:** `vp check` and `vp test run`; run focused e2e when UI flows change.
|
||||
|
||||
- dev - Run the development server
|
||||
- check - Run format, lint, and TypeScript type checks
|
||||
- lint - Lint code
|
||||
- fmt - Format code
|
||||
- test - Run tests
|
||||
**Monorepo:** If this app lives under [antd-admin](https://github.com/zuiidea/antd-admin), read repo-root `AGENTS.md` for turbo/git hooks; still run `vp` from this directory.
|
||||
|
||||
### Execute
|
||||
---
|
||||
|
||||
- run - Run monorepo tasks
|
||||
- exec - Execute a command from local `node_modules/.bin`
|
||||
- dlx - Execute a package binary without installing it as a dependency
|
||||
- cache - Manage the task cache
|
||||
## Frontend
|
||||
|
||||
### Build
|
||||
**Purpose:** Predictable, minimal UI changes under `src/`.
|
||||
|
||||
- build - Build for production
|
||||
- pack - Build libraries
|
||||
- preview - Preview production build
|
||||
**Do:** Preserve route/UI contracts unless asked. Reuse components/hooks. Token-driven styles. Ant Design styling order: component API → `theme.useToken()` + inline `style` → `className` + CSS. Lingui macros/catalogs for copy. Follow `src/components` and `src/routes` layout.
|
||||
|
||||
### Manage Dependencies
|
||||
**Do not:** New UI libs when Ant Design suffices; bypass theme/store; CSS-first overrides when props/`styles` work; unrelated refactors in the same change.
|
||||
|
||||
Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles.
|
||||
**Validation:** `pnpm exec vp check --no-fmt`; focused e2e when flows change.
|
||||
|
||||
- add - Add packages to dependencies
|
||||
- remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies
|
||||
- update (`up`) - Update packages to latest versions
|
||||
- dedupe - Deduplicate dependencies
|
||||
- outdated - Check for outdated packages
|
||||
- list (`ls`) - List installed packages
|
||||
- why (`explain`) - Show why a package is installed
|
||||
- info (`view`, `show`) - View package information from the registry
|
||||
- link (`ln`) / unlink - Manage local package links
|
||||
- pm - Forward a command to the package manager
|
||||
---
|
||||
|
||||
### Maintain
|
||||
## API
|
||||
|
||||
- upgrade - Update `vp` itself to the latest version
|
||||
**Purpose:** **schemas → `defineApi` modules → UI**; transport in `src/api/request.ts` only.
|
||||
|
||||
These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs.
|
||||
**Do:** Define APIs with `defineApi` in `src/api/<resource>.ts` (`method` default `GET`; `params`/`query`/`body` + `output`). Zod in `src/api/schemas.ts`. MSW envelopes `{ code, data, message }` aligned with schemas. Co-locate query keys (e.g. `userQueryKeys`). `hydrateSession` from `@/api/auth` after login/register/session restore.
|
||||
|
||||
## Common Pitfalls
|
||||
**Do not:** Call axios or `@/api/request` from routes/components — use resource functions (`listUsers`, …). Ad-hoc response shapes; skip schema parsing; mix unrelated domains in one module.
|
||||
|
||||
- **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
|
||||
- **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead.
|
||||
- **Running scripts:** Vite+ commands take precedence over `package.json` scripts. If there is a `test` script defined in `scripts` that conflicts with the built-in `vp test` command, run it using `vp run test`.
|
||||
- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
|
||||
- **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands.
|
||||
- **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities.
|
||||
- **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box.
|
||||
**Validation:** `vp check --no-fmt`.
|
||||
|
||||
## Review Checklist for Agents
|
||||
---
|
||||
|
||||
- Run `vp install` after pulling remote changes and before getting started.
|
||||
- Run `vp check` and `vp test` to validate changes.
|
||||
## Testing
|
||||
|
||||
## Monorepo git hooks
|
||||
**Purpose:** Fast, deterministic tests for core flows (auth, users CRUD, permissions).
|
||||
|
||||
When this app lives under a monorepo, `git config core.hooksPath` may point at `.vite-hooks/_` here while commits run with the **repository root** as cwd. The checked-in `.vite-hooks/pre-commit` script dispatches `vp staged` into `apps/with-lingui` and `apps/basic` based on staged paths (and runs `pnpm --dir packages/create run check-types` for matching `packages/create` sources) so each app’s `vite.config.ts` is found.
|
||||
**Do:** User-visible assertions; reuse test helpers; keep mocks/schemas in sync; focused runs while iterating.
|
||||
|
||||
## AI Instruction Files
|
||||
**Do not:** Brittle DOM-internal selectors; bloated fixtures; duplicate scenarios.
|
||||
|
||||
This repository also uses scoped AI instruction files in `.github/instructions/`.
|
||||
**Validation:** Focused tests first; `pnpm exec vp check --no-fmt`; unit/hooks: `pnpm run test:unit`.
|
||||
|
||||
- `frontend.instructions.md` for UI/routes/components/style work
|
||||
- `testing.instructions.md` for Playwright/MSW/test updates
|
||||
- `api.instructions.md` for API/schema/handler changes
|
||||
- `refactor.instructions.md` for behavior-preserving cleanup
|
||||
- `add-resource.instructions.md` for adding a new CRUD resource (checklist; mirror `users`)
|
||||
---
|
||||
|
||||
See `.github/instructions/README.md` for usage and authoring rules.
|
||||
## Refactor
|
||||
|
||||
**Purpose:** Less duplication, same behavior and public contracts.
|
||||
|
||||
**Do:** One concern per change; extract shared utils/hooks/components; reviewable diffs; comments only when non-obvious.
|
||||
|
||||
**Do not:** Behavior changes unless requested; broad renames; drop unique test coverage; heavy deps for tiny wins.
|
||||
|
||||
**Considerations:** Main chunk ~135KB gzip ~41KB; vendor splits for antd/tanstack — avoid large extra UI libs. Validate at API boundaries (Zod), not app-wide runtime checks.
|
||||
|
||||
**Validation:** `pnpm exec vp check --no-fmt`; significant changes → `vp build` and watch chunk sizes in log.
|
||||
|
||||
---
|
||||
|
||||
## Add CRUD resource
|
||||
|
||||
Multi-step checklist (mirror **users**): use skill **`.agents/skills/add-resource/SKILL.md`** (invoke in Copilot/Codex/Claude or `@` that path in chat). After routes change, run `pnpm run build` to refresh `routeTree.gen.ts`.
|
||||
|
||||
@@ -106,7 +106,8 @@ pnpm run i18n:extract && git diff --exit-code -- src/locales
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.github/instructions/ # Scoped AI guidance (frontend/testing/api/refactor/add-resource)
|
||||
AGENTS.md # Agent rules (frontend/api/testing/refactor)
|
||||
.agents/skills/add-resource/ # CRUD scaffold checklist (Skill)
|
||||
src/
|
||||
├── api/ # schemas, request (axios + defineApi), resource APIs
|
||||
├── components/ # Reusable UI primitives and layout shells
|
||||
@@ -180,13 +181,13 @@ Ant Design strings follow the active locale via `ConfigProvider` in `__root.tsx`
|
||||
|
||||
## Extending the template
|
||||
|
||||
- **New CRUD resource:** See `.github/instructions/add-resource.instructions.md` (checklist; copy from `users`), then `pnpm run i18n:extract && pnpm run i18n:compile`, wire Sidebar labels/icons if needed (§6b in that doc), and `pnpm exec vp check --no-fmt`.
|
||||
- **New CRUD resource:** Follow `.agents/skills/add-resource/SKILL.md` (mirror `users`), then `pnpm run i18n:extract && pnpm run i18n:compile`, and `pnpm exec vp check --no-fmt`.
|
||||
- **Real backend:** Point `VITE_API_BASE_URL` in env and disable or remove MSW in `main.tsx` when you no longer need mocks.
|
||||
- **Drop i18n:** Remove Lingui packages, vite/swc plugins, and replace `t` macros with plain strings (larger refactor).
|
||||
|
||||
### AI instruction files
|
||||
### AI guidance
|
||||
|
||||
**Single source of truth**: `.github/instructions/` (`*.instructions.md`). Both humans and agents should maintain and review guidance from this directory. See also `AGENTS.md` for the Vite+ workflow. In chat, reference files with `@.github/instructions/…` (for example `@.github/instructions/frontend.instructions.md`).
|
||||
**Single source of truth:** **`AGENTS.md`** in this app (commands + Frontend/API/Testing/Refactor rules). New CRUD flows: `@.agents/skills/add-resource/SKILL.md`.
|
||||
|
||||
## Developer Notes
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
> 状态：已部分落地（更新于 2026-04-27）
|
||||
> 计划日期：2026-04-24
|
||||
> 范围：以 `apps/with-lingui` 为主模板（`apps/basic` 为英文、无 Lingui 的对照应用；**CRUD 页面级示例仅以 `users` 为样板**，不设第二示例资源）
|
||||
> 面向：人类贡献者 + AI Agent（结合 `.github/instructions/` 指令体系执行）
|
||||
> 面向：人类贡献者 + AI Agent（**现行**：各 app 的 `AGENTS.md` + `.agents/skills/`；下文若提及 `.github/instructions/*.instructions.md` 为历史方案）
|
||||
|
||||
## 0. 背景
|
||||
|
||||
|
||||
Reference in New Issue
Block a user