@farris/cli 2.3.12 → 2.3.14

package/templates/create/AGENTS.md

@@ -56,6 +56,7 @@
 - 联调真实后端：在**工程目录内**执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
 - 请求路径必须与 mock 的 `url` 逐字一致；禁止在组件里散落假数据。
 - mock 不得进入构建产物：`msw` 已在应用 `devDependencies`（开发期依赖），不要在 `mock/` 之外引用它，也不要把它加到 `dependencies`。
+- mock 目录里的用例放 `mock/__tests__/`：`*.spec.*` / `*.test.*` / `*.d.ts` / `_` 前缀的文件与目录都不会被当作 handler 加载。mock 目录在工程 `tsconfig.json` 的 `include` 内，`pnpm typecheck` 会一并检查。
 
 ### 2.6 工程内生成器
 
@@ -97,8 +98,22 @@
 
 - 文件名 = 被测文件名 + `.spec`：纯逻辑用 `*.spec.ts`，组件或含 JSX 用 `*.spec.tsx`。
 - `__tests__/` 与被测文件同级；**不要**在工程根另建 `test/` 汇总目录。
+- mock 数据的用例同样就近，放 `mock/__tests__/<模块>.spec.ts`：加载器按语义跳过它，不需要靠 `_` 前缀躲开。
 - 工程里**不预置**端到端测试：需要时自行引入，别与上面的单元测试混放。
 
+**测试环境**：jsdom 没有实现全部浏览器 API（如 `ResizeObserver`）。缺口统一在工程根 `vitest.setup.ts` 里补齐，
+由 `vitest.config.ts` 的 `setupFiles` 引入；用例里不要再各写一份，需要新 API 就往那个文件加。
+
+**测用到 Farris 组件的视图**：组件在 `src/main.ts` 里是全局注册的，测试挂载时要自己带上插件，否则模板里的 `<f-xxx>` 渲染不出来：
+
+```tsx
+import FarrisVue from '@farris/ui-vue';
+import { mount } from '@vue/test-utils';
+import ProjectView from '../ProjectView';
+
+const wrapper = mount(ProjectView, { global: { plugins: [FarrisVue] } });
+```
+
 ### 4.2 每次改动必须做
 
 1. 改完代码先在**工程目录内**跑 `pnpm test`；提交前在根目录跑一次 `pnpm test`（递归全部工程）。
@@ -108,7 +123,7 @@
 
 ### 4.3 禁止
 
-- 禁止为让测试通过而改 `vitest.config.ts` 的 `include` / `exclude` / `environment`，或删改既有用例。
+- 禁止为让测试通过而改 `vitest.config.ts` 的 `include` / `exclude` / `environment`，或删改既有用例。缺的 jsdom API 加到 `vitest.setup.ts`，不要在每个用例里自己打补丁。
 - 禁止把端到端用例放进 `__tests__/`；禁止提交 `.only` / `.skip`。
 - 禁止在用例里靠固定 `sleep` 等待，或依赖上一条用例残留的状态。
 

package/templates/create/README.md

@@ -13,6 +13,8 @@ pnpm test             # 跑全部工程的单元测试
 pnpm verify           # 校验 workspace 规范（改结构 / 脚本 / 容器后必跑）
 ```
 
+**装依赖之前先看一眼 `.npmrc`**：它按组织内网源写好了 `registry=`。不在该网络内（外网、客户现场、其他团队）请先改掉再 `pnpm install`，否则会直接报错；两种改法任选：编辑根目录 `.npmrc` 里的这一行，或执行 `pnpm config set registry <你的源>`。
+
 开发某个工程时，进入它的目录：
 
 ```bash
@@ -20,6 +22,8 @@ cd <%= appContainer %>/shop    # 以应用为例：工程内的命令都在这
 pnpm dev          # 启动开发服务器（根目录没有 dev，是有意为之）
 ```
 
+首页默认会请求 `/api/v1/users`，数据来自工程内 `mock/user.mock.ts`（假接口，写法见 `mock/README.md`）：打开页面就能看到列表，`pnpm dev --no-mock` 则会转去请求真实后端。
+
 ## 目录结构
 
 ```text

package/templates/lib/package.json

@@ -50,6 +50,7 @@
     "@vue/eslint-config-typescript": "^13.0.0",
     "@vue/test-utils": "^2.4.6",
     "@vue/tsconfig": "^0.5.1",
+    "esbuild-sass-plugin": "^3.3.1",
     "eslint": "^8.57.0",
     "eslint-plugin-vue": "^9.23.0",
     "jsdom": "^25.0.1",

package/templates/lib/tsconfig.json

@@ -2,9 +2,11 @@
   "extends": "@vue/tsconfig/tsconfig.dom.json",
   "include": [
     "components/**/*",
-    "src/**/*"
+    "src/**/*",
+    "vitest.setup.ts"
   ],
   "compilerOptions": {
-    "strict": true
+    "strict": true,
+    "types": ["vite/client"]
   }
 }

package/templates/lib/vitest.config.ts

@@ -1,10 +1,13 @@
 import vue from '@vitejs/plugin-vue';
+import vueJsx from '@vitejs/plugin-vue-jsx';
 import { configDefaults, defineConfig } from 'vitest/config';
 
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), vueJsx()],
   test: {
     environment: 'jsdom',
+    // jsdom 缺失的浏览器 API（如 ResizeObserver）统一在这里补齐，用例里不要再各写一份
+    setupFiles: ['./vitest.setup.ts'],
     // 官方默认收集范围（**/*.{test,spec}.*），源码旁的测试才会被收集
     include: [...configDefaults.include],
     exclude: [...configDefaults.exclude, '**/__sandbox_*/**']

package/templates/lib/vitest.setup.ts

@@ -0,0 +1,29 @@
+/**
+ * 测试运行前的环境兜底（由 `vitest.config.ts` 的 `setupFiles` 引入）。
+ *
+ * jsdom 没有实现全部浏览器 API，而组件在挂载时会直接读它们：例如依赖尺寸观测的组件，
+ * 缺 `ResizeObserver` 就报错。统一在这里补齐，不要在用例里各写一份。
+ * 需要更多 API（`IntersectionObserver`、`matchMedia` 等）时同样是往这里加。
+ */
+class ResizeObserverStub implements ResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+
+  /**
+   * 同步回调一次。只写空方法的话，靠回调算尺寸的组件在用例里永远不会被触发，
+   * 测试就变成"挂上去就完事"的假绿。
+   */
+  observe(target: Element): void {
+    const entry = [
+      { target, contentRect: (target as HTMLElement).getBoundingClientRect() }
+    ] as unknown as ResizeObserverEntry[];
+    this.callback(entry, this);
+  }
+
+  unobserve(): void {}
+
+  disconnect(): void {}
+}
+
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = ResizeObserverStub;
+}

package/templates/micro/mock/README.md

@@ -26,6 +26,11 @@ export const handlers = [
 3. 在工程目录执行 `pnpm dev`，打开用到该接口的页面，**验证**返回的是 mock 数据。
 4. 需要联调真实后端时执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
 
+## 给 mock 数据写测试
+
+mock 目录里若有纯数据操作（种子数据、查询、增删改），值得单测：落点与工程其他用例一致，放 `mock/__tests__/<模块>.spec.ts`。
+用例会被 `pnpm test` 收集、被 `pnpm typecheck` 检查，也**不会**被当成 handler 加载（见下面规则），不需要靠 `_` 前缀躲开加载器。
+
 规则：
 
 - url 必须与代码实际发出的请求路径逐字一致，前缀也要带上；请求路径见 `src/api/` 下的接口模块。
@@ -34,7 +39,7 @@ export const handlers = [
 - 同一前缀下同时有字面量路径与 `:参数名` 路径时，字面量写在前面。MSW 取第一个匹配的 handler，`/api/v1/users/current` 排在 `/api/v1/users/:id` 后面会被 `:id` 接走。
 - 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。数据要有业务语义，用中文姓名、机构、单据号这类内容，不要用占位文本。
 - 关键场景要模拟：空态、错误、慢响应。错误用 `HttpResponse.json(..., { status: 500 })`；慢响应用 `delay`。
-- 目录里只放 handler 文件。共享数据或工具函数要放进 `_` 开头的文件，例如 `_data.ts`，加载时会跳过；其他文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
+- 目录里只放 handler 文件。共享数据或工具函数放 `_` 开头的文件（如 `_data.ts`），用例放 `mock/__tests__/`。`_` 前缀的文件与目录、`__tests__/` 目录、`*.spec.*` / `*.test.*` / `*.d.ts` 都不会被加载；其余文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
 - 同一路径不允许在多个 mock 文件中重复定义，重复时开发服务启动或请求即报错。
 - 文件只导出 handler 数组，写 `export const handlers = [...]` 或 `export default [...]`。不需要 `setupServer` / `setupWorker` 接线；接线由脚手架完成。
 - `msw` 已由模板放进应用 `devDependencies`，版本随工作区 catalog 统一。不要把它加到 `dependencies`，也不要在 `mock/` 之外引用它，否则构建期会报错。
@@ -48,6 +53,6 @@ export const handlers = [
 
 开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。
 
-类型：本目录附带独立的 `tsconfig.json`，只服务于编辑器与按需类型检查。应用自身的 `typecheck` 不包含本目录，mock 也不参与构建。
+类型：本目录在工程 `tsconfig.json` 的 `include` 内，`pnpm typecheck` 会一并检查（含 `mock/__tests__/` 下的用例）。mock 不参与构建。
 
 约定版本 2026-09。本文件随 `@farris/cli` 模板发布，AI 协作以本文件为准。

package/templates/micro/mock/user.mock.ts

@@ -0,0 +1,24 @@
+import { http, HttpResponse, delay } from 'msw';
+
+/**
+ * 用户接口的假数据（开发期）。
+ *
+ * - 路径必须与 src/api/user.api.ts 里实际发出的请求**逐字一致**（前缀也要带上）；
+ * - 只写路径，不要写协议与主机；
+ * - 存成 mock/*.mock.ts 保存即生效，不需要重启 pnpm dev；
+ * - 联调真实后端：pnpm dev --no-mock（或 MOCK=none pnpm dev），业务代码不用改。
+ *
+ * 完整规则见同目录 README.md，约定版本 2026-09。
+ */
+export const handlers = [
+  http.get('/api/v1/users', async () => {
+    await delay(200);
+    return HttpResponse.json({
+      data: [
+        { id: 'u-1', name: '张三', dept: '财务部' },
+        { id: 'u-2', name: '李四', dept: '供应链部' }
+      ],
+      total: 2
+    });
+  })
+];

package/templates/micro/package.json

@@ -19,7 +19,7 @@
     "i18n": "farris-cli extract-i18n"
   },
   "dependencies": {
-    "@farris/ui-vue": "latest",
+    "@farris/ui-vue": "<%= uiVueVersion %>",
     "vue": "^3.4.29",
     "vue-router": "^4.3.0"
   },

package/templates/micro/src/api/http-client.ts

@@ -0,0 +1,38 @@
+/**
+ * Farris 标准 HTTP 请求客户端封装
+ */
+export interface RequestOptions extends RequestInit {
+  params?: Record<string, any>;
+}
+
+export async function request<T = any>(url: string, options: RequestOptions = {}): Promise<T> {
+  const { params, ...customConfig } = options;
+
+  let requestUrl = url;
+  if (params && Object.keys(params).length > 0) {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, val]) => {
+      if (val !== undefined && val !== null) {
+        searchParams.append(key, String(val));
+      }
+    });
+    requestUrl += (url.includes('?') ? '&' : '?') + searchParams.toString();
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(customConfig.headers || {})
+  };
+
+  const response = await fetch(requestUrl, {
+    ...customConfig,
+    headers
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => response.statusText);
+    throw new Error(`HTTP Error ${response.status}: ${errorText}`);
+  }
+
+  return response.json();
+}

package/templates/micro/src/api/index.ts

@@ -0,0 +1 @@
+export * from './user.api';

package/templates/micro/src/api/user.api.ts

@@ -0,0 +1,21 @@
+import { request } from './http-client';
+
+export interface UserItem {
+  id: string;
+  name: string;
+  dept: string;
+}
+
+export interface UserListResponse {
+  data: UserItem[];
+  total?: number;
+}
+
+/**
+ * 用户列表。
+ *
+ * 开发期由工程内 mock/user.mock.ts 提供假数据；联调真实后端执行 pnpm dev --no-mock。
+ */
+export async function getUserList(): Promise<UserListResponse> {
+  return request<UserListResponse>('/api/v1/users');
+}

package/templates/micro/src/views/HomeView.tsx

@@ -1,11 +1,43 @@
-import { defineComponent } from 'vue';
+import { defineComponent, onMounted, ref } from 'vue';
+import { getUserList, type UserItem } from '../api/user.api';
 
 export default defineComponent({
   name: 'HomeView',
   setup() {
+    const users = ref<UserItem[]>([]);
+    const loading = ref(false);
+    const error = ref('');
+
+    async function loadUsers(): Promise<void> {
+      loading.value = true;
+      error.value = '';
+      try {
+        users.value = (await getUserList()).data;
+      } catch (err) {
+        // 后端不可用时不阻塞页面：把失败原因显示出来即可
+        error.value = err instanceof Error ? err.message : '请求失败';
+      } finally {
+        loading.value = false;
+      }
+    }
+
+    onMounted(loadUsers);
+
     return () => (
       <main>
         <h1>Home</h1>
+        <p>下面的数据来自工程内 mock/ 目录的假接口；联调真实后端执行 pnpm dev --no-mock。</p>
+        {loading.value ? <p>加载中…</p> : null}
+        {!loading.value && error.value ? <p>加载失败：{error.value}</p> : null}
+        {!loading.value && !error.value ? (
+          <ul>
+            {users.value.map((user) => (
+              <li key={user.id}>
+                {user.name}（{user.dept}）
+              </li>
+            ))}
+          </ul>
+        ) : null}
         <p>在 src/views/ 下新增页面；通用组件按需创建在 src/components/ 下。</p>
       </main>
     );

package/templates/micro/src/views/__tests__/HomeView.spec.tsx

@@ -4,8 +4,10 @@ import HomeView from '../HomeView';
 
 describe('HomeView', () => {
   it('mounts', () => {
+    // 页面挂载时会请求接口（开发期由 mock/ 提供数据），这里只断言首屏能渲染
     const wrapper = mount(HomeView);
 
     expect(wrapper.exists()).toBe(true);
+    expect(wrapper.text()).toContain('Home');
   });
 });

package/templates/micro/tsconfig.json

@@ -3,7 +3,9 @@
   "include": [
     "env.d.ts",
     "src/**/*",
-    "src/**/*.vue"
+    "src/**/*.vue",
+    "mock/**/*",
+    "vitest.setup.ts"
   ],
   "compilerOptions": {
     "composite": true,

package/templates/micro/vitest.config.ts

@@ -1,10 +1,13 @@
 import vue from '@vitejs/plugin-vue';
+import vueJsx from '@vitejs/plugin-vue-jsx';
 import { configDefaults, defineConfig } from 'vitest/config';
 
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), vueJsx()],
   test: {
     environment: 'jsdom',
+    // jsdom 缺失的浏览器 API（如 ResizeObserver）统一在这里补齐，用例里不要再各写一份
+    setupFiles: ['./vitest.setup.ts'],
     // 官方默认收集范围（**/*.{test,spec}.*），源码旁的测试才会被收集
     include: [...configDefaults.include],
     exclude: [...configDefaults.exclude, '**/__sandbox_*/**']

package/templates/micro/vitest.setup.ts

@@ -0,0 +1,29 @@
+/**
+ * 测试运行前的环境兜底（由 `vitest.config.ts` 的 `setupFiles` 引入）。
+ *
+ * jsdom 没有实现全部浏览器 API，而组件在挂载时会直接读它们：例如依赖尺寸观测的组件，
+ * 缺 `ResizeObserver` 就报错。统一在这里补齐，不要在用例里各写一份。
+ * 需要更多 API（`IntersectionObserver`、`matchMedia` 等）时同样是往这里加。
+ */
+class ResizeObserverStub implements ResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+
+  /**
+   * 同步回调一次。只写空方法的话，靠回调算尺寸的组件在用例里永远不会被触发，
+   * 测试就变成"挂上去就完事"的假绿。
+   */
+  observe(target: Element): void {
+    const entry = [
+      { target, contentRect: (target as HTMLElement).getBoundingClientRect() }
+    ] as unknown as ResizeObserverEntry[];
+    this.callback(entry, this);
+  }
+
+  unobserve(): void {}
+
+  disconnect(): void {}
+}
+
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = ResizeObserverStub;
+}

package/templates/mobile/mock/README.md

@@ -26,6 +26,11 @@ export const handlers = [
 3. 在工程目录执行 `pnpm dev`，打开用到该接口的页面，**验证**返回的是 mock 数据。
 4. 需要联调真实后端时执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
 
+## 给 mock 数据写测试
+
+mock 目录里若有纯数据操作（种子数据、查询、增删改），值得单测：落点与工程其他用例一致，放 `mock/__tests__/<模块>.spec.ts`。
+用例会被 `pnpm test` 收集、被 `pnpm typecheck` 检查，也**不会**被当成 handler 加载（见下面规则），不需要靠 `_` 前缀躲开加载器。
+
 规则：
 
 - url 必须与代码实际发出的请求路径逐字一致，前缀也要带上；请求路径见 `src/api/` 下的接口模块。
@@ -34,7 +39,7 @@ export const handlers = [
 - 同一前缀下同时有字面量路径与 `:参数名` 路径时，字面量写在前面。MSW 取第一个匹配的 handler，`/api/v1/users/current` 排在 `/api/v1/users/:id` 后面会被 `:id` 接走。
 - 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。数据要有业务语义，用中文姓名、机构、单据号这类内容，不要用占位文本。
 - 关键场景要模拟：空态、错误、慢响应。错误用 `HttpResponse.json(..., { status: 500 })`；慢响应用 `delay`。
-- 目录里只放 handler 文件。共享数据或工具函数要放进 `_` 开头的文件，例如 `_data.ts`，加载时会跳过；其他文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
+- 目录里只放 handler 文件。共享数据或工具函数放 `_` 开头的文件（如 `_data.ts`），用例放 `mock/__tests__/`。`_` 前缀的文件与目录、`__tests__/` 目录、`*.spec.*` / `*.test.*` / `*.d.ts` 都不会被加载；其余文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
 - 同一路径不允许在多个 mock 文件中重复定义，重复时开发服务启动或请求即报错。
 - 文件只导出 handler 数组，写 `export const handlers = [...]` 或 `export default [...]`。不需要 `setupServer` / `setupWorker` 接线；接线由脚手架完成。
 - `msw` 已由模板放进应用 `devDependencies`，版本随工作区 catalog 统一。不要把它加到 `dependencies`，也不要在 `mock/` 之外引用它，否则构建期会报错。
@@ -48,6 +53,6 @@ export const handlers = [
 
 开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。
 
-类型：本目录附带独立的 `tsconfig.json`，只服务于编辑器与按需类型检查。应用自身的 `typecheck` 不包含本目录，mock 也不参与构建。
+类型：本目录在工程 `tsconfig.json` 的 `include` 内，`pnpm typecheck` 会一并检查（含 `mock/__tests__/` 下的用例）。mock 不参与构建。
 
 约定版本 2026-09。本文件随 `@farris/cli` 模板发布，AI 协作以本文件为准。

package/templates/mobile/tsconfig.json

@@ -3,7 +3,9 @@
   "include": [
     "env.d.ts",
     "src/**/*",
-    "src/**/*.vue"
+    "src/**/*.vue",
+    "mock/**/*",
+    "vitest.setup.ts"
   ],
   "compilerOptions": {
     "composite": true,

package/templates/mobile/vitest.config.ts

@@ -1,10 +1,13 @@
 import vue from '@vitejs/plugin-vue';
+import vueJsx from '@vitejs/plugin-vue-jsx';
 import { configDefaults, defineConfig } from 'vitest/config';
 
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), vueJsx()],
   test: {
     environment: 'jsdom',
+    // jsdom 缺失的浏览器 API（如 ResizeObserver）统一在这里补齐，用例里不要再各写一份
+    setupFiles: ['./vitest.setup.ts'],
     // 官方默认收集范围（**/*.{test,spec}.*），源码旁的测试才会被收集
     include: [...configDefaults.include],
     exclude: [...configDefaults.exclude, '**/__sandbox_*/**']

package/templates/mobile/vitest.setup.ts

@@ -0,0 +1,29 @@
+/**
+ * 测试运行前的环境兜底（由 `vitest.config.ts` 的 `setupFiles` 引入）。
+ *
+ * jsdom 没有实现全部浏览器 API，而组件在挂载时会直接读它们：例如依赖尺寸观测的组件，
+ * 缺 `ResizeObserver` 就报错。统一在这里补齐，不要在用例里各写一份。
+ * 需要更多 API（`IntersectionObserver`、`matchMedia` 等）时同样是往这里加。
+ */
+class ResizeObserverStub implements ResizeObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+
+  /**
+   * 同步回调一次。只写空方法的话，靠回调算尺寸的组件在用例里永远不会被触发，
+   * 测试就变成"挂上去就完事"的假绿。
+   */
+  observe(target: Element): void {
+    const entry = [
+      { target, contentRect: (target as HTMLElement).getBoundingClientRect() }
+    ] as unknown as ResizeObserverEntry[];
+    this.callback(entry, this);
+  }
+
+  unobserve(): void {}
+
+  disconnect(): void {}
+}
+
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = ResizeObserverStub;
+}

package/templates/web/mock/README.md

@@ -26,6 +26,11 @@ export const handlers = [
 3. 在工程目录执行 `pnpm dev`，打开用到该接口的页面，**验证**返回的是 mock 数据。
 4. 需要联调真实后端时执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
 
+## 给 mock 数据写测试
+
+mock 目录里若有纯数据操作（种子数据、查询、增删改），值得单测：落点与工程其他用例一致，放 `mock/__tests__/<模块>.spec.ts`。
+用例会被 `pnpm test` 收集、被 `pnpm typecheck` 检查，也**不会**被当成 handler 加载（见下面规则），不需要靠 `_` 前缀躲开加载器。
+
 规则：
 
 - url 必须与代码实际发出的请求路径逐字一致，前缀也要带上；请求路径见 `src/api/` 下的接口模块。
@@ -34,7 +39,7 @@ export const handlers = [
 - 同一前缀下同时有字面量路径与 `:参数名` 路径时，字面量写在前面。MSW 取第一个匹配的 handler，`/api/v1/users/current` 排在 `/api/v1/users/:id` 后面会被 `:id` 接走。
 - 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。数据要有业务语义，用中文姓名、机构、单据号这类内容，不要用占位文本。
 - 关键场景要模拟：空态、错误、慢响应。错误用 `HttpResponse.json(..., { status: 500 })`；慢响应用 `delay`。
-- 目录里只放 handler 文件。共享数据或工具函数要放进 `_` 开头的文件，例如 `_data.ts`，加载时会跳过；其他文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
+- 目录里只放 handler 文件。共享数据或工具函数放 `_` 开头的文件（如 `_data.ts`），用例放 `mock/__tests__/`。`_` 前缀的文件与目录、`__tests__/` 目录、`*.spec.*` / `*.test.*` / `*.d.ts` 都不会被加载；其余文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
 - 同一路径不允许在多个 mock 文件中重复定义，重复时开发服务启动或请求即报错。
 - 文件只导出 handler 数组，写 `export const handlers = [...]` 或 `export default [...]`。不需要 `setupServer` / `setupWorker` 接线；接线由脚手架完成。
 - `msw` 已由模板放进应用 `devDependencies`，版本随工作区 catalog 统一。不要把它加到 `dependencies`，也不要在 `mock/` 之外引用它，否则构建期会报错。
@@ -48,6 +53,6 @@ export const handlers = [
 
 开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。
 
-类型：本目录附带独立的 `tsconfig.json`，只服务于编辑器与按需类型检查。应用自身的 `typecheck` 不包含本目录，mock 也不参与构建。
+类型：本目录在工程 `tsconfig.json` 的 `include` 内，`pnpm typecheck` 会一并检查（含 `mock/__tests__/` 下的用例）。mock 不参与构建。
 
 约定版本 2026-09。本文件随 `@farris/cli` 模板发布，AI 协作以本文件为准。

package/templates/web/mock/user.mock.ts

@@ -0,0 +1,24 @@
+import { http, HttpResponse, delay } from 'msw';
+
+/**
+ * 用户接口的假数据（开发期）。
+ *
+ * - 路径必须与 src/api/user.api.ts 里实际发出的请求**逐字一致**（前缀也要带上）；
+ * - 只写路径，不要写协议与主机；
+ * - 存成 mock/*.mock.ts 保存即生效，不需要重启 pnpm dev；
+ * - 联调真实后端：pnpm dev --no-mock（或 MOCK=none pnpm dev），业务代码不用改。
+ *
+ * 完整规则见同目录 README.md，约定版本 2026-09。
+ */
+export const handlers = [
+  http.get('/api/v1/users', async () => {
+    await delay(200);
+    return HttpResponse.json({
+      data: [
+        { id: 'u-1', name: '张三', dept: '财务部' },
+        { id: 'u-2', name: '李四', dept: '供应链部' }
+      ],
+      total: 2
+    });
+  })
+];

package/templates/web/package.json

@@ -18,7 +18,7 @@
     "i18n": "farris-cli extract-i18n"
   },
   "dependencies": {
-    "@farris/ui-vue": "latest",
+    "@farris/ui-vue": "<%= uiVueVersion %>",
     "vue": "^3.4.29",
     "vue-router": "^4.3.0"
   },

package/templates/web/src/api/http-client.ts

@@ -0,0 +1,38 @@
+/**
+ * Farris 标准 HTTP 请求客户端封装
+ */
+export interface RequestOptions extends RequestInit {
+  params?: Record<string, any>;
+}
+
+export async function request<T = any>(url: string, options: RequestOptions = {}): Promise<T> {
+  const { params, ...customConfig } = options;
+
+  let requestUrl = url;
+  if (params && Object.keys(params).length > 0) {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, val]) => {
+      if (val !== undefined && val !== null) {
+        searchParams.append(key, String(val));
+      }
+    });
+    requestUrl += (url.includes('?') ? '&' : '?') + searchParams.toString();
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(customConfig.headers || {})
+  };
+
+  const response = await fetch(requestUrl, {
+    ...customConfig,
+    headers
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => response.statusText);
+    throw new Error(`HTTP Error ${response.status}: ${errorText}`);
+  }
+
+  return response.json();
+}

package/templates/web/src/api/index.ts

@@ -0,0 +1 @@
+export * from './user.api';

package/templates/web/src/api/user.api.ts

@@ -0,0 +1,21 @@
+import { request } from './http-client';
+
+export interface UserItem {
+  id: string;
+  name: string;
+  dept: string;
+}
+
+export interface UserListResponse {
+  data: UserItem[];
+  total?: number;
+}
+
+/**
+ * 用户列表。
+ *
+ * 开发期由工程内 mock/user.mock.ts 提供假数据；联调真实后端执行 pnpm dev --no-mock。
+ */
+export async function getUserList(): Promise<UserListResponse> {
+  return request<UserListResponse>('/api/v1/users');
+}

package/templates/web/src/views/HomeView.tsx

@@ -1,11 +1,43 @@
-import { defineComponent } from 'vue';
+import { defineComponent, onMounted, ref } from 'vue';
+import { getUserList, type UserItem } from '../api/user.api';
 
 export default defineComponent({
   name: 'HomeView',
   setup() {
+    const users = ref<UserItem[]>([]);
+    const loading = ref(false);
+    const error = ref('');
+
+    async function loadUsers(): Promise<void> {
+      loading.value = true;
+      error.value = '';
+      try {
+        users.value = (await getUserList()).data;
+      } catch (err) {
+        // 后端不可用时不阻塞页面：把失败原因显示出来即可
+        error.value = err instanceof Error ? err.message : '请求失败';
+      } finally {
+        loading.value = false;
+      }
+    }
+
+    onMounted(loadUsers);
+
     return () => (
       <main>
         <h1>Home</h1>
+        <p>下面的数据来自工程内 mock/ 目录的假接口；联调真实后端执行 pnpm dev --no-mock。</p>
+        {loading.value ? <p>加载中…</p> : null}
+        {!loading.value && error.value ? <p>加载失败：{error.value}</p> : null}
+        {!loading.value && !error.value ? (
+          <ul>
+            {users.value.map((user) => (
+              <li key={user.id}>
+                {user.name}（{user.dept}）
+              </li>
+            ))}
+          </ul>
+        ) : null}
         <p>在 src/views/ 下新增页面；通用组件按需创建在 src/components/ 下。</p>
       </main>
     );

package/templates/web/src/views/__tests__/HomeView.spec.tsx

@@ -4,8 +4,10 @@ import HomeView from '../HomeView';
 
 describe('HomeView', () => {
   it('mounts', () => {
+    // 页面挂载时会请求接口（开发期由 mock/ 提供数据），这里只断言首屏能渲染
     const wrapper = mount(HomeView);
 
     expect(wrapper.exists()).toBe(true);
+    expect(wrapper.text()).toContain('Home');
   });
 });