mirror of
https://github.com/zuiidea/antd-admin
synced 2026-11-03 16:46:12 +00:00
refactor(api): modular defineApi layer with shared API_PREFIX (#1181)
* refactor(api): introduce defineApi + axios request layer Replace ad-hoc fetch httpClient with api/request.ts (axios interceptors, envelope unwrap, auth refresh) and defineApi-based resource modules. Move session hydration into api/auth, sync both templates, and update docs. Co-authored-by: zuiidea <zuiiidea@gmail.com> * chore: unify Cursor rules, fix monorepo install hooks, refresh basic docs Add root preinstall to set githooks and disable parallel vp config git lock races; merge per-app Cursor thin rules into app.mdx; keep template READMEs free of monorepo-only paths and describe basic as default English rather than English-only. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: add root turbo fmt and format app sources Expose fmt via turbo at the monorepo root, apply Oxfmt in basic/with-lingui, and run vp staged through pnpm exec in pre-commit so hooks work without a global vp. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: drop root eslint/prettier and bump turbo to 2.11.9 Root formatting and lint stay on turbo fmt/lint via Vite+ in workspace apps. Co-authored-by: Cursor <cursoragent@cursor.com> * 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> * 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> * refactor(api): split modules under shared/ with API_PREFIX Move auth and users into folder modules, centralize path constants, and align MSW with endpoint paths in both template apps. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: document modular API layer in README files Expand template READMEs with src/api layout, fix CLI table and E2E script references. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: align site with modular src/api layout Document API_PREFIX, folder structure, templates, and E2E script usage in en/zh. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: zuiidea <zuiidea@example.com>
This commit is contained in:
zuiidea
co-authored by
Cursor
zuiidea
Cursor
zuiidea
parent
60ef2fe7f8
commit
4dc473ba55
-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,67 +0,0 @@
|
||||
---
|
||||
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."
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
## 0. Verification commands (after your changes)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 1. Zod and types (`src/api/schemas.ts`)
|
||||
|
||||
- Define `<Entity>Schema`, `Create<Entity>RequestSchema`, `Update<Entity>RequestSchema` (`Update` = `Create.partial()`).
|
||||
- Reuse `PaginatedResponseSchema(<Entity>Schema)` for list responses.
|
||||
- Export `type <Entity> = z.infer<typeof ...>`.
|
||||
|
||||
## 2. Endpoint constants (`src/api/<slug>.ts`)
|
||||
|
||||
- Export `<SLUG_UPPER>_ENDPOINTS`: `list` / `create` / `update(id)` / `delete(id)` with paths like `/api/<slug>`.
|
||||
|
||||
## 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` (recommended: `optimistic: { update: true, delete: true }`), `useCrudToasts`, `useUrlSearchState`, `useTableFitHeight` (see `users/` for splitting `-Toolbar` / `-FormModal`).
|
||||
- **Lingui**: run `pnpm run i18n:extract && pnpm run i18n:compile` for new copy (or `vp exec lingui …`).
|
||||
|
||||
## 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 a Lingui `msg` entry 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`.
|
||||
- Then run `pnpm run i18n:extract && pnpm run i18n:compile` and fill in `zh` (and other locale) translations.
|
||||
|
||||
## 7. E2E (`e2e/<slug>.spec.ts`)
|
||||
|
||||
- Copy structure from `users.spec.ts`: `loginAsAdmin` → `goto /<slug>`, assert headers / search placeholder, etc.
|
||||
|
||||
## 8. Verification
|
||||
|
||||
- `pnpm exec vp check --no-fmt`
|
||||
- `pnpm run test:e2e:core` (if you add the new spec to core) or `pnpm exec playwright test e2e/<slug>.spec.ts`
|
||||
- `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.
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
applyTo: "src/api/**/*.ts,src/utils/http.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, http, schema, zod, handler, endpoint, auth, users."
|
||||
---
|
||||
|
||||
# API Instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
Maintain strict API contracts and consistent server/client mock behavior.
|
||||
|
||||
## Do
|
||||
|
||||
- Keep request/response shapes schema-driven and type-safe.
|
||||
- Reuse endpoint constants and shared response helpers.
|
||||
- Keep handler response envelope consistent (`code`, `data`, `message`).
|
||||
- MSW success payloads: use `successWithSchema` / `paginatedWithSchema` / `successWithNullBody` from `src/mocks/createHandler.ts` so responses match Zod contracts before `HttpResponse.json`.
|
||||
- Ensure mock handlers reflect real API behavior and error semantics.
|
||||
- Keep naming stable for endpoint keys and mutation/query keys.
|
||||
|
||||
## Do Not
|
||||
|
||||
- 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: `pnpm exec vp check --no-fmt`
|
||||
- After changing `createHandler` or handler envelopes: `pnpm run test:unit` (includes `src/mocks/createHandler.test.ts`).
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user