@teamix-evo/skills 0.3.0 → 0.5.0

package/src/teamix-evo-code-opentrek/file-structure.md

@@ -0,0 +1,282 @@
+# 业务工程目录约定
+
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 3 的强制读取项。AI 确定新文件放置位置前必须读完本文件。
+
+> 业内主流 React/Vite 业务工程的标准目录骨架。本文件是 AI 决定"新建文件应该放在哪"的唯一参考。
+
+---
+
+## 顶层 `src/` 骨架
+
+```
+src/
+├── pages/            # 路由页面(每个目录对应一条路由)
+├── components/       # 跨页面复用的业务组件
+├── services/         # 后端通信(纯函数,见 api-layering.md)
+├── hooks/            # 自定义 Hook(包含数据 hook、UI hook)
+├── contexts/         # React Context(跨子树共享、低频更新的全局态)
+├── stores/           # 高频全局态(zustand / jotai / redux,首次需要时引入,只用一种)
+├── types/            # Domain / API 类型声明(.ts 仅类型,无运行时)
+├── utils/            # 纯函数工具(无 React、无副作用)
+├── lib/              # 三方 SDK 包装、http 实例、环境配置、monitor
+├── routes/           # 路由配置 + 守卫(若用 react-router 集中式声明)
+├── layouts/          # 应用级 / 区域级布局(ConsoleLayout、AuthLayout)
+├── test/             # 测试基础设施(setup.ts、handlers.ts、render.tsx、fixtures/)
+├── styles/           # 全局样式 / token 覆盖(尽量少)
+├── assets/           # 图片 / 字体 / 静态文件
+├── locales/          # i18n 资源(可选)
+├── main.tsx          # 应用入口
+└── App.tsx           # 根组件
+```
+
+> 没列出的目录按需补,但**不要**新增同义层(如同时有 `utils/` 和 `helpers/`、`api/` 和 `services/`、`views/` 和 `pages/`)。`*.test.ts(x)` 文件**就近**放在被测文件同目录,**不要**集中堆到顶层 `tests/`(见 [`testing.md`](testing.md))。
+
+---
+
+## 各目录职责与边界
+
+### `src/pages/`
+
+**职责**:路由页面。一个目录 = 一条路由。
+
+```
+src/pages/
+├── orders/
+│   ├── index.tsx            # 列表页(/orders)
+│   ├── [id].tsx             # 详情页(/orders/:id),命名按路由方案
+│   ├── _components/         # 仅本页面用的子组件(下划线前缀,不导出给外部)
+│   │   └── OrderFilterBar.tsx
+│   └── _hooks/              # 仅本页面用的 hook
+│       └── useOrderFilter.ts
+└── users/
+    └── ...
+```
+
+约束:
+
+- 页面组件**默认 default export**,与文件名一致
+- `_components/` `_hooks/` 用下划线前缀标记**私有**,**禁止跨页面 import**
+- 跨页面用得到的组件/hook → 升到 `src/components/` `src/hooks/`
+
+### `src/components/`
+
+**职责**:跨页面复用的业务组件。
+
+```
+src/components/
+├── OrderStatusBadge.tsx
+├── UserAvatar.tsx
+└── filters/
+    ├── DateRangeFilter.tsx
+    └── StatusFilter.tsx
+```
+
+约束:
+
+- 命名 PascalCase,文件名 = 组件名
+- 单组件 = 单文件;复杂组件可建子目录 `<Name>/{index.tsx, types.ts, hooks.ts}`
+- **不要**重复 `@teamix-evo/ui` 已经提供的能力(见 [reuse-first.md](reuse-first.md))
+- **不要**写"小工具组件"如 `Wrapper`、`Container` —— 用 div + tailwind 即可
+
+### `src/services/`
+
+**职责**:后端通信纯函数。详见 [`api-layering.md`](api-layering.md)。
+
+### `src/hooks/`
+
+**职责**:跨页面复用的自定义 Hook。
+
+```
+src/hooks/
+├── useOrderList.ts          # 数据 hook(包 react-query)
+├── useCreateOrder.ts
+├── useDebounce.ts           # UI hook
+└── useMediaQuery.ts
+```
+
+约束:
+
+- 命名必须 `use` 开头
+- 单 hook = 单文件
+- 数据 hook 调 `src/services/`,**禁止**直接 fetch
+
+### 全局态选型决策
+
+**装机时默认不预装任何状态库**。按"最小够用"逐级升级,不要直接跳到 zustand:
+
+| 场景                                             | 用什么                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| 组件内状态                                       | `useState` / `useReducer`                                |
+| 跨少量组件、低频更新(当前用户、主题、语言、租户) | React `Context`                                          |
+| 跨域、多页面、**高频**更新的客户端态             | `src/stores/`(zustand / jotai / redux 选一)              |
+| 服务端数据(列表、详情、表单提交)                 | `react-query` / `swr`,**永远不进 Context、也不进 store** |
+
+「高频」的粗略判定:一个状态被 10+ 处读取、且每秒可能变化一次以上 —— Context 会触发整子树重渲染,这时才有引 store 的收益。
+
+Context 文件位置:
+
+- 全应用级(UserContext、ThemeContext)→ `src/contexts/<Name>Context.tsx`
+- 仅一个页面/子树用 → `src/pages/<id>/_components/<Name>Context.tsx`
+
+> 如果项目自始至终只用 Context + react-query 就能解决,**不需要**建 `src/stores/`,也不需要引 zustand。等真出现跨域高频全局态再装。
+
+### `src/stores/`
+
+**职责**:跨域、高频更新的客户端全局态。**不是**全局态的默认入口,先看上方「全局态选型决策」。
+
+约束:
+
+- 一个项目**只用一种**状态库(zustand / jotai / redux 选一,首次需要时引入并固定)
+- 按 domain 拆 store:`useOrderStore.ts`、`useUserStore.ts`
+- **不要**把服务端数据放 store —— 用 `react-query` / `swr` 缓存(它们就是异步 store)
+- **不要**为了消除一处 props drilling 就建 store —— 那是 Context 的场景
+
+### `src/types/`
+
+**职责**:类型声明。
+
+约束:
+
+- 只放 `.ts` 类型文件,**不导出运行时代码**
+- 按 domain 拆:`order.ts`、`user.ts`
+- 通用类型放 `api.ts`、`common.ts`
+
+### `src/utils/`
+
+**职责**:纯函数工具。
+
+约束:
+
+- **不依赖 React**(用了 React 应该是 hook,放 `src/hooks/`)
+- **不依赖 DOM**(用了 DOM 应该是 lib 层包装)
+- **不发请求**(发请求是 service)
+- 一个文件一个主题:`format.ts`、`validate.ts`、`array.ts`
+
+### `src/lib/`
+
+**职责**:三方 SDK 包装、http 实例、env 读取。
+
+```
+src/lib/
+├── http.ts                  # axios / fetch 实例(全局唯一)
+├── env.ts                   # import.meta.env 的类型化封装
+├── analytics.ts             # 埋点 SDK 包装
+└── map.ts                   # 第三方地图 SDK 包装
+```
+
+约束:
+
+- 这一层**与 React 解耦**,可以在 Node / 测试中跑
+- **不放业务逻辑** —— 业务逻辑去 service / hook
+
+### `src/routes/`
+
+仅当使用集中式路由声明(react-router data router)时才有:
+
+```
+src/routes/
+├── index.tsx                # createBrowserRouter 声明
+└── guards.tsx               # 鉴权守卫
+```
+
+文件路由(file-based routing)项目不需要这个目录。
+
+---
+
+## 命名约定
+
+| 类型           | 风格                                 | 例                        |
+| -------------- | ------------------------------------ | ------------------------- |
+| 目录           | kebab-case                           | `src/pages/order-detail/` |
+| React 组件文件 | PascalCase.tsx                       | `OrderStatusBadge.tsx`    |
+| Hook 文件      | camelCase.ts,`use` 前缀              | `useOrderList.ts`         |
+| Service 文件   | camelCase.ts,domain 名               | `order.ts`                |
+| 工具文件       | camelCase.ts                         | `formatDate.ts`           |
+| 类型文件       | camelCase.ts,domain 名               | `order.ts`                |
+| 常量文件       | camelCase.ts 或 SCREAMING_SNAKE 导出 | `constants.ts`            |
+| 测试文件       | `*.test.ts(x)` 紧邻被测文件          | `formatDate.test.ts`      |
+
+---
+
+## 路径别名
+
+业务工程默认配 `@/*` 指向 `src/*`,所有跨目录 import 走别名:
+
+```ts
+// ✅
+import { Button } from '@teamix-evo/ui';
+import { listOrders } from '@/services/order';
+import { OrderStatusBadge } from '@/components/OrderStatusBadge';
+
+// ❌
+import { listOrders } from '../../../services/order';
+```
+
+---
+
+## Import 边界(单向依赖)
+
+```
+pages   ──▶ components, hooks, services, types, utils, lib, stores
+components ──▶ hooks, services, types, utils, lib (NOT pages)
+hooks   ──▶ services, types, utils, lib, stores (NOT components, NOT pages)
+services ──▶ types, lib (NOT hooks, NOT components, NOT pages)
+stores  ──▶ types, utils, lib (NOT services, NOT hooks)
+types   ──▶ (no runtime imports)
+utils   ──▶ types only
+lib     ──▶ types only
+```
+
+要点:
+
+- **services 不依赖 React** —— 它是纯函数层
+- **types / utils / lib 是叶子层** —— 不依赖业务层,谁都能引
+- **反向依赖直接否决**(component 不能 import page,service 不能 import hook)
+
+---
+
+## 反模式速查
+
+| 反模式                                            | 为什么禁                         | 应该怎么做                                                                                   |
+| ------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
+| `src/views/`、`src/screens/` 与 `src/pages/` 并存 | 同义层,认知爆炸                  | 二选一,统一叫 `pages/`                                                                       |
+| `src/api/` 与 `src/services/` 并存                | 同义层                           | 统一叫 `services/`                                                                           |
+| `src/utils/` 与 `src/helpers/` 并存               | 同义层                           | 统一叫 `utils/`                                                                              |
+| 在 `src/components/` 里写 page-only 组件          | 抽象层级别错位                   | 放 `src/pages/<id>/_components/`                                                             |
+| 在 `src/utils/` 里写 React Hook                   | 边界错位                         | 放 `src/hooks/`                                                                              |
+| 一个文件 export 5 个不相关的工具                  | 命名失焦                         | 拆成多文件,一个主题一个文件                                                                  |
+| `index.ts` 大量 `export *` 当 barrel              | 影响 tree-shaking、循环依赖      | 显式 named export 需要的几个                                                                 |
+| 为消除一处 props drilling 直接引 zustand          | 升级过度,徒增心智                | 用 React `Context`                                                                           |
+| 服务端数据塞进 Context / store                    | 与 query 缓存形成双源,易漂移     | 一律走 `react-query` / `swr`                                                                 |
+| 表单字段用一堆 `useState` 拼                      | 字段越多越糟,校验散落            | `useForm` + `zodResolver`(见 [`forms-and-validation.md`](forms-and-validation.md))           |
+| 页面顶部 `import` 不 lazy + 无 Suspense           | 首屏 bundle 爆炸 / 进入即崩      | `React.lazy` + Layout 挂 Suspense(见 [`routing-and-codesplit.md`](routing-and-codesplit.md)) |
+| 鉴权写在每个 page 顶部                            | 散乱、易漏、UI 与 URL 两层不一致 | `src/routes/guards.tsx` 集中,URL 与 sidebar 两层都判                                         |
+| 全局没有 ErrorBoundary                            | 任何未捕获异常直接白屏           | App 根挂 `ErrorBoundary` + `reportError`                                                     |
+| 测试堆在顶层 `tests/` 目录                        | 改文件忘记移动测试,易漂移        | `*.test.ts(x)` 就近紧邻被测文件                                                              |
+| `alert()` / `window.location.href = ...`          | 阻断、丑、丢状态                 | `toast.error()` / `useNavigate()`                                                            |
+
+---
+
+## 决策速查表
+
+| AI 收到的请求                             | 文件应该放在                                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
+| 新增订单列表页                            | `src/pages/orders/index.tsx`                                                                  |
+| 新增订单状态徽章(跨页面用)                | `src/components/OrderStatusBadge.tsx`                                                         |
+| 新增订单状态徽章(只在订单页用)            | `src/pages/orders/_components/OrderStatusBadge.tsx`                                           |
+| 新增"取消订单"接口调用                    | `src/services/order.ts` 加 `cancelOrder`                                                      |
+| 新增"取消订单"的 mutation hook            | `src/hooks/useCancelOrder.ts`                                                                 |
+| 新增日期格式化函数                        | `src/utils/format.ts`(先 grep 是否已存在)                                                     |
+| 新增鉴权拦截器                            | `src/lib/http.ts` 加 interceptor                                                              |
+| 新增订单 domain 类型                      | `src/types/order.ts`                                                                          |
+| 跨少量组件分享当前用户 / 主题             | `src/contexts/UserContext.tsx`(用 React Context)                                              |
+| 跨域高频全局态(首次需要)                  | `src/stores/useXxxStore.ts`(按需引 zustand,固定后只用一种)                                    |
+| 列表 / 详情等服务端数据                   | `src/hooks/useXxx.ts` 包 `react-query`,**不进** store / Context                               |
+| 新增"下单表单"(react-hook-form + zod)     | `src/pages/orders/new/_components/CreateOrderForm.tsx` + `src/services/order.schema.ts`       |
+| 跨页面复用表单(地址 / 客户搜索)           | `src/components/forms/<Name>Form.tsx` + 对应 schema                                           |
+| 新增路由 / 页面入口                       | `src/routes/index.tsx` 注册 + `src/pages/<id>/index.tsx`(default export,被 `React.lazy` 引入) |
+| 新增鉴权 / 角色守卫                       | `src/routes/guards.tsx`                                                                       |
+| 全局 ErrorBoundary fallback 组件          | `src/components/GlobalErrorFallback.tsx`                                                      |
+| Sentry / 日志上报包装                     | `src/lib/monitor.ts`(`reportError(err, extra?)`)                                              |
+| 测试基础设施(msw handler / 自定义 render) | `src/test/handlers.ts` / `src/test/render.tsx`                                                |
+| 纯函数 / service / hook 的测试            | 同目录 `<name>.test.ts(x)`(就近,不集中)                                                       |

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/forms-and-validation.md

@@ -1,17 +1,19 @@
 # 表单与校验规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 4 的条件读取项。任务涉及表单时必须读取。
+
 > **核心约定**:表单状态用 `react-hook-form`,schema 用 `zod`,**永远不要**用一堆 `useState` 拼表单。
 
 ---
 
 ## 为什么选这个组合(业界事实标准)
 
-| 维度 | react-hook-form + zod | 多 `useState` 拼 |
-| --- | --- | --- |
-| 重渲染 | 字段级订阅,只渲染变化的字段 | 任意字段变化整个表单重渲染 |
-| 校验 | schema 驱动,前后端共用 | 散落在 onChange 里,易漏 |
-| 复杂表单 | resolver + watch + array fields 内建 | 自己实现一遍 |
-| TypeScript | 从 schema 自动推导类型 | 手写类型,易漂移 |
+| 维度       | react-hook-form + zod                | 多 `useState` 拼           |
+| ---------- | ------------------------------------ | -------------------------- |
+| 重渲染     | 字段级订阅,只渲染变化的字段          | 任意字段变化整个表单重渲染 |
+| 校验       | schema 驱动,前后端共用               | 散落在 onChange 里,易漏    |
+| 复杂表单   | resolver + watch + array fields 内建 | 自己实现一遍               |
+| TypeScript | 从 schema 自动推导类型               | 手写类型,易漂移            |
 
 参考:[React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) 是 2024+ React 生态默认组合,被 shadcn/ui、Vercel、Linear、Cal.com 等广泛采用。
 
@@ -141,12 +143,12 @@ export function CreateOrderForm() {
 
 ## 校验规则
 
-| 场景 | 写在哪 |
-| --- | --- |
-| 字段格式(邮箱 / 手机号 / URL) | zod schema(`z.string().email()`) |
-| 业务规则(库存检查 / 唯一性) | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
-| 跨字段约束(开始日期 < 结束日期) | zod `.refine()` / `.superRefine()` |
-| 异步校验(用户名是否被占用) | `useQuery` + debounce,**不放 schema** |
+| 场景                            | 写在哪                                          |
+| ------------------------------- | ----------------------------------------------- |
+| 字段格式(邮箱 / 手机号 / URL)   | zod schema(`z.string().email()`)                |
+| 业务规则(库存检查 / 唯一性)     | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
+| 跨字段约束(开始日期 < 结束日期) | zod `.refine()` / `.superRefine()`              |
+| 异步校验(用户名是否被占用)      | `useQuery` + debounce,**不放 schema**           |
 
 ### 反模式
 

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/reuse-first.md

@@ -1,5 +1,7 @@
 # Reuse-First · 组件 / 工具复用决策流
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 1 的强制读取项。AI 写任何新代码前必须先读完本文件并执行复用查询。
+
 > 在写**任何**新组件 / Hook / 工具函数之前,AI 必须按本流程跑一遍。"没找到现成的"必须是查询的结论,不能是默认假设。
 
 ---
@@ -13,8 +15,8 @@
 │   ├── 是 → 走 §1（查 @teamix-evo/ui 注册表）
 │   └── 否 → 跳 Step 2
 │
-├── Step 2: 这是业务组件 / 页面模板吗?
-│   ├── 是 → 走 §2（查 @teamix-evo/biz-ui 与 @teamix-evo/templates）
+├── Step 2: 这是业务组件 / 页面骨架吗?
+│   ├── 是 → 走 §2（查 @teamix-evo/biz-ui；页面骨架走 design skill 的 patterns/）
 │   └── 否 → 跳 Step 3
 │
 ├── Step 3: 这是工具函数 / Hook 吗?
@@ -39,12 +41,12 @@
 
 ### 命中后的处理
 
-| 情况 | 处理 |
-| --- | --- |
-| 注册表里有,本项目已装 | 直接 `import` 复用,**不要复制源码** |
-| 注册表里有,本项目未装 | 提示用户跑 `teamix-evo ui add <id>`,装机后再用 |
+| 情况                            | 处理                                           |
+| ------------------------------- | ---------------------------------------------- |
+| 注册表里有,本项目已装           | 直接 `import` 复用,**不要复制源码**            |
+| 注册表里有,本项目未装           | 提示用户跑 `teamix-evo ui add <id>`,装机后再用 |
 | 注册表里有近义但 props 不完全够 | **优先组合**(包一层 wrapper),不要 fork ui 源码 |
-| 注册表里完全没有 | 进 §4 |
+| 注册表里完全没有                | 进 §4                                          |
 
 ### 反模式(禁止)
 
@@ -54,20 +56,28 @@
 
 ---
 
-## §2 · 业务组件 / 页面模板:查 `biz-ui` 与 `templates`
+## §2 · 业务组件:查 `biz-ui`(页面骨架走 design skill 的 patterns/)
 
-| 包 | 用途 | 查询入口 |
-| --- | --- | --- |
+| 包                   | 用途                                   | 查询入口                                               |
+| -------------------- | -------------------------------------- | ------------------------------------------------------ |
 | `@teamix-evo/biz-ui` | 业务化的复合组件(变体感知 + slot 边界) | 本项目 `node_modules/@teamix-evo/biz-ui/manifest.json` |
-| `@teamix-evo/templates` | 页面模板(slot-based) | 同上 |
+
+### 页面骨架来源(列表 / 详情 / 表单 / 仪表盘)
+
+> ⚠️ **AI 默认不调用 `@teamix-evo/templates` 包**(见 [ADR 0031](../../../docs/adr/0031-skill-templates-decoupling.md))。页面骨架按下列优先级生成:
+
+1. **首选** —— 读 `teamix-evo-design-opentrek` skill 的 [`patterns/{list|detail|form|dashboard}-page.md`](../teamix-evo-design-opentrek/patterns/),按 Zone Map 与决策树用 ui 原子件 + biz-ui 业务件**直接拼装**到 `src/pages/<id>/`
+2. **patterns/ 未覆盖时** —— 按业界流行的中后台页面架构(antd Pro / shadcn Examples 等)与用户描述自由实现,**不要回退到 templates 包**
+3. **`@teamix-evo/templates` 包与 CLI 命令仍保留**,但仅在用户**显式**要求(如"用 templates 包的 frozen 骨架")时才走 `teamix-evo templates add`
 
 ### 决策表
 
-| 场景 | 选择 |
-| --- | --- |
-| 列表页 / 详情页 / 表单页骨架 | 优先 `templates` |
-| "带筛选的用户表格"、"带审批流的卡片" | 优先 `biz-ui` |
-| 一次性的、强领域绑定的组合 | 写在 `src/components/<domain>/` 里,**不要污染 biz-ui** |
+| 场景                                  | 选择                                                      |
+| ------------------------------------- | --------------------------------------------------------- |
+| 列表页 / 详情页 / 表单页 / 仪表盘骨架 | 读 design skill `patterns/*.md` → ui + biz-ui 拼装        |
+| "带筛选的用户表格"、"带审批流的卡片"  | 优先 `biz-ui`                                             |
+| 一次性的、强领域绑定的组合            | 写在 `src/components/<domain>/` 里,**不要污染 biz-ui**    |
+| patterns/ 未覆盖的特殊页面            | 按业界流行架构 + 用户描述自由实现,**不调用 templates 包** |
 
 ---
 
@@ -102,7 +112,7 @@
 1. **命名要能让下次复用查得到** —— 起 `OrderStatusBadge` 而不是 `MyBadge`;`useOrderList` 而不是 `useList`。
 2. **抽象层级别低于一次性页面** —— 跨页面会用的才放 `src/components/`,只在一个页面用的写在 `src/pages/<id>/_components/`。
 3. **暴露面尽量窄** —— 默认只 `export` 这次需要的 API,别一次性 `export *`。
-4. **写完登记** —— 在 PR 描述里明确"新增 `<path>`,因为 ui / biz-ui / templates / 本项目均未提供 X 能力"。
+4. **写完登记** —— 在 PR 描述里明确"新增 `<path>`,因为 ui / biz-ui / patterns / 本项目均未提供 X 能力"(注:不再以 `templates` 包作为兜底依据,见 [ADR 0031](../../../docs/adr/0031-skill-templates-decoupling.md))。
 
 ---
 

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/routing-and-codesplit.md

@@ -1,6 +1,8 @@
 # 路由与代码分包规范
 
-> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兜底。
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 6 的条件读取项。任务涉及路由或页面入口时必须读取。
+
+> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兗底。
 
 ---
 
@@ -8,11 +10,11 @@
 
 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-dom@6` Data Router | **默认**。中后台 / SPA / 多页应用    |
+| `@tanstack/react-router`         | 类型安全要求极高、复杂 search params | (替换需在 ADR 记录) |
+| 文件路由(Next.js / Remix)        | 不在本 preset 范围                   |
 
 **一个项目只用一种**。已经用了 react-router 就不要混入 tanstack-router。
 
@@ -181,11 +183,11 @@ export function RoleGuard({
 
 每个项目**必须**有这三个页面,放在 `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` 兜底 |
+| 路径                | 文件                             | 触发场景                   |
+| ------------------- | -------------------------------- | -------------------------- |
+| `*` (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`,**不**单独建页面。
 
@@ -229,7 +231,7 @@ function OrderListPage() {
 import { useNavigate, Link } from 'react-router-dom';
 
 // 声明式(链接)
-<Link to={`/orders/${order.id}`}>查看</Link>
+<Link to={`/orders/${order.id}`}>查看</Link>;
 
 // 命令式(mutation success)
 const navigate = useNavigate();
@@ -249,15 +251,15 @@ mutation.mutate(values, {
 
 ## 反模式速查
 
-| 反模式 | 为什么禁 | 应该 |
-| --- | --- | --- |
-| 全部页面顶部 `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` 集中 |
+| 反模式                        | 为什么禁               | 应该                          |
+| ----------------------------- | ---------------------- | ----------------------------- |
+| 全部页面顶部 `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` 集中 |
 
 ---
 

package/{skills/teamix-evo-coding-conventions → src/teamix-evo-code-opentrek}/testing.md

@@ -1,18 +1,20 @@
 # 测试规范
 
+> ⚠️ **Prerequisites**: 本文件是 [SKILL.md](./SKILL.md) Step 7 的读取项。纯函数和 zod schema 必测，其余按关键路径覆盖。
+
 > **核心约定**:`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 范围** |
+| 类型        | 工具                                                     | 理由                                             |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------ |
+| 测试 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。
 
@@ -57,16 +59,16 @@ src/test/
 
 按 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` | **不要测** |
+| 优先级 | 类型                                  | 例子                                | 必测?          |
+| ------ | ------------------------------------- | ----------------------------------- | -------------- |
+| 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` 能不能用。
 
@@ -158,7 +160,9 @@ function wrapper({ children }: { children: React.ReactNode }) {
 }
 
 it('加载订单列表', async () => {
-  const { result } = renderHook(() => useOrderList({ status: 'all' }), { wrapper });
+  const { result } = renderHook(() => useOrderList({ status: 'all' }), {
+    wrapper,
+  });
   await waitFor(() => expect(result.current.isSuccess).toBe(true));
   expect(result.current.data).toHaveLength(1);
 });
@@ -238,16 +242,16 @@ 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% 覆盖率刷数字 | 测了没价值的代码 | 按"优先级表"测,不看覆盖率盲冲 |
+| 反模式                                   | 为什么禁                     | 应该                                            |
+| ---------------------------------------- | ---------------------------- | ----------------------------------------------- |
+| 测 `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% 覆盖率刷数字                    | 测了没价值的代码             | 按"优先级表"测,不看覆盖率盲冲                   |
 
 ---