@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-code-opentrek/routing-and-codesplit.md

@@ -0,0 +1,298 @@
+# 路由与代码分包规范
+
+> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兜底。
+
+---
+
+## 路由库选型
+
+teamix-evo console preset 默认 `react-router-dom@6`(Data Router 模式,业界主流)。
+
+| 候选 | 何时选 |
+| --- | --- |
+| `react-router-dom@6` Data Router | **默认**。中后台 / SPA / 多页应用 |
+| `@tanstack/react-router` | 类型安全要求极高、复杂 search params | (替换需在 ADR 记录)
+| 文件路由(Next.js / Remix) | 不在本 preset 范围 |
+
+**一个项目只用一种**。已经用了 react-router 就不要混入 tanstack-router。
+
+---
+
+## §1 · 路由文件组织
+
+```
+src/routes/
+├── index.tsx              # createBrowserRouter 声明(单一来源)
+├── guards.tsx             # AuthGuard、RoleGuard
+└── lazy.tsx               # 统一的 lazy() 工厂,可选
+```
+
+**约定**:
+
+- 路由声明**只在** `src/routes/index.tsx`,不要散在多个 layout / page 里
+- 页面文件**默认 default export**,便于 `React.lazy`
+- 嵌套路由用 `children`,layout 用 `<Outlet />`
+
+### 标准声明
+
+```tsx
+// src/routes/index.tsx
+import { createBrowserRouter } from 'react-router-dom';
+import { lazy } from 'react';
+import { ConsoleLayout } from '@/layouts/ConsoleLayout';
+import { AuthGuard } from './guards';
+import { PageErrorFallback } from '@/components/PageErrorFallback';
+import { PageSkeleton } from '@/components/PageSkeleton';
+
+const DashboardPage = lazy(() => import('@/pages/dashboard'));
+const OrderListPage = lazy(() => import('@/pages/orders'));
+const OrderDetailPage = lazy(() => import('@/pages/orders/[id]'));
+const LoginPage = lazy(() => import('@/pages/login'));
+const NotFoundPage = lazy(() => import('@/pages/_not-found'));
+
+export const router = createBrowserRouter([
+  {
+    path: '/login',
+    element: <LoginPage />,
+  },
+  {
+    element: (
+      <AuthGuard>
+        <ConsoleLayout />
+      </AuthGuard>
+    ),
+    errorElement: <PageErrorFallback />,
+    children: [
+      { path: '/', element: <DashboardPage /> },
+      { path: '/orders', element: <OrderListPage /> },
+      { path: '/orders/:id', element: <OrderDetailPage /> },
+    ],
+  },
+  { path: '*', element: <NotFoundPage /> },
+]);
+```
+
+---
+
+## §2 · 代码分包(默认开启)
+
+### 规则
+
+- **每个页面文件**用 `React.lazy()` 引入 → vite 自动 chunk
+- 重型第三方库(图表、富文本、PDF)用动态 import 包一层组件,延迟到使用时加载
+- 同一 layout 下的多个 page 自动共享 layout chunk —— 不需要手动配
+
+### 不分包的例外
+
+- 登录页 / 错误页 / 404 → **不分包**(否则首屏要等 chunk 加载)
+- 主 layout / Header / Sidebar → **不分包**(立即用到)
+- < 5 KB 的小页面 → 分不分都行,默认分
+
+### 动态 import 重型库
+
+```tsx
+// ❌ 顶部 import:整个图表库进首屏 bundle
+import { LineChart } from 'recharts';
+
+// ✅ 用到时再加载
+const LineChart = lazy(() =>
+  import('recharts').then((m) => ({ default: m.LineChart })),
+);
+
+<Suspense fallback={<ChartSkeleton />}>
+  <LineChart data={data} />
+</Suspense>;
+```
+
+---
+
+## §3 · Suspense 配合
+
+每个 lazy 页面**必须**有 Suspense 兜底,否则首次进入会抛错。
+
+最佳实践:在 layout / route 配置里挂一次,所有 children 共享:
+
+```tsx
+// ConsoleLayout.tsx
+import { Outlet } from 'react-router-dom';
+import { Suspense } from 'react';
+
+export function ConsoleLayout() {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">
+        <Suspense fallback={<PageSkeleton />}>
+          <Outlet />
+        </Suspense>
+      </main>
+    </div>
+  );
+}
+```
+
+---
+
+## §4 · 鉴权 / 角色守卫
+
+### 模式:守卫组件包路由
+
+```tsx
+// src/routes/guards.tsx
+import { Navigate, useLocation } from 'react-router-dom';
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+
+export function AuthGuard({ children }: { children: React.ReactNode }) {
+  const { data: user, isPending } = useCurrentUser();
+  const location = useLocation();
+
+  if (isPending) return <PageSkeleton />;
+  if (!user) {
+    // 记录原 URL,登录后跳回
+    return <Navigate to="/login" state={{ from: location.pathname }} replace />;
+  }
+  return <>{children}</>;
+}
+
+export function RoleGuard({
+  roles,
+  children,
+}: {
+  roles: string[];
+  children: React.ReactNode;
+}) {
+  const { data: user } = useCurrentUser();
+  if (!user || !roles.some((r) => user.roles.includes(r))) {
+    return <Navigate to="/_forbidden" replace />;
+  }
+  return <>{children}</>;
+}
+```
+
+### 反模式
+
+- ❌ 每个页面顶部都写 `if (!user) navigate('/login')` —— 抽到守卫
+- ❌ 把角色判断写在 sidebar / button 的渲染逻辑里(只能藏入口,无法防直接访问 URL)—— 路由层判 + UI 层判,**两层都要**
+- ❌ 守卫里直接 fetch 用户信息 —— 走 `useCurrentUser` hook,享受缓存
+
+---
+
+## §5 · 必须存在的兜底路由
+
+每个项目**必须**有这三个页面,放在 `src/pages/_xxx/`(下划线前缀,表示非业务路由):
+
+| 路径 | 文件 | 触发场景 |
+| --- | --- | --- |
+| `*` (404) | `src/pages/_not-found/index.tsx` | 任何未匹配的 URL |
+| `/_forbidden` (403) | `src/pages/_forbidden/index.tsx` | 角色无权访问 |
+| `/_error` (500) | `src/pages/_error/index.tsx` | router `errorElement` 兜底 |
+
+未登录(401)由 `AuthGuard` 重定向到 `/login`,**不**单独建页面。
+
+---
+
+## §6 · search params 与状态同步
+
+列表页的筛选 / 分页 / 排序参数**必须**写进 URL,刷新 / 分享 / 浏览器后退都要还原:
+
+```tsx
+import { useSearchParams } from 'react-router-dom';
+
+function OrderListPage() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const status = searchParams.get('status') ?? 'all';
+  const page = Number(searchParams.get('page') ?? 1);
+
+  const { data } = useOrderList({ status, page });
+
+  return (
+    <Toolbar
+      status={status}
+      onStatusChange={(s) => setSearchParams({ status: s, page: '1' })}
+    />
+  );
+}
+```
+
+复杂场景用 [`nuqs`](https://nuqs.47ng.com/) 做类型化包装,业界常见。
+
+反模式:
+
+- ❌ 筛选状态只放 `useState` —— 刷新就丢
+- ❌ 分页放 store —— 多 tab 各自分页会互相污染
+
+---
+
+## §7 · 导航与跳转
+
+```tsx
+import { useNavigate, Link } from 'react-router-dom';
+
+// 声明式(链接)
+<Link to={`/orders/${order.id}`}>查看</Link>
+
+// 命令式(mutation success)
+const navigate = useNavigate();
+mutation.mutate(values, {
+  onSuccess: (order) => navigate(`/orders/${order.id}`),
+});
+```
+
+约束:
+
+- 静态跳 → `<Link>`(可右键打开新 tab)
+- 动态跳(提交后) → `useNavigate()`
+- **不要** `window.location.href = ...`(整页刷新,丢状态)
+- 外链 → 普通 `<a href target="_blank" rel="noopener noreferrer">`
+
+---
+
+## 反模式速查
+
+| 反模式 | 为什么禁 | 应该 |
+| --- | --- | --- |
+| 全部页面顶部 `import` 不 lazy | 首屏 bundle 爆炸 | `React.lazy` 每页 |
+| Lazy 但没 Suspense 兜底 | 进入页面报错 | Layout 挂一次 Suspense |
+| 鉴权写在每个 page 里 | 散乱、易漏 | 守卫组件 + 路由层 |
+| 路由声明分散在多处 | 难维护、易循环 | 唯一在 `src/routes/index.tsx` |
+| 列表筛选状态不进 URL | 刷新 / 分享 / 后退失效 | `useSearchParams` |
+| `window.location.href` 跳转 | 整页刷新 | `useNavigate` / `<Link>` |
+| 路由 path 写魔法字符串 | 改路径漏改 | 抽 `src/routes/paths.ts` 集中 |
+
+---
+
+## 进阶:Loader / Action(react-router v6.4+)
+
+如果项目愿意采用 Data Router 的 `loader` / `action` 模式,可把数据预取下沉到路由层:
+
+```tsx
+{
+  path: '/orders/:id',
+  element: <OrderDetailPage />,
+  loader: async ({ params }) => {
+    return queryClient.ensureQueryData({
+      queryKey: ['order', params.id],
+      queryFn: () => getOrder(params.id!),
+    });
+  },
+}
+```
+
+收益:页面切换时数据并行加载(不是渲染后才发请求),首屏更快。
+
+**慎用**:loader 写多了和 hook 形成两套数据流,需团队约定清楚。建议先用 hook + Suspense,熟练后再考虑 loader。
+
+---
+
+## AI 必须输出的路由日志
+
+```
+## 路由 / 分包改动
+
+- src/routes/index.tsx: 注册 /orders、/orders/:id(均 React.lazy)
+- src/pages/orders/index.tsx: default export(便于 lazy)
+- 守卫: ✅ 包在已有 AuthGuard 下
+- Suspense: ✅ ConsoleLayout 已挂一次,新增页面共用
+- search params: ✅ status / page 用 useSearchParams
+- 兜底: ✅ * → NotFoundPage 已存在
+```

package/src/teamix-evo-code-opentrek/testing.md

@@ -0,0 +1,313 @@
+# 测试规范
+
+> **核心约定**:`vitest` + `@testing-library/react` + `msw`,文件就近 `*.test.ts(x)`。**不追求覆盖率数字**,追求"关键路径必有测试 + 纯函数全测"。
+
+---
+
+## 选型(业界主流)
+
+| 类型 | 工具 | 理由 |
+| --- | --- | --- |
+| 测试 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/
+│   ├── order.ts
+│   └── order.test.ts
+├── hooks/
+│   ├── useOrderList.ts
+│   └── useOrderList.test.ts
+└── components/
+    ├── OrderStatusBadge.tsx
+    └── OrderStatusBadge.test.tsx
+```
+
+**不要**集中放在 `tests/` / `__tests__/` 顶层 —— 业界共识已偏向就近,便于维护与移动。
+
+测试辅助资源(fixtures、mock handler)放 `src/test/`:
+
+```
+src/test/
+├── setup.ts                  # vitest setup(jest-dom、msw server)
+├── handlers.ts               # msw handler 集合
+├── render.tsx                # 自定义 render(包 Provider)
+└── fixtures/
+    └── order.ts              # 测试数据工厂
+```
+
+---
+
+## §2 · 应该写什么测试(优先级)
+
+按 ROI 排序:
+
+| 优先级 | 类型 | 例子 | 必测? |
+| --- | --- | --- | --- |
+| P0 | 纯函数(`src/utils/`、`src/services/`) | `formatMoney`、`isValidOrder` | ✅ **必测** |
+| P0 | zod schema | `CreateOrderInputSchema.parse(...)` | ✅ **必测** |
+| P0 | 关键业务路径(下单 / 支付 / 鉴权) | E2E-style 组件测 | ✅ **必测** |
+| P1 | Hook(数据 hook + 自定义 UI hook) | `useOrderList`、`useDebounce` | 推荐 |
+| P1 | 复用业务组件(`src/components/`) | `OrderStatusBadge` 各状态渲染 | 推荐 |
+| P2 | 页面组件 | 用 RTL 渲染 + msw mock | 可选 |
+| ❌ | ui 包源码 | 已在 `@teamix-evo/ui` 包内测过 | **不要重复测** |
+| ❌ | 三方库 | `react-router`、`react-query` | **不要测** |
+
+**红线**:不要为了凑覆盖率数字测 `Button` 能不能渲染、`React.useState` 能不能用。
+
+---
+
+## §3 · 标准测试模式
+
+### 纯函数
+
+```ts
+// src/utils/format.test.ts
+import { describe, it, expect } from 'vitest';
+import { formatMoney } from './format';
+
+describe('formatMoney', () => {
+  it('保留两位小数', () => {
+    expect(formatMoney(1234.5)).toBe('1,234.50');
+  });
+  it('0 显示 0.00', () => {
+    expect(formatMoney(0)).toBe('0.00');
+  });
+  it('负数前置 -', () => {
+    expect(formatMoney(-1.5)).toBe('-1.50');
+  });
+});
+```
+
+约定:
+
+- 一个 `describe` 一个函数
+- 一个 `it` 一个行为(不堆 5 个 expect 测无关行为)
+- 测试名是**行为描述**,不是函数名("保留两位小数" ✓ / "test formatMoney" ❌)
+
+### Service 函数(用 msw)
+
+```ts
+// src/test/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  http.get('/api/orders', () =>
+    HttpResponse.json({ list: [{ id: 'o1', status: 'pending' }] }),
+  ),
+  http.post('/api/orders', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: 'o-new', ...body });
+  }),
+];
+```
+
+```ts
+// src/test/setup.ts
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { handlers } from './handlers';
+
+const server = setupServer(...handlers);
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+```ts
+// src/services/order.test.ts
+import { describe, it, expect } from 'vitest';
+import { listOrders } from './order';
+
+describe('listOrders', () => {
+  it('返回订单列表', async () => {
+    const orders = await listOrders({ status: 'all' });
+    expect(orders).toHaveLength(1);
+    expect(orders[0].id).toBe('o1');
+  });
+});
+```
+
+### Hook
+
+```tsx
+// src/hooks/useOrderList.test.tsx
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useOrderList } from './useOrderList';
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return <QueryClientProvider client={qc}>{children}</QueryClientProvider>;
+}
+
+it('加载订单列表', async () => {
+  const { result } = renderHook(() => useOrderList({ status: 'all' }), { wrapper });
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toHaveLength(1);
+});
+```
+
+### 组件(testing-library 范式:测行为不测实现)
+
+```tsx
+// src/components/OrderStatusBadge.test.tsx
+import { render, screen } from '@testing-library/react';
+import { OrderStatusBadge } from './OrderStatusBadge';
+
+it('pending 状态显示"待处理"', () => {
+  render(<OrderStatusBadge status="pending" />);
+  expect(screen.getByText('待处理')).toBeInTheDocument();
+});
+
+it('cancelled 状态有 destructive 视觉', () => {
+  render(<OrderStatusBadge status="cancelled" />);
+  expect(screen.getByText('已取消')).toHaveClass('bg-destructive');
+});
+```
+
+### 用户交互(`user-event`)
+
+```tsx
+import userEvent from '@testing-library/user-event';
+
+it('点击提交按钮触发 onSubmit', async () => {
+  const onSubmit = vi.fn();
+  render(<CreateOrderForm onSubmit={onSubmit} />);
+
+  await userEvent.type(screen.getByLabelText('客户'), 'cust-1');
+  await userEvent.click(screen.getByRole('button', { name: '提交' }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ customerId: 'cust-1', items: [] });
+});
+```
+
+**不要**用 `fireEvent` —— 它不模拟真实键盘 / 鼠标事件序列,`user-event` 才贴近真实用户。
+
+---
+
+## §4 · 自定义 render(包 Provider)
+
+每次 render 都重复套 QueryClient / Router / Theme 太繁琐,抽到 `src/test/render.tsx`:
+
+```tsx
+// src/test/render.tsx
+import { render, type RenderOptions } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  { route = '/', ...options }: RenderOptions & { route?: string } = {},
+) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>
+    </QueryClientProvider>,
+    options,
+  );
+}
+```
+
+测试里:
+
+```tsx
+import { renderWithProviders } from '@/test/render';
+
+renderWithProviders(<OrderListPage />, { route: '/orders?status=pending' });
+```
+
+---
+
+## §5 · 反模式速查
+
+| 反模式 | 为什么禁 | 应该 |
+| --- | --- | --- |
+| 测 `setState` 是否被调用 | 测了实现,重构即崩 | 测渲染结果 / 用户行为 |
+| `getByTestId` 当默认查询 | data-testid 跟可访问性绑不上 | `getByRole` / `getByLabelText` 优先 |
+| 一个 it 里 expect 10 次无关断言 | 失败定位难 | 拆多个 it |
+| mock 整个 hook(`vi.mock('@/hooks/...')`) | 失去集成价值 | msw mock 后端,hook 真跑 |
+| 自己 mock fetch / axios | 与生产代码路径不一致 | 用 msw |
+| 测试里写 `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/calcDiscount.ts → 同目录 calcDiscount.test.ts(5 个 case)
+- 新增 src/services/order.ts:createOrder → order.test.ts(成功 / 422 字段错 / 500)
+- 新增 src/hooks/useCreateOrder.ts → useCreateOrder.test.tsx(success / error)
+- 复用 src/components/OrderStatusBadge.tsx → 已有 test 覆盖,无需补
+- 跳过测: src/pages/orders/new/index.tsx(纯组合,关键逻辑已在 hook / form 层测)
+```
+
+如果跳过测试,**必须**写明原因(纯组合 / ui 包已测 / 一次性脚本)。