@teamix-evo/skills 0.2.0 → 0.4.0

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

@@ -0,0 +1,273 @@
+# 业务工程目录约定
+
+> 业内主流 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/src/teamix-evo-code-opentrek/forms-and-validation.md

@@ -0,0 +1,220 @@
+# 表单与校验规范
+
+> **核心约定**:表单状态用 `react-hook-form`,schema 用 `zod`,**永远不要**用一堆 `useState` 拼表单。
+
+---
+
+## 为什么选这个组合(业界事实标准)
+
+| 维度 | 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 等广泛采用。
+
+---
+
+## Schema 落点
+
+```
+src/services/
+├── order.ts                # 请求函数:listOrders、createOrder
+└── order.schema.ts         # zod schema:CreateOrderInput、UpdateOrderInput
+```
+
+约定:
+
+- **每个 domain 一个 `<domain>.schema.ts`**,与 service 同目录
+- 从 schema 派生类型:`export type CreateOrderInput = z.infer<typeof CreateOrderInputSchema>`
+- service 的入参 / 返回类型**优先用** schema 推导,而不是手写 interface
+- **不要**把 schema 写在页面 / 组件文件里 —— schema 是 domain 资产,跨页面复用
+
+### 示例
+
+```ts
+// src/services/order.schema.ts
+import { z } from 'zod';
+
+export const CreateOrderInputSchema = z.object({
+  customerId: z.string().uuid(),
+  items: z
+    .array(
+      z.object({
+        skuId: z.string(),
+        quantity: z.number().int().positive(),
+      }),
+    )
+    .min(1, '至少添加一项'),
+  remark: z.string().max(200).optional(),
+});
+
+export type CreateOrderInput = z.infer<typeof CreateOrderInputSchema>;
+```
+
+```ts
+// src/services/order.ts
+import { http } from '@/lib/http';
+import type { CreateOrderInput } from './order.schema';
+import type { Order } from '@/types/order';
+
+export async function createOrder(input: CreateOrderInput): Promise<Order> {
+  // 服务端层也可在这里再 parse 一次防御
+  const { data } = await http.post('/api/orders', input);
+  return data;
+}
+```
+
+---
+
+## 表单组件结构
+
+### 简单表单(单页面专用)
+
+放在页面私有目录:
+
+```
+src/pages/orders/new/
+├── index.tsx                       # 路由组件
+└── _components/
+    └── CreateOrderForm.tsx         # useForm + UI
+```
+
+### 跨页面复用表单
+
+升到 `src/components/forms/<Name>Form.tsx`:
+
+```
+src/components/forms/
+├── AddressForm.tsx                 # 地址表单(下单页 + 用户中心都用)
+└── CustomerSearchForm.tsx
+```
+
+### 标准实现模板
+
+```tsx
+// src/pages/orders/new/_components/CreateOrderForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useCreateOrder } from '@/hooks/useCreateOrder';
+import {
+  CreateOrderInputSchema,
+  type CreateOrderInput,
+} from '@/services/order.schema';
+import { Button, Input, Form, FormField, FormItem } from '@/components/ui';
+
+export function CreateOrderForm() {
+  const form = useForm<CreateOrderInput>({
+    resolver: zodResolver(CreateOrderInputSchema),
+    defaultValues: { customerId: '', items: [], remark: '' },
+  });
+  const mutation = useCreateOrder();
+
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((values) => mutation.mutate(values))}
+        className="space-y-4"
+      >
+        <FormField
+          control={form.control}
+          name="customerId"
+          render={({ field }) => (
+            <FormItem>
+              <Input {...field} />
+            </FormItem>
+          )}
+        />
+        {/* ... 其他字段 */}
+        <Button type="submit" disabled={mutation.isPending}>
+          {mutation.isPending ? '提交中…' : '提交'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+---
+
+## 校验规则
+
+| 场景 | 写在哪 |
+| --- | --- |
+| 字段格式(邮箱 / 手机号 / URL) | zod schema(`z.string().email()`) |
+| 业务规则(库存检查 / 唯一性) | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
+| 跨字段约束(开始日期 < 结束日期) | zod `.refine()` / `.superRefine()` |
+| 异步校验(用户名是否被占用) | `useQuery` + debounce,**不放 schema** |
+
+### 反模式
+
+- ❌ 在 `onChange` 里手写 `if (value.length > 20) setError(...)`
+- ❌ 校验报错信息硬编码在组件里("请输入正确的手机号") —— 写在 schema 里,UI 只读
+- ❌ 表单状态用 `useState`,然后再加 `useEffect` 同步校验 —— 直接用 `useForm`
+- ❌ schema 在组件文件里就地定义 —— 抽到 `<domain>.schema.ts`
+- ❌ 提交逻辑写在 `<form onSubmit>` 里直接 fetch —— 走 mutation hook
+
+---
+
+## 表单提交错误如何展示
+
+```tsx
+const mutation = useCreateOrder();
+
+// 提交后:
+mutation.mutate(values, {
+  onError: (err) => {
+    // 1. 字段级错误回填 form(后端返回 { field, message }[])
+    if (isFieldErrors(err)) {
+      err.fields.forEach(({ field, message }) =>
+        form.setError(field as keyof CreateOrderInput, { message }),
+      );
+      return;
+    }
+    // 2. 通用错误走 toast(全局错误归一化在 lib/http.ts)
+    toast.error(err.message);
+  },
+});
+```
+
+要点:
+
+- 字段级错误 → `form.setError`(高亮对应输入框)
+- 通用错误 → `toast`(由 `lib/http.ts` 已归一化的 `Error.message`)
+- **不要**把后端错误对象塞到 form,先归一化
+
+---
+
+## 与 ui 包的边界
+
+`@teamix-evo/ui` 提供 `Form`、`FormField`、`FormItem`、`FormLabel`、`FormMessage`(shadcn 同款,基于 react-hook-form Context)。
+
+- **必须用 ui 包提供的 Form 组件**,不要自己 `<form>` + `<label>` 手撸
+- 业务表单只负责:schema + 字段 + 提交 callback,UI 一律走 ui 包
+
+---
+
+## 装机指引
+
+如果项目里还没装:
+
+```bash
+pnpm add react-hook-form zod @hookform/resolvers
+```
+
+`@hookform/resolvers` 提供 `zodResolver`,把 zod schema 接入 react-hook-form。
+
+---
+
+## AI 必须输出的表单日志
+
+```
+## 表单改动
+
+- src/services/order.schema.ts: 新增 CreateOrderInputSchema(zod)、派生类型
+- src/services/order.ts: createOrder 入参用派生类型
+- src/pages/orders/new/_components/CreateOrderForm.tsx: useForm + zodResolver
+- src/hooks/useCreateOrder.ts: useMutation 包 createOrder,onError 区分字段级 / 通用
+```

package/src/teamix-evo-code-opentrek/reuse-first.md

@@ -0,0 +1,130 @@
+# Reuse-First · 组件 / 工具复用决策流
+
+> 在写**任何**新组件 / Hook / 工具函数之前,AI 必须按本流程跑一遍。"没找到现成的"必须是查询的结论,不能是默认假设。
+
+---
+
+## 决策树
+
+```
+收到「写一个 xxx」请求
+│
+├── Step 1: 这是 UI 组件吗?
+│   ├── 是 → 走 §1（查 @teamix-evo/ui 注册表）
+│   └── 否 → 跳 Step 2
+│
+├── Step 2: 这是业务组件 / 页面骨架吗?
+│   ├── 是 → 走 §2（查 @teamix-evo/biz-ui；页面骨架走 design skill 的 patterns/）
+│   └── 否 → 跳 Step 3
+│
+├── Step 3: 这是工具函数 / Hook 吗?
+│   ├── 是 → 走 §3（grep 本项目 + 查常见库)
+│   └── 否 → 跳 Step 4
+│
+└── Step 4: 全部未命中 → 走 §4（写新代码,但要遵守归位规则）
+```
+
+---
+
+## §1 · UI 组件:必须先查 `@teamix-evo/ui` 注册表
+
+`@teamix-evo/ui` 是源码注入式 UI 组件库,**89 个条目**(button、input、dialog、data-table、…)。在写新 UI 组件之前:
+
+### 查询顺序(从快到慢)
+
+1. **MCP `list_components`** —— 一次列全部,扫描是否有同名 / 近义。
+2. **MCP `find_components` query=<关键词>** —— 子串匹配 id / name / description。
+3. **本项目 grep** —— `grep -r "from '@/components/ui'" src/` 看哪些已经装机。
+4. **本项目 `.teamix-evo/ui/manifest.lock.json`** —— 已装机的 ui entry 清单。
+
+### 命中后的处理
+
+| 情况                            | 处理                                           |
+| ------------------------------- | ---------------------------------------------- |
+| 注册表里有,本项目已装           | 直接 `import` 复用,**不要复制源码**            |
+| 注册表里有,本项目未装           | 提示用户跑 `teamix-evo ui add <id>`,装机后再用 |
+| 注册表里有近义但 props 不完全够 | **优先组合**(包一层 wrapper),不要 fork ui 源码 |
+| 注册表里完全没有                | 进 §4                                          |
+
+### 反模式(禁止)
+
+- ❌ 在 `src/components/` 下重写 `Button` / `Input` / `Dialog`(已经在 ui 包里)
+- ❌ 复制 ui 包源码到 `src/components/` 改样式 —— 改样式应当通过 design token 覆盖
+- ❌ 包 `antd` / `mui` / `chakra` 的同类组件 —— teamix-evo 的设计系统是 shadcn-based,混用会破坏 token 链路
+
+---
+
+## §2 · 业务组件:查 `biz-ui`(页面骨架走 design skill 的 patterns/)
+
+| 包                   | 用途                                   | 查询入口                                               |
+| -------------------- | -------------------------------------- | ------------------------------------------------------ |
+| `@teamix-evo/biz-ui` | 业务化的复合组件(变体感知 + slot 边界) | 本项目 `node_modules/@teamix-evo/biz-ui/manifest.json` |
+
+### 页面骨架来源(列表 / 详情 / 表单 / 仪表盘)
+
+> ⚠️ **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`
+
+### 决策表
+
+| 场景                                  | 选择                                                      |
+| ------------------------------------- | --------------------------------------------------------- |
+| 列表页 / 详情页 / 表单页 / 仪表盘骨架 | 读 design skill `patterns/*.md` → ui + biz-ui 拼装        |
+| "带筛选的用户表格"、"带审批流的卡片"  | 优先 `biz-ui`                                             |
+| 一次性的、强领域绑定的组合            | 写在 `src/components/<domain>/` 里,**不要污染 biz-ui**    |
+| patterns/ 未覆盖的特殊页面            | 按业界流行架构 + 用户描述自由实现,**不调用 templates 包** |
+
+---
+
+## §3 · 工具函数 / Hook:本项目优先,再查通用库
+
+### 顺序
+
+1. **本项目 grep**:
+   ```bash
+   grep -rn "function <近义名>" src/utils/ src/lib/ src/hooks/
+   ```
+2. **`@teamix-evo/*` 是否提供**(少数情况,如格式化、token 工具)
+3. **依赖里的成熟库** —— 例如:
+   - 日期 → `date-fns` / `dayjs`(看项目里已经装哪个,不要再装第三个)
+   - 数据请求 → `@tanstack/react-query` / `swr`
+   - 表单 → `react-hook-form` + `zod`
+   - 工具 → `lodash-es`、`es-toolkit`
+4. **完全没有现成** → 进 §4
+
+### 反模式
+
+- ❌ 写 `formatDate` 时不看项目用的是 dayjs 还是 date-fns,凭直觉新加一个
+- ❌ 同一项目里既装 `lodash` 又装 `lodash-es` 又装 `es-toolkit`
+- ❌ 自己写防抖 / 节流 / 深拷贝(标准库都有)
+
+---
+
+## §4 · 必须新写时的归位规则
+
+走到这一步,代码确实需要新写。归位见 [`file-structure.md`](file-structure.md);本节只讲**写新代码时**的最小约束:
+
+1. **命名要能让下次复用查得到** —— 起 `OrderStatusBadge` 而不是 `MyBadge`;`useOrderList` 而不是 `useList`。
+2. **抽象层级别低于一次性页面** —— 跨页面会用的才放 `src/components/`,只在一个页面用的写在 `src/pages/<id>/_components/`。
+3. **暴露面尽量窄** —— 默认只 `export` 这次需要的 API,别一次性 `export *`。
+4. **写完登记** —— 在 PR 描述里明确"新增 `<path>`,因为 ui / biz-ui / patterns / 本项目均未提供 X 能力"(注:不再以 `templates` 包作为兜底依据,见 [ADR 0031](../../../docs/adr/0031-skill-templates-decoupling.md))。
+
+---
+
+## AI 必须输出的决策日志
+
+完成代码改动时,AI **必须**在响应里附一段决策日志,例如:
+
+```
+## 复用决策
+
+- ✅ 复用 `@teamix-evo/ui` 的 `DataTable`(已装机)
+- ✅ 复用 `@teamix-evo/ui` 的 `Button`、`Badge`
+- 🆕 新写 `src/components/OrderStatusBadge.tsx` —— ui 包提供通用 `Badge`,但订单状态 → 颜色映射是业务逻辑,组合一层
+- ✅ 复用 `src/utils/format.ts` 的 `formatMoney`
+```
+
+没有这段日志,任务不算完成。