diff --git a/apps/basic/.agents/skills/add-resource/SKILL.md b/apps/basic/.agents/skills/add-resource/SKILL.md new file mode 100644 index 0000000..8871f05 --- /dev/null +++ b/apps/basic/.agents/skills/add-resource/SKILL.md @@ -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/.spec.ts +``` + +## 1. Zod and types (`src/api/schemas.ts`) + +- Define `Schema`, `CreateRequestSchema`, `UpdateRequestSchema` (`Update` = `Create.partial()`). +- For list `output`, reuse `PaginatedDataSchema(Schema)` (unwrapped `data`; envelope stays in `request.ts`). +- Add list query schema (e.g. `ListQuerySchema`) when the table has filters/pagination. +- Export `type = z.infer`. + +## 2. Resource API module (`src/api/.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_` array. For **admin** users, `permissions` must include `:view` (and create/edit/delete if you add writes), aligned with `GET /api/auth/permissions`. + +## 4. MSW (`src/mocks/handlers/.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 `...Handlers` in `handlers/index.ts`. + +## 5. Route page (`src/routes/_auth//`) + +- `createFileRoute("/_auth//")`, wiring `useResourceCRUD` with resource functions (`listX`, `createX`, …) and `queryKeys` from `@/api/` (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: "/"`, `permissions: [":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/.spec.ts`) + +- Copy structure from `users.spec.ts`: `loginAsAdmin` → `goto /`, 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. diff --git a/apps/basic/AGENTS.md b/apps/basic/AGENTS.md index d9d4eb4..a4bd5d2 100644 --- a/apps/basic/AGENTS.md +++ b/apps/basic/AGENTS.md @@ -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`. diff --git a/apps/basic/README.md b/apps/basic/README.md index 6c211c2..6bb3e6b 100644 --- a/apps/basic/README.md +++ b/apps/basic/README.md @@ -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`. diff --git a/apps/with-lingui/.agents/skills/add-resource/SKILL.md b/apps/with-lingui/.agents/skills/add-resource/SKILL.md index 2190d19..f5f6f7a 100644 --- a/apps/with-lingui/.agents/skills/add-resource/SKILL.md +++ b/apps/with-lingui/.agents/skills/add-resource/SKILL.md @@ -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/.spec.ts diff --git a/apps/with-lingui/AGENTS.md b/apps/with-lingui/AGENTS.md index 9b3de76..5712134 100644 --- a/apps/with-lingui/AGENTS.md +++ b/apps/with-lingui/AGENTS.md @@ -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 | | ------------------------- | ---------------------------------------------------------------------------- |