@teamix-evo/skills 0.3.0 → 0.4.0

package/src/teamix-evo-code-uni-manager/testing.md

@@ -0,0 +1,396 @@
+# 测试规范（uni-manager）
+
+> **核心约定**:`vitest` + `@testing-library/react` + `msw`,文件就近 `*.test.ts(x)`。**不追求覆盖率数字**,追求"关键路径必有测试 + 纯函数全测"。**uni-manager 额外要求 msw handler 校验 X-Tenant-Id / X-Region-Id / X-Cloud-Provider 请求头。**
+
+---
+
+## 选型(业界主流)
+
+| 类型        | 工具                                                     | 理由                                             |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------ |
+| 测试 runner | `vitest`                                                 | 与 Vite 原生集成,ESM 友好,API 与 Jest 兼容       |
+| 组件测试    | `@testing-library/react` + `@testing-library/user-event` | 测行为不测实现,业界事实标准(Kent C. Dodds)       |
+| API mock    | `msw`(Mock Service Worker)                               | 拦截真实 fetch / axios,测试与生产共用 service 层 |
+| 断言        | `vitest` 内置 `expect`(兼容 Jest)                        | 无需 chai                                        |
+| E2E(可选)   | `playwright`                                             | 关键流程冒烟,**不在本 skill 范围**               |
+
+**不要混用**:已经选 vitest 就不要再加 jest;已经用 msw 就不要再自己 mock axios。
+
+---
+
+## §1 · 文件位置
+
+测试文件**就近**放在被测文件同目录,`<name>.test.ts(x)`:
+
+```
+src/
+├── utils/
+│   ├── format.ts
+│   └── format.test.ts                    # ← 紧邻
+├── services/
+│   ├── instance.ts
+│   └── instance.test.ts
+├── hooks/
+│   ├── useInstanceList.ts
+│   └── useInstanceList.test.ts
+└── components/
+    ├── InstanceStatusBadge.tsx
+    └── InstanceStatusBadge.test.tsx
+```
+
+**不要**集中放在 `tests/` / `__tests__/` 顶层 —— 业界共识已偏向就近,便于维护与移动。
+
+测试辅助资源(fixtures、mock handler)放 `src/test/`:
+
+```
+src/test/
+├── setup.ts                  # vitest setup(jest-dom、msw server、active-context 重置)
+├── handlers.ts               # msw handler 集合(必须断言 X-Tenant-Id 等 header)
+├── render.tsx                # 自定义 render(包 Provider:QueryClient + Tenant + Region)
+└── fixtures/
+    ├── instance.ts           # 测试数据工厂
+    └── tenant.ts             # 租户工厂
+```
+
+---
+
+## §2 · 应该写什么测试(优先级)
+
+按 ROI 排序:
+
+| 优先级 | 类型                                    | 例子                                           | 必测?          |
+| ------ | --------------------------------------- | ---------------------------------------------- | -------------- |
+| P0     | 纯函数(`src/utils/`、`src/services/`)   | `formatMoney`、`isValidInstance`               | ✅ **必测**    |
+| P0     | zod schema                              | `CreateInstanceInputSchema.parse(...)`         | ✅ **必测**    |
+| P0     | 关键业务路径(创建实例 / 释放 / 切租户)  | E2E-style 组件测                               | ✅ **必测**    |
+| P0     | **interceptor / active-context 切换**   | 切租户后请求带新 X-Tenant-Id,旧缓存 invalidate | ✅ **必测**    |
+| P0     | **danger 流程(useDangerConfirm)**       | 输入正确名才 enable 按钮、关闭后状态重置       | ✅ **必测**    |
+| P1     | Hook(数据 hook + 自定义 UI hook)        | `useInstanceList`、`useDebounce`               | 推荐           |
+| P1     | 复用业务组件(`src/components/`)         | `CloudBadge` 各 cloud 渲染                     | 推荐           |
+| P2     | 页面组件                                | 用 RTL 渲染 + msw mock                         | 可选           |
+| ❌     | ui 包源码                               | 已在 `@teamix-evo/ui` 包内测过                 | **不要重复测** |
+| ❌     | biz-ui/uni-manager 包源码(如 um-topbar) | 已在 biz-ui 包内测过                           | **不要重复测** |
+| ❌     | 三方库                                  | `react-router`、`react-query`                  | **不要测**     |
+
+**红线**:不要为了凑覆盖率数字测 `Button` 能不能渲染、`React.useState` 能不能用。
+
+---
+
+## §3 · 标准测试模式
+
+### 纯函数
+
+```ts
+// src/utils/format.test.ts
+import { describe, it, expect } from 'vitest';
+import { formatCloudProvider } from './cloud';
+
+describe('formatCloudProvider', () => {
+  it('aws → Amazon Web Services', () => {
+    expect(formatCloudProvider('aws')).toBe('Amazon Web Services');
+  });
+  it('未知 cloud 回退到原值', () => {
+    expect(formatCloudProvider('unknown' as never)).toBe('unknown');
+  });
+});
+```
+
+约定:
+
+- 一个 `describe` 一个函数
+- 一个 `it` 一个行为(不堆 5 个 expect 测无关行为)
+- 测试名是**行为描述**,不是函数名
+
+### Service 函数(用 msw,**必须校验 tenant/region header**)
+
+```ts
+// src/test/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+// uni-manager 强约束:每个 handler 都要断言 tenant header
+function assertTenantHeader(request: Request): string {
+  const tenantId = request.headers.get('X-Tenant-Id');
+  if (!tenantId) {
+    throw new Error('Missing X-Tenant-Id header — interceptor 未注入或被绕过');
+  }
+  return tenantId;
+}
+
+export const handlers = [
+  http.get('/api/instances', ({ request }) => {
+    const tenantId = assertTenantHeader(request);
+    const regionId = request.headers.get('X-Region-Id');
+    return HttpResponse.json({
+      list: [{ id: 'i-1', tenantId, regionId, status: 'running' }],
+    });
+  }),
+  http.post('/api/instances', async ({ request }) => {
+    assertTenantHeader(request);
+    const body = (await request.json()) as Record<string, unknown>;
+    return HttpResponse.json({ id: 'i-new', ...body });
+  }),
+  // 跨云聚合:cloud header 必须存在
+  http.get('/api/cloud/instances', ({ request }) => {
+    const cloud = request.headers.get('X-Cloud-Provider');
+    if (!cloud) throw new Error('Missing X-Cloud-Provider header');
+    return HttpResponse.json({ list: [], cloud });
+  }),
+];
+```
+
+```ts
+// src/test/setup.ts
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll, beforeEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { handlers } from './handlers';
+import { setActiveTenant, setActiveRegion } from '@/lib/active-context';
+
+const server = setupServer(...handlers);
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+// uni-manager 必须:每个 test 前重置 active-context,避免上一 test 污染
+beforeEach(() => {
+  setActiveTenant({ id: 't-default', name: 'Default Tenant' });
+  setActiveRegion({ id: 'cn-hangzhou', name: '华东1' });
+});
+```
+
+```ts
+// src/services/instance.test.ts
+import { describe, it, expect } from 'vitest';
+import { listInstances } from './instance';
+import { setActiveTenant } from '@/lib/active-context';
+
+describe('listInstances', () => {
+  it('返回实例列表(自动带当前 tenant header)', async () => {
+    const instances = await listInstances();
+    expect(instances).toHaveLength(1);
+    expect(instances[0].tenantId).toBe('t-default');
+  });
+
+  it('切换 active tenant 后,后续请求带新 tenantId', async () => {
+    setActiveTenant({ id: 't-other', name: 'Other Tenant' });
+    const instances = await listInstances();
+    expect(instances[0].tenantId).toBe('t-other');
+  });
+});
+```
+
+### Hook(包 Provider 树)
+
+```tsx
+// src/test/render.tsx
+import { render, renderHook, type RenderOptions } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { TenantProvider } from '@/contexts/TenantContext';
+import { RegionProvider } from '@/contexts/RegionContext';
+
+function createWrapper(route = '/') {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    const qc = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    return (
+      <QueryClientProvider client={qc}>
+        <TenantProvider>
+          <RegionProvider>
+            <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+          </RegionProvider>
+        </TenantProvider>
+      </QueryClientProvider>
+    );
+  };
+}
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  { route = '/', ...options }: RenderOptions & { route?: string } = {},
+) {
+  return render(ui, { wrapper: createWrapper(route), ...options });
+}
+
+export function renderHookWithProviders<R, P>(
+  hook: (props: P) => R,
+  { route = '/' }: { route?: string } = {},
+) {
+  return renderHook(hook, { wrapper: createWrapper(route) });
+}
+```
+
+```tsx
+// src/hooks/useInstanceList.test.tsx
+import { waitFor } from '@testing-library/react';
+import { renderHookWithProviders } from '@/test/render';
+import { useInstanceList } from './useInstanceList';
+
+it('加载实例列表(queryKey 含 tenantId)', async () => {
+  const { result } = renderHookWithProviders(() =>
+    useInstanceList({ status: 'all' }),
+  );
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toHaveLength(1);
+});
+```
+
+### 组件(testing-library 范式:测行为不测实现)
+
+```tsx
+// src/components/InstanceStatusBadge.test.tsx
+import { render, screen } from '@testing-library/react';
+import { InstanceStatusBadge } from './InstanceStatusBadge';
+
+it('running 状态显示"运行中"', () => {
+  render(<InstanceStatusBadge status="running" />);
+  expect(screen.getByText('运行中')).toBeInTheDocument();
+});
+
+it('terminated 状态有 destructive 视觉', () => {
+  render(<InstanceStatusBadge status="terminated" />);
+  expect(screen.getByText('已销毁')).toHaveClass('bg-destructive');
+});
+```
+
+### 用户交互(`user-event`)
+
+```tsx
+import userEvent from '@testing-library/user-event';
+import { renderWithProviders } from '@/test/render';
+
+it('释放实例:必须输入完整名称才能确认', async () => {
+  const onConfirm = vi.fn();
+  renderWithProviders(
+    <DangerConfirmDialog
+      open
+      title="释放实例 i-12345"
+      resourceName="i-12345"
+      onConfirm={onConfirm}
+      onClose={() => {}}
+    />,
+  );
+
+  const confirmBtn = screen.getByRole('button', { name: '确认释放' });
+  expect(confirmBtn).toBeDisabled();
+
+  await userEvent.type(screen.getByLabelText(/输入实例 ID 确认/), 'i-1234');
+  expect(confirmBtn).toBeDisabled(); // 不完全匹配
+
+  await userEvent.type(screen.getByLabelText(/输入实例 ID 确认/), '5');
+  expect(confirmBtn).toBeEnabled();
+
+  await userEvent.click(confirmBtn);
+  expect(onConfirm).toHaveBeenCalledOnce();
+});
+```
+
+**不要**用 `fireEvent` —— 它不模拟真实键盘 / 鼠标事件序列,`user-event` 才贴近真实用户。
+
+---
+
+## §4 · 关键集成测试:切租户 → invalidate → 新数据
+
+uni-manager 的核心交互之一是切换租户,**必须**有集成测试覆盖:
+
+```tsx
+// src/contexts/TenantContext.test.tsx
+import { renderWithProviders } from '@/test/render';
+import userEvent from '@testing-library/user-event';
+import { screen, waitFor } from '@testing-library/react';
+
+it('切换租户:invalidate 旧 query + 新请求带新 tenantId', async () => {
+  renderWithProviders(<TenantSwitcherTestHarness />);
+
+  // 初始:t-default 的实例
+  await waitFor(() => screen.getByText(/i-1.*t-default/));
+
+  // 切换到 t-other
+  await userEvent.click(screen.getByRole('button', { name: '切换到 t-other' }));
+
+  // 应该看到新 tenant 的实例(msw 根据 header 返回不同数据)
+  await waitFor(() => screen.getByText(/i-1.*t-other/));
+});
+```
+
+---
+
+## §5 · 反模式速查
+
+| 反模式                                   | 为什么禁                          | 应该                                            |
+| ---------------------------------------- | --------------------------------- | ----------------------------------------------- |
+| 测 `setState` 是否被调用                 | 测了实现,重构即崩                 | 测渲染结果 / 用户行为                           |
+| `getByTestId` 当默认查询                 | data-testid 跟可访问性绑不上      | `getByRole` / `getByLabelText` 优先             |
+| 一个 it 里 expect 10 次无关断言          | 失败定位难                        | 拆多个 it                                       |
+| mock 整个 hook(`vi.mock('@/hooks/...')`) | 失去集成价值                      | msw mock 后端,hook 真跑                         |
+| 自己 mock fetch / axios                  | 与生产代码路径不一致              | 用 msw                                          |
+| msw handler 不校验 X-Tenant-Id           | interceptor 失效不会被发现        | 每个 handler `assertTenantHeader(request)`      |
+| 测试间不重置 active-context              | 上一 test 污染下一 test 的 tenant | `beforeEach` 重置                               |
+| 测试里写 `setTimeout(..., 1000)` 等异步  | 慢且不稳定                        | `await waitFor` / `findBy*`                     |
+| 全局 mock console.error 静默             | 错过真实告警                      | 让测试输出 console.error,但 setup 里 fail on it |
+| 追求 80% 覆盖率刷数字                    | 测了没价值的代码                  | 按"优先级表"测,不看覆盖率盲冲                   |
+
+---
+
+## §6 · 装机指引
+
+```bash
+pnpm add -D vitest @vitest/ui @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom msw
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    globals: true, // 可选:免 import describe / it / expect
+  },
+});
+```
+
+```json
+// package.json scripts
+{
+  "test": "vitest",
+  "test:run": "vitest run",
+  "test:ui": "vitest --ui"
+}
+```
+
+`msw` 还需要初始化 worker(用于 dev 环境)或 server(node):
+
+```bash
+pnpm exec msw init public/ --save  # 浏览器 worker
+```
+
+---
+
+## §7 · 何时跑测试
+
+- **本地开发**:`pnpm test`(watch 模式),改文件即跑相邻 test
+- **commit 前**:pre-commit hook 跑改动文件的 test(可选,慢就关)
+- **CI**:`pnpm test:run`(必须,跑全量)
+- **PR**:CI 红 → 不合并
+
+---
+
+## AI 必须输出的测试日志
+
+新增 / 修改业务代码时,AI 必须在响应里说明测试覆盖情况:
+
+```
+## 测试覆盖
+
+- 新增 src/utils/cloud.ts → 同目录 cloud.test.ts(formatCloudProvider 4 case)
+- 新增 src/services/instance.ts:releaseInstance → instance.test.ts(成功 / 422 / tenant header 校验)
+- 新增 src/hooks/useReleaseInstance.ts → useReleaseInstance.test.tsx(success / error / 未确认 dangerName 不调 mutate)
+- 复用 src/components/CloudBadge.tsx → 已有 test 覆盖 aws/aliyun/azure,无需补
+- 切租户集成测试: ✅ TenantContext.test.tsx(invalidate + 新 tenantId header)
+- 跳过测: src/pages/instances/new/index.tsx(纯组合,关键逻辑已在 hook / form 层测)
+```
+
+如果跳过测试,**必须**写明原因(纯组合 / ui 包已测 / biz-ui 已测 / 一次性脚本)。

package/src/teamix-evo-design-opentrek/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: teamix-evo-design-opentrek
+description: |
+  Apply OpenTrek design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in an OpenTrek-variant project.
+  TRIGGER when: user asks to "新建 / 优化 / 重构 一个页面"、"做一个列表页 / 详情页 / 表单页 / 仪表盘"、"create / review / refactor a page、screen、dashboard、template"; intent involves layout structure, page-level information density, or multi-component composition; file write under `src/pages/**` or `src/templates/**`.
+  SKIP: single-component edits like "加个按钮"、"改 input 的 label"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).
+  Coordinates with: teamix-evo-code-opentrek (run alongside when the screen also creates new files).
+---
+
+# teamix-evo-design-opentrek
+
+> OpenTrek 设计体系 — 面向云控制台与企业级 B2B 产品的现代设计语言。
+> 沉稳、克制、可预期，强调高密度信息下的清晰与效率。
+>
+> 本技能是 **完整自包含** 的 OpenTrek 设计规则（非 overlay）。
+> Token 具体值请参照 `tokens/theme.css` 中的 CSS 变量，组件详细 API 通过 MCP `get_component_meta` 按需查询。
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## 意图路由
+
+收到页面相关请求时，按意图分流：
+
+| 意图     | 识别关键词                                         | 执行路径                                    |
+| -------- | -------------------------------------------------- | ------------------------------------------- |
+| **生成** | "生成" / "创建" / "新建" / "设计一个" / "做一个"   | → generation-flow.md 六步流程               |
+| **翻新** | "改造" / "升级" / "翻新" / "对齐规范" / "重新生成" | → generation-flow.md §翻新路径              |
+| **验证** | "检查" / "验证" / "评估" / "是否符合规范"          | → checklist.md 逐项对照                     |
+| **查询** | "token" / "色值" / "间距" / "组件尺寸"             | → foundations.md(MCP `tokens_*` 工具规划中) |
+
+## 三阶段 Dispatch
+
+```
+阶段 ① 确定页面类型
+  → 读 patterns/page-types.md 决策树
+  → 读 components.md 确认组件集
+
+阶段 ② 匹配子类型 + 布局
+  - List / Detail / Form    → patterns/{list|detail|form}-page.md
+  - Dashboard               → patterns/dashboard.md
+  - Dialog/Sheet/Drawer     → 视为复合组件(非页面);走 components.md §3.1 选型
+                              + boundaries.md F8 / F9 / S7 / C2 / FF1-FF4
+  → 读 patterns/page-types.md §6 确认页间流转(主流转图 / 规则 / CRUD 速查)
+  → 涉及用户旅程时读 flows.md(A 资源查找 / B 创建 / C 异常 / D 批量)
+
+阶段 ③ 生成代码
+  → 读 foundations.md (Token 约束)
+  → 读 boundaries.md (硬规则)
+  → MCP get_component_meta(id) 查组件 Props
+  → 对照 checklist.md 自检
+```
+
+## 文件索引
+
+| 文件                                                 | 职责                                                     |
+| ---------------------------------------------------- | -------------------------------------------------------- |
+| [philosophy.md](./philosophy.md)                     | 设计哲学 + 四大原则 + 方法论                             |
+| [generation-flow.md](./generation-flow.md)           | AI 六步生成/翻新/验证流程                                |
+| [boundaries.md](./boundaries.md)                     | 硬约束：F/FF/S/C/I 五组共 38 条规则([ERROR]/[WARN])      |
+| [checklist.md](./checklist.md)                       | 10 项自检清单                                            |
+| [foundations.md](./foundations.md)                   | Token 用法 + 排版 + 间距 + 色彩 + 圆角 + 阴影 + 动效     |
+| [components.md](./components.md)                     | 组件选型决策树 + 双层架构索引 + 组合规则                 |
+| [patterns/page-types.md](./patterns/page-types.md)   | 5 种页面类型 + 识别决策树 + Zone Map + 页间流转(§6)      |
+| [patterns/list-page.md](./patterns/list-page.md)     | 列表页模式 (6 种子类型)                                  |
+| [patterns/detail-page.md](./patterns/detail-page.md) | 详情页模式                                               |
+| [patterns/form-page.md](./patterns/form-page.md)     | 表单页模式 (含 wizard)                                   |
+| [patterns/dashboard.md](./patterns/dashboard.md)     | Dashboard 数据概览(StatCard / Chart 标准结构)            |
+| [flows.md](./flows.md)                               | 4 条核心用户旅程 + 流转自检                              |
+| [brand.md](./brand.md)                               | OpenTrek 品牌调性 + 文案语气 + 正反例                    |
+
+<!-- teamix-evo:managed:end -->