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>
2026-10-19 16:14:37 +00:00 · 2026-10-18 21:17:47 +08:00
parent bb141469e1
commit b8bb7713b3
16 changed files with 103 additions and 26 deletions
@@ -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/<module>/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/<module>/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`.
@@ -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.
@@ -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
@@ -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

@@ -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

@@ -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.
@@ -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

@@ -11,10 +11,26 @@ description: MSW、API 基地址与对接真实后端

 **Worker 目录**由 `package.json` 的 **`msw.workerDirectory`** 配置为 `public`，与 [public 目录](/styles-and-assets/public-folder) 说明一致。

+## API 层（模板约定）
+
+数据流：**Zod schema → `src/api/<module>/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/<module>/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`，按团队规范填写目标地址）。
@@ -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 专有
@@ -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)
@@ -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` 抽取/编译工作流。

@@ -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`。

 ## 跟随本仓库模板

@@ -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)。

 ## 常用命令

@@ -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 插件见应用内配置。

 ## 国际化命令

@@ -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` 等，以官方说明为准）。
@@ -19,7 +19,7 @@ description: 本文档的阅读方式与章节说明
 | **样式与资源** | 全局样式、CSS Modules、静态资源、public、代码分割 |
 | **构建应用** | 路由、环境变量、性能、生产构建 |
 | **测试** | 单元测试与 E2E |
-| **后端对接** | MSW Mock、API 基地址与代理思路 |
+| **后端对接** | MSW、`src/api/` 模块化与 `API_PREFIX`、真实 API 与代理 |
 | **部署** | 构建产物与部署注意点 |

 更完整的模板说明仍以仓库内 **`apps/*/README.md`** 为准；本站用中文串联常用路径，减少在 GitHub 间跳转的成本。