mirror of
https://github.com/zuiidea/antd-admin
synced 2026-11-01 07:20:20 +00:00
chore(basic): add add-resource skill and portable app-root paths
Align basic with with-lingui for CRUD scaffolding via AGENTS.md and .agents/skills, and drop hardcoded monorepo paths in agent docs. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zuiidea
Cursor
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: add-resource
|
||||
description: Add a new CRUD resource in antd-admin-basic (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 that mirrors **Users** (TanStack Router + Query + MSW). **No codegen** — copy and adapt by hand. References: `src/routes/_auth/users/` and matching `e2e/*.spec.ts`. UI copy is **English plain strings** (no i18n).
|
||||
|
||||
## 0. Verification commands (after your changes)
|
||||
|
||||
Run from the **app root** (this project directory — where `package.json` and `vite.config.ts` live):
|
||||
|
||||
```bash
|
||||
pnpm run build # refresh TanStack routeTree when routes change
|
||||
vp check --no-fmt
|
||||
pnpm run test:e2e -- e2e/<slug>.spec.ts
|
||||
```
|
||||
|
||||
## 1. Zod and types (`src/api/schemas.ts`)
|
||||
|
||||
- Define `<Entity>Schema`, `Create<Entity>RequestSchema`, `Update<Entity>RequestSchema` (`Update` = `Create.partial()`).
|
||||
- For list `output`, reuse `PaginatedDataSchema(<Entity>Schema)` (unwrapped `data`; envelope stays in `request.ts`).
|
||||
- Add list query schema (e.g. `List<Entity>QuerySchema`) when the table has filters/pagination.
|
||||
- Export `type <Entity> = z.infer<typeof ...>`.
|
||||
|
||||
## 2. Resource API module (`src/api/<slug>.ts`)
|
||||
|
||||
- Export path constants if useful for MSW/docs.
|
||||
- Define APIs with `defineApi` from `@/api/request`: `list` / `create` / `update` / `delete` (and `queryKeys`).
|
||||
- `method` defaults to `GET`; mutations set `POST` / `PUT` / `DELETE`.
|
||||
- Use segmented `params` / `query` / `body` + `output`; do not call axios from routes.
|
||||
|
||||
## 3. Mock data (`src/mocks/data.ts`)
|
||||
|
||||
- Append a `MOCK_<ENTITIES>` array. For **admin** users, `permissions` must include `<slug>:view` (and create/edit/delete if you add writes), aligned with `GET /api/auth/permissions`.
|
||||
|
||||
## 4. MSW (`src/mocks/handlers/<slug>.ts` + `handlers/index.ts`)
|
||||
|
||||
- Follow `handlers/user.ts`: paginated `GET` + optional `keyword`, `POST` / `PUT` / `DELETE`; use `successWithSchema` / `paginatedWithSchema` / `successWithNullBody` for success and `errorResponse` for errors.
|
||||
- Register `...<slug>Handlers` in `handlers/index.ts`.
|
||||
|
||||
## 5. Route page (`src/routes/_auth/<slug>/`)
|
||||
|
||||
- `createFileRoute("/_auth/<slug>/")`, wiring `useResourceCRUD` with resource functions (`listX`, `createX`, …) and `queryKeys` from `@/api/<slug>` (recommended: `optimistic: { update: true, delete: true }`), plus `useCrudToasts`, `useUrlSearchState`, `useTableFitHeight` (see `users/` for splitting `-Toolbar` / `-FormModal`).
|
||||
- Use English string literals for labels, placeholders, and messages.
|
||||
|
||||
## 6. Menu and permissions (`src/utils/appMenu.ts`)
|
||||
|
||||
- Add a menu entry to `APP_MENU_TREE`: `path: "/<slug>"`, `permissions: ["<slug>:view"]`, `icon` using a Sidebar-registered key (see existing `IconLucide*` entries in `Sidebar`).
|
||||
- Keep behavior consistent with `canAccessPath` / 403.
|
||||
|
||||
## 6b. Sidebar labels and icons (`src/components/Layout/Sidebar/index.tsx`)
|
||||
|
||||
- In `MENU_LABELS`, add an English label for the menu item `name` (must match the `name` string from `appMenu`).
|
||||
- In `MENU_ICON_MAP`, map the new `icon` key to a `lucide-react` icon and add the matching `import`.
|
||||
|
||||
## 7. E2E (`e2e/<slug>.spec.ts`)
|
||||
|
||||
- Copy structure from `users.spec.ts`: `loginAsAdmin` → `goto /<slug>`, assert headers / search placeholder, etc.
|
||||
|
||||
## 8. Verification
|
||||
|
||||
- `vp check --no-fmt`
|
||||
- `pnpm run test:e2e` (focused spec) or full suite as needed
|
||||
- `pnpm run build` and watch chunk sizes in the log
|
||||
|
||||
## Notes
|
||||
|
||||
- Before adding or renaming files, confirm nothing already exists at that path so you do not overwrite hand-written code.
|
||||
- After manual schema edits, treat the diff as source of truth; there is no automatic merge.
|
||||
@@ -4,7 +4,7 @@ Vite+ template app (React 19, Ant Design 6, TanStack Router/Query, MSW). Default
|
||||
|
||||
## Commands
|
||||
|
||||
Run from **`apps/basic`** (this directory):
|
||||
Run from **this app root** (directory with `package.json` / `vite.config.ts`):
|
||||
|
||||
| Task | Command |
|
||||
| ------------------------- | ---------------------------------------------------- |
|
||||
@@ -68,3 +68,9 @@ Run from **`apps/basic`** (this directory):
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 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`.
|
||||
|
||||
@@ -103,6 +103,8 @@ pnpm run test:e2e:ui # interactive UI mode
|
||||
## Project Structure
|
||||
|
||||
```text
|
||||
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
|
||||
@@ -162,9 +164,14 @@ User-facing copy lives in components and routes as plain strings. **Default lang
|
||||
|
||||
## Extending the template
|
||||
|
||||
- **New CRUD resource:** Follow `.agents/skills/add-resource/SKILL.md` (mirror `users`), then `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.
|
||||
- **Add i18n:** Integrate your preferred stack, or copy patterns from [`apps/with-lingui`](../with-lingui/).
|
||||
|
||||
### AI guidance
|
||||
|
||||
**Single source of truth:** **`AGENTS.md`** in this app. New CRUD flows: `@.agents/skills/add-resource/SKILL.md`.
|
||||
|
||||
## Developer Notes
|
||||
|
||||
- Prefer Vite+ commands for installs, checks, and scripts. This repo is configured around `vp`.
|
||||
|
||||
@@ -9,8 +9,9 @@ Add a list CRUD flow that mirrors **Users** (TanStack Router + Query + MSW + Lin
|
||||
|
||||
## 0. Verification commands (after your changes)
|
||||
|
||||
Run from the **app root** (this project directory — where `package.json` and `vite.config.ts` live):
|
||||
|
||||
```bash
|
||||
cd apps/with-lingui
|
||||
pnpm run build # refresh TanStack routeTree when routes change
|
||||
pnpm exec vp check --no-fmt
|
||||
pnpm run test:e2e -- e2e/<slug>.spec.ts
|
||||
|
||||
@@ -4,7 +4,7 @@ Vite+ template app (React 19, Ant Design 6, Lingui i18n, TanStack Router/Query,
|
||||
|
||||
## Commands
|
||||
|
||||
Run from **`apps/with-lingui`** (this directory):
|
||||
Run from **this app root** (directory with `package.json` / `vite.config.ts`):
|
||||
|
||||
| Task | Command |
|
||||
| ------------------------- | ---------------------------------------------------------------------------- |
|
||||
|
||||
Reference in New Issue
Block a user