Alawn/antd-admin
1
0
Fork 0
mirror of https://github.com/zuiidea/antd-admin synced 2026-10-26 18:28:57 +00:00
Code Issues Releases Wiki Activity

docs: document modular API layer in README files

Browse Source 
Expand template READMEs with src/api layout, fix CLI table and E2E script references.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zuiidea
2026-10-18 21:14:30 +08:00
co-authored by Cursor
parent c02f6dc2f2
commit bb141469e1
3 changed files with 48 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+10 -9
View File
@@ -20,6 +20,7 @@ Scaffolding CLI:
- URL-synced table state (pagination, sorting, search)
- Dark mode theme switching
- Mock-first local development (no backend required)
- Modular API layer (`defineApi` per domain, Zod schemas, shared `API_PREFIX`)
- Typed API boundaries and reusable CRUD patterns
- React 19 + Ant Design 6 + TanStack Router/Query + Zustand + Zod
- Optional Lingui-based i18n workflow (`with-lingui`)
@@ -48,15 +49,15 @@ pnpm dlx init-antd-admin@latest my-app --example with-lingui --skip-install
### Common options
| Option | Description |
| ---------------------------- | -------------------------------- |
| `[project-directory]` | Target folder |
| `-e, --example <name | url>` |
| `--example-path <path>` | Subpath inside remote repository |
| `-m, --package-manager <pm>` | `npm` / `pnpm` / `yarn` / `bun` |
| `--skip-install` | Skip dependency install |
| `--skip-transforms` | Skip rewrite transforms |
| `--no-git` | Skip git initialization |
| Option | Description |
| ---------------------------- | ------------------------------------------ |
| `[project-directory]` | Target folder |
| `-e, --example <name\|url>` | Template name (`basic`, `with-lingui`) or URL |
| `--example-path <path>` | Subpath inside remote repository |
| `-m, --package-manager <pm>` | `npm` / `pnpm` / `yarn` / `bun` |
| `--skip-install` | Skip dependency install |
| `--skip-transforms` | Skip rewrite transforms |
| `--no-git` | Skip git initialization |
For detailed CLI behavior, see `[packages/create/README.md](./packages/create/README.md)`.
apps/basic/README.md
+22 -3
View File
@@ -35,7 +35,7 @@ Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built
| Icons | [lucide-react](https://lucide.dev/guide/packages/lucide-react) |
| API Mocking | [MSW 2.x](https://mswjs.io) (Service Worker based) |
| E2E Testing | [Playwright](https://playwright.dev) |
| Language | TypeScript 5.9 (strict mode) |
| Language | TypeScript (strict mode) |
## Features
@@ -44,6 +44,7 @@ Admin scaffold: MSW mocks, minimal RBAC, full CRUD, and Playwright E2E — built
- **URL-First State** — Table search params (page, pageSize, keyword, sort) synced to URL
- **Default locale** — UI copy in plain strings (English by default); Ant Design `ConfigProvider` uses `en_US`.
- **Dark Mode** — One-click toggle with Ant Design theme algorithm
- **Modular API layer** — `defineApi` modules under `src/api/<domain>/`, shared Zod helpers, single `API_PREFIX`
- **Full Type Safety** — Zod schemas validate API boundaries at runtime where used
- **Zero-Config Mocking** — MSW intercepts API calls in development, no backend needed
@@ -96,7 +97,7 @@ pnpm run test:unit
```bash
pnpm run test:e2e
pnpm run test:e2e:core
pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # core flows only
pnpm run test:e2e:ui # interactive UI mode
```
@@ -106,7 +107,12 @@ pnpm run test:e2e:ui # interactive UI mode
AGENTS.md # Agent rules (frontend/api/testing/refactor)
.agents/skills/add-resource/ # CRUD scaffold checklist (Skill)
src/
├── api/ # request.ts, shared/, auth/, users/, … (defineApi per module)
├── api/ # HTTP + contracts (see “API layer” below)
│ ├── request.ts # axios, defineApi, token refresh, envelope unwrap
│ ├── schemas.ts # deprecated barrel; prefer @/api/shared and module schemas
│ ├── shared/ # API_PREFIX, pagination, params, menu, envelope helpers
│ ├── auth/ # paths, schemas, login/register/hydrateSession
│ └── users/ # schemas, listUsers CRUD, userQueryKeys, path constants
├── components/ # Reusable UI primitives and layout shells
│ ├── Layout/ # MainLayout, Header, Sidebar, UserMenu, AppFooter
│ ├── DataTable/ # Shared table frame/skeleton/empty state
@@ -158,6 +164,19 @@ e2e/ # Playwright E2E suites
└── url-state.spec.ts
```
## API layer
Data flow: **Zod schemas → `defineApi` in `src/api/<module>/index.ts` → routes/components call resource functions** (never axios or `@/api/request` directly).
| Piece | Role |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `request.ts` | Shared HTTP client, `{ code, data, message }` handling, 401 refresh |
| `shared/` | `API_PREFIX` (`/api`), pagination/query helpers, shared menu types |
| `auth/`, `users/` | Domain schemas + `defineApi` exports; MSW handlers import the same path constants |
| `schemas.ts` | Compatibility re-exports; new code should import from `@/api/shared` and `@/api/<module>/schemas` |
Change the REST prefix in one place: `src/api/shared/prefix.ts` (`API_PREFIX`).
## Language
User-facing copy lives in components and routes as plain strings. **Default language is English**; Ant Design is wired to `en_US` in `__root.tsx`. This template does not include a locale switcher or translation catalogs—you can add your own i18n library or start from the [`with-lingui`](../with-lingui/) template for LinguiJS (en + zh).
apps/with-lingui/README.md
+16 -6
View File
@@ -25,7 +25,7 @@ Balanced admin scaffold: i18n (Lingui), MSW mocks, minimal RBAC, full CRUD, and
| Icons | [lucide-react](https://lucide.dev/guide/packages/lucide-react) |
| API Mocking | [MSW 2.x](https://mswjs.io) (Service Worker based) |
| E2E Testing | [Playwright](https://playwright.dev) |
| Language | TypeScript 5.9 (strict mode) |
| Language | TypeScript (strict mode) |
## Features
@@ -34,6 +34,7 @@ Balanced admin scaffold: i18n (Lingui), MSW mocks, minimal RBAC, full CRUD, and
- **URL-First State** — Table search params (page, pageSize, keyword, sort) synced to URL
- **i18n** — LinguiJS with English (`en`) and Chinese (`zh`); Ant Design locales wired in root
- **Dark Mode** — One-click toggle with Ant Design theme algorithm
- **Modular API layer** — `defineApi` modules under `src/api/<domain>/`, shared Zod helpers, single `API_PREFIX`
- **Full Type Safety** — Zod schemas validate API boundaries at runtime where used
- **Zero-Config Mocking** — MSW intercepts API calls in development, no backend needed
@@ -86,7 +87,7 @@ pnpm run test:unit
```bash
pnpm run test:e2e
pnpm run test:e2e:core
pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # core flows only
pnpm run test:e2e:ui # interactive UI mode
```
@@ -100,7 +101,7 @@ vp exec lingui extract -- --clean
vp exec lingui compile
# CI-oriented check: extract + ensure no pending locale diff
pnpm run i18n:extract && git diff --exit-code -- src/locales
pnpm run i18n:check
```
## Project Structure
@@ -109,7 +110,12 @@ pnpm run i18n:extract && git diff --exit-code -- src/locales
AGENTS.md # Agent rules (frontend/api/testing/refactor)
.agents/skills/add-resource/ # CRUD scaffold checklist (Skill)
src/
├── api/ # request.ts, shared/, auth/, users/, … (defineApi per module)
├── api/ # HTTP + contracts (see “API layer” below)
│ ├── request.ts # axios, defineApi, token refresh, envelope unwrap
│ ├── schemas.ts # deprecated barrel; prefer @/api/shared and module schemas
│ ├── shared/ # API_PREFIX, pagination, params, menu, envelope helpers
│ ├── auth/ # paths, schemas, login/register/hydrateSession
│ └── users/ # schemas, listUsers CRUD, userQueryKeys, path constants
├── components/ # Reusable UI primitives and layout shells
│ ├── Layout/ # MainLayout, Header, Sidebar, UserMenu, AppFooter
│ ├── DataTable/ # Shared table frame/skeleton/empty state
@@ -166,9 +172,13 @@ e2e/ # Playwright E2E suites
```
## API layer
Same layout as [`apps/basic`](../basic/): **schemas → `defineApi` in `src/api/<module>/index.ts` → UI imports `@/api/users`, `@/api/auth`, etc.** Transport stays in `request.ts`; path constants (`API_PREFIX`, `AUTH_ENDPOINTS`, `USERS_PATH`) are shared with MSW handlers.
## Internationalization (i18n)
The project uses [LinguiJS](https://lingui.dev) with compile-time macros. Locales: `**en**` (source) and `**zh**`.
The project uses [LinguiJS](https://lingui.dev) with compile-time macros. Locales: **en** (source) and **zh**.
### Workflow
@@ -181,7 +191,7 @@ Ant Design strings follow the active locale via `ConfigProvider` in `__root.tsx`
## Extending the template
- **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`.
- **New CRUD resource:** Follow `.agents/skills/add-resource/SKILL.md` (mirror `users`), then `pnpm run i18n:extract && pnpm run i18n:compile`, and `pnpm run check`.
- **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).