diff --git a/apps/docs/content/en/backend/proxying-api-requests.mdx b/apps/docs/content/en/backend/proxying-api-requests.mdx index 917dc03..8b964d1 100644 --- a/apps/docs/content/en/backend/proxying-api-requests.mdx +++ b/apps/docs/content/en/backend/proxying-api-requests.mdx @@ -11,10 +11,26 @@ Templates use **MSW** to intercept HTTP in development. Handlers live under `src The **worker directory** is configured via `package.json` **`msw.workerDirectory`** as `public`. +## API layer (templates) + +Data flow: **Zod schemas → `defineApi` in `src/api//index.ts` → routes/components call resource functions** (`listUsers`, `login`, …). Do not import axios or `@/api/request` from UI code. + +```text +src/api/ +├── request.ts # axios, envelope unwrap, token refresh +├── schemas.ts # deprecated barrel; prefer @/api/shared and module schemas +├── shared/ # API_PREFIX, pagination, params, menu helpers +├── auth/ # paths, schemas, login / hydrateSession +└── users/ # schemas, CRUD APIs, userQueryKeys, path constants +``` + +- REST path prefix: **`API_PREFIX`** in `src/api/shared/prefix.ts` (default `/api`). Auth and user paths (`AUTH_ENDPOINTS`, `USERS_PATH`) and **MSW handlers** import the same constants. +- New domains: mirror **`users`** — see each app **`.agents/skills/add-resource/SKILL.md`** and **`AGENTS.md`**. + ## Talking to a real API -Transport lives in **`src/api/request.ts` (axios)**. `baseURL` comes from **`VITE_API_BASE_URL`** (`src/utils/constants.ts`). Call APIs through `defineApi` functions in `src/api/*.ts` — do not call axios from pages. +Transport lives in **`src/api/request.ts` (axios)**. `baseURL` comes from **`VITE_API_BASE_URL`** (`src/utils/constants.ts`). Call **`defineApi` exports** from `src/api//index.ts` — not axios from pages. Point `VITE_API_BASE_URL` at your gateway and disable or bypass MSW per `main.tsx` / env flags when you no longer need mocks. -For CORS, configure the gateway the browser can reach, or proxy `/api` in `vite.config.ts` `server.proxy`. +For CORS, configure the gateway the browser can reach, or proxy **`API_PREFIX`** (default `/api`) in `vite.config.ts` `server.proxy`. diff --git a/apps/docs/content/en/getting-started/folder-structure.mdx b/apps/docs/content/en/getting-started/folder-structure.mdx index 29759da..48b6677 100644 --- a/apps/docs/content/en/getting-started/folder-structure.mdx +++ b/apps/docs/content/en/getting-started/folder-structure.mdx @@ -23,6 +23,28 @@ description: Key directories and responsibilities in the repository - `apps/docs`: Documentation site (Nextra + Next.js) - `packages`: Shared packages and utilities +## Template app `src/` (basic / with-lingui) + +Both templates share the same layout; **with-lingui** adds `src/locales/` and Lingui scripts. + +```text +src/ +├── api/ +│ ├── request.ts # Transport (axios, defineApi, token refresh) +│ ├── schemas.ts # Compatibility re-exports +│ ├── shared/ # API_PREFIX, pagination, params, menu helpers +│ ├── auth/ # Auth paths, schemas, login / hydrateSession +│ └── users/ # User CRUD, query keys, path constants +├── components/ +├── hooks/ +├── mocks/ # MSW handlers (same path constants as api modules) +├── routes/ +├── stores/ +└── utils/ # Constants, menu tree — not HTTP transport +``` + +See **[Proxying API Requests](/en/backend/proxying-api-requests)** for the API layer and MSW/backend wiring. + ## Recommendation When creating reusable logic, prioritize placing it in `packages` rather than duplicating in app folders. diff --git a/apps/docs/content/en/getting-started/supported-features.mdx b/apps/docs/content/en/getting-started/supported-features.mdx index 4932b6a..09d5d29 100644 --- a/apps/docs/content/en/getting-started/supported-features.mdx +++ b/apps/docs/content/en/getting-started/supported-features.mdx @@ -9,7 +9,7 @@ The templates include: - User login and permission-based routing - Dashboard and reusable business pages -- Request abstraction and API proxy support +- Modular API layer (`defineApi`, Zod schemas, shared `API_PREFIX`) and dev proxy / MSW - Theme and layout customization - Mock data support with MSW - Unit tests and E2E tests diff --git a/apps/docs/content/en/templates/basic.mdx b/apps/docs/content/en/templates/basic.mdx index c662ff4..8705608 100644 --- a/apps/docs/content/en/templates/basic.mdx +++ b/apps/docs/content/en/templates/basic.mdx @@ -15,9 +15,12 @@ description: Admin template with plain-string UI (default English) ## Highlights -- Clean route organization -- Common data table and form patterns -- Practical defaults for request handling and page layout +- Modular **`src/api/`** (`defineApi` per domain, shared **`API_PREFIX`**, Zod at boundaries) +- Clean route organization and reusable CRUD hooks +- MSW mocks aligned with the same path constants as the API modules +- **`AGENTS.md`** and **`.agents/skills/add-resource/`** for AI-assisted scaffolding + +Full tree and scripts: [apps/basic/README.md](https://github.com/zuiidea/antd-admin/blob/master/apps/basic/README.md). ## Start Development diff --git a/apps/docs/content/en/templates/with-lingui.mdx b/apps/docs/content/en/templates/with-lingui.mdx index 3520acd..8914d22 100644 --- a/apps/docs/content/en/templates/with-lingui.mdx +++ b/apps/docs/content/en/templates/with-lingui.mdx @@ -15,9 +15,11 @@ description: Admin template with Lingui internationalization ## Highlights -- Lingui message extraction and compilation flow -- Language resource organization -- Built-in language switching patterns +- Same **`src/api/`** layout as **basic** (shared transport, `API_PREFIX`, `auth/` / `users/` modules) +- Lingui message extraction and compilation flow (`i18n:extract`, `i18n:compile`, `i18n:check`) +- Built-in **en** / **zh** switching with Ant Design locale wiring + +Full tree and scripts: [apps/with-lingui/README.md](https://github.com/zuiidea/antd-admin/blob/master/apps/with-lingui/README.md). ## Start Development diff --git a/apps/docs/content/en/testing/running-tests.mdx b/apps/docs/content/en/testing/running-tests.mdx index 91ae2c3..027de7d 100644 --- a/apps/docs/content/en/testing/running-tests.mdx +++ b/apps/docs/content/en/testing/running-tests.mdx @@ -7,12 +7,19 @@ description: Run unit and e2e tests in this repository Run tests from repository root or per app. -Common commands: +From a template app directory (`apps/basic` or `apps/with-lingui`): + +```bash +pnpm run test:unit +pnpm run test:e2e +pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # focused core flows +pnpm run test:e2e:ui +``` + +Monorepo-wide (if configured): ```bash pnpm -r test -pnpm --filter ./apps/basic test -pnpm --filter ./apps/with-lingui test ``` -Set up CI to run tests on pull requests before merge. +Set up CI to run `vp check` and E2E on pull requests before merge. See each app **`AGENTS.md`** for toolchain rules. diff --git a/apps/docs/content/en/welcome/documentation-intro.mdx b/apps/docs/content/en/welcome/documentation-intro.mdx index 1b4ad7e..7450836 100644 --- a/apps/docs/content/en/welcome/documentation-intro.mdx +++ b/apps/docs/content/en/welcome/documentation-intro.mdx @@ -11,7 +11,7 @@ If this is your first time here: 1. Read **[Getting Started](/en/getting-started)** for setup and scripts. 2. Compare templates in **[Templates](/en/templates)**. -3. Go to **[Backend Integration](/en/backend/proxying-api-requests)** if you need API setup. +3. Go to **[Backend Integration](/en/backend/proxying-api-requests)** for MSW, the modular **`src/api/`** layer, and real backend wiring. ## Repo Structure diff --git a/apps/docs/content/zh/backend/proxying-api-requests.mdx b/apps/docs/content/zh/backend/proxying-api-requests.mdx index e4c375b..19d9081 100644 --- a/apps/docs/content/zh/backend/proxying-api-requests.mdx +++ b/apps/docs/content/zh/backend/proxying-api-requests.mdx @@ -11,10 +11,26 @@ description: MSW、API 基地址与对接真实后端 **Worker 目录**由 `package.json` 的 **`msw.workerDirectory`** 配置为 `public`，与 [public 目录](/styles-and-assets/public-folder) 说明一致。 +## API 层（模板约定） + +数据流：**Zod schema → `src/api//index.ts` 中的 `defineApi` → 路由/组件只调用资源函数**（如 `listUsers`、`login`）。页面不要 import axios 或 `@/api/request`。 + +```text +src/api/ +├── request.ts # axios、响应 envelope、token 刷新 +├── schemas.ts # 兼容 re-export；新代码用 @/api/shared 与各 module schemas +├── shared/ # API_PREFIX、分页/查询/菜单等共用 schema +├── auth/ # paths、schemas、登录与 hydrateSession +└── users/ # schemas、CRUD、userQueryKeys、路径常量 +``` + +- REST 前缀：**`API_PREFIX`**（`src/api/shared/prefix.ts`，默认 `/api`）。`AUTH_ENDPOINTS`、`USERS_PATH` 与 **MSW handlers** 共用同一套常量。 +- 新增资源：对照 **`users`**，见各应用 **`.agents/skills/add-resource/SKILL.md`** 与 **`AGENTS.md`**。 + ## 对接真实 API -模板传输层为 **`src/api/request.ts`（axios）**：`baseURL` 来自环境变量 **`VITE_API_BASE_URL`**（见 `src/utils/constants.ts`）。业务调用请走 `src/api/*.ts` 中的 `defineApi` 函数，不要在页面里直连 axios。 +模板传输层为 **`src/api/request.ts`（axios）**：`baseURL` 来自环境变量 **`VITE_API_BASE_URL`**（见 `src/utils/constants.ts`）。业务调用请走 **`src/api//index.ts`** 导出的 `defineApi` 函数，不要在页面里直连 axios。 将 `VITE_API_BASE_URL` 指向真实网关，并按环境关闭或绕过 MSW 初始化（具体开关以模板 `main.tsx` / 环境变量为准）。 -跨域时需由**浏览器可访问**的网关配置 **CORS**；或通过开发代理将 `/api` 转发到后端（在 `vite.config.ts` 配置 `server.proxy`，按团队规范填写目标地址）。 +跨域时需由**浏览器可访问**的网关配置 **CORS**；或通过开发代理将 **`API_PREFIX`（默认 `/api`）** 转发到后端（在 `vite.config.ts` 配置 `server.proxy`，按团队规范填写目标地址）。 diff --git a/apps/docs/content/zh/getting-started/available-scripts.mdx b/apps/docs/content/zh/getting-started/available-scripts.mdx index fc4819d..b95d16c 100644 --- a/apps/docs/content/zh/getting-started/available-scripts.mdx +++ b/apps/docs/content/zh/getting-started/available-scripts.mdx @@ -29,7 +29,7 @@ description: package.json 中与开发相关的 npm 脚本 |------|------| | `pnpm run test:unit` | Vitest 单元测试 | | `pnpm run test:e2e` | Playwright 全部 E2E | -| `pnpm run test:e2e:core` | 核心场景子集（登录、users CRUD、refresh、RBAC、URL 状态） | +| `pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts` | 核心流程（登录 + users CRUD） | | `pnpm run test:e2e:ui` | Playwright UI 模式 | ## With Lingui 专有 diff --git a/apps/docs/content/zh/getting-started/folder-structure.mdx b/apps/docs/content/zh/getting-started/folder-structure.mdx index a331ede..d44681f 100644 --- a/apps/docs/content/zh/getting-started/folder-structure.mdx +++ b/apps/docs/content/zh/getting-started/folder-structure.mdx @@ -9,16 +9,23 @@ description: 模板应用 src 目录职责说明 ``` src/ -├── api/ # Zod schema、request（axios + defineApi）、资源 API +├── api/ +│ ├── request.ts # 传输层（axios、defineApi、刷新 token） +│ ├── schemas.ts # 兼容 barrel +│ ├── shared/ # API_PREFIX、分页/params/menu 等 +│ ├── auth/ # 认证 API 与 paths +│ └── users/ # 用户 CRUD 与 query keys ├── components/ # 通用 UI（表格壳、表单弹窗、布局等） ├── hooks/ # 主题、权限、CRUD 等组合逻辑 ├── locales/ # Lingui：仅 with-lingui（en/zh .po） -├── mocks/ # MSW handlers 与浏览器 worker +├── mocks/ # MSW handlers（路径与 api 模块常量一致） ├── routes/ # TanStack Router 文件路由 ├── stores/ # Zustand（auth、settings 等持久化） -└── utils/ # 常量、菜单等（传输层在 api/request.ts） +└── utils/ # 常量、菜单等（不含 HTTP 客户端） ``` +API 约定详见 [开发代理与 Mock](/backend/proxying-api-requests)。 + 更完整的树状说明见： - [apps/basic/README.md](https://github.com/zuiidea/antd-admin/blob/master/apps/basic/README.md) diff --git a/apps/docs/content/zh/getting-started/supported-features.mdx b/apps/docs/content/zh/getting-started/supported-features.mdx index 1ad5e75..b4356b5 100644 --- a/apps/docs/content/zh/getting-started/supported-features.mdx +++ b/apps/docs/content/zh/getting-started/supported-features.mdx @@ -13,7 +13,8 @@ description: 两模板共同具备的产品与技术能力 - **动态菜单与 RBAC**：服务端菜单、路由权限、403 - **表格 URL 状态**：分页、关键字、排序等与查询参数同步 - **MSW**：开发环境 Mock，无需真实后端即可跑通流程 -- **Playwright E2E**：覆盖登录、CRUD、鉴权刷新、RBAC、URL 状态等（`test:e2e:core` 为核心子集） +- **模块化 API**：`defineApi` 分域、`API_PREFIX`、MSW 与真实后端共用路径常量 +- **Playwright E2E**：覆盖登录、CRUD、鉴权刷新、RBAC、URL 状态等（可用 `pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts` 跑核心流程） **With Lingui** 额外包含：LinguiJS 中英文、Ant Design locale 随语言切换、`.po` 抽取/编译工作流。 diff --git a/apps/docs/content/zh/getting-started/updating-releases.mdx b/apps/docs/content/zh/getting-started/updating-releases.mdx index b82d72f..cb4543a 100644 --- a/apps/docs/content/zh/getting-started/updating-releases.mdx +++ b/apps/docs/content/zh/getting-started/updating-releases.mdx @@ -8,7 +8,7 @@ description: 依赖与模板演进时的建议 ## 依赖升级 - 使用 **Vite+**（`vp`）管理依赖，避免绕过 `vp` 直接大面积 `pnpm up` 导致与模板锁定的工具链不一致。 -- 升级 **Ant Design / TanStack / React** 大版本前，建议先阅读官方迁移说明，并在单分支上跑通 `vp check`、`test:unit`、`test:e2e:core` 与 `vp build`。 +- 升级 **Ant Design / TanStack / React** 大版本前，建议先阅读官方迁移说明，并在单分支上跑通 `vp check`、`test:unit`、`pnpm run test:e2e`（或指定核心 spec）与 `vp build`。 ## 跟随本仓库模板 diff --git a/apps/docs/content/zh/templates/basic.mdx b/apps/docs/content/zh/templates/basic.mdx index 5d779f8..ca83769 100644 --- a/apps/docs/content/zh/templates/basic.mdx +++ b/apps/docs/content/zh/templates/basic.mdx @@ -13,7 +13,9 @@ description: apps/basic — 默认英文界面的管理后台模板 ## 技术栈摘要 -构建：[Vite+](https://viteplus.dev)；UI：Ant Design 6；路由：TanStack Router；数据：TanStack Query；本地状态：Zustand；校验：Zod；Mock：MSW；E2E：Playwright。 +构建：[Vite+](https://viteplus.dev)；UI：Ant Design 6；路由：TanStack Router；数据：TanStack Query；本地状态：Zustand；校验：Zod；API：`defineApi` 分模块（`src/api/shared/`、`auth/`、`users/`）；Mock：MSW；E2E：Playwright。 + +API 与 Mock 约定见 [开发代理与 Mock](/backend/proxying-api-requests)。 ## 常用命令 diff --git a/apps/docs/content/zh/templates/with-lingui.mdx b/apps/docs/content/zh/templates/with-lingui.mdx index 3820792..c4d8641 100644 --- a/apps/docs/content/zh/templates/with-lingui.mdx +++ b/apps/docs/content/zh/templates/with-lingui.mdx @@ -13,7 +13,7 @@ description: apps/with-lingui — 中英双语与 Lingui 工作流 ## 技术栈补充 -在 Basic 技术栈基础上增加 Lingui 6；`src/locales/{en,zh}/messages.po` 为翻译源；`lingui.config.ts` 与 Vite 插件见应用内配置。 +在 Basic 技术栈基础上增加 Lingui 6；**`src/api/` 目录与 Basic 同构**（`shared/`、`auth/`、`users/`）。`src/locales/{en,zh}/messages.po` 为翻译源；`lingui.config.ts` 与 Vite 插件见应用内配置。 ## 国际化命令 diff --git a/apps/docs/content/zh/testing/running-tests.mdx b/apps/docs/content/zh/testing/running-tests.mdx index ef87278..d4644c9 100644 --- a/apps/docs/content/zh/testing/running-tests.mdx +++ b/apps/docs/content/zh/testing/running-tests.mdx @@ -17,7 +17,8 @@ pnpm run test:unit ```bash pnpm run test:e2e # 全部 -pnpm run test:e2e:core # 核心子集（登录、users、refresh、RBAC、URL 状态） +pnpm run test:e2e -- e2e/login.spec.ts e2e/users.spec.ts # 核心流程 +pnpm run test:e2e -- e2e/auth-refresh.spec.ts e2e/rbac.spec.ts e2e/url-state.spec.ts ``` 首次在机器上跑 E2E 前，按 Playwright 文档安装浏览器依赖（`pnpm exec playwright install` 等，以官方说明为准）。 diff --git a/apps/docs/content/zh/welcome/documentation-intro.mdx b/apps/docs/content/zh/welcome/documentation-intro.mdx index c926d97..d8031b4 100644 --- a/apps/docs/content/zh/welcome/documentation-intro.mdx +++ b/apps/docs/content/zh/welcome/documentation-intro.mdx @@ -19,7 +19,7 @@ description: 本文档的阅读方式与章节说明 | **样式与资源** | 全局样式、CSS Modules、静态资源、public、代码分割 | | **构建应用** | 路由、环境变量、性能、生产构建 | | **测试** | 单元测试与 E2E | -| **后端对接** | MSW Mock、API 基地址与代理思路 | +| **后端对接** | MSW、`src/api/` 模块化与 `API_PREFIX`、真实 API 与代理 | | **部署** | 构建产物与部署注意点 | 更完整的模板说明仍以仓库内 **`apps/*/README.md`** 为准；本站用中文串联常用路径，减少在 GitHub 间跳转的成本。