@teamix-evo/skills 0.2.0 → 0.4.0

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

@@ -0,0 +1,173 @@
+# 编码自检清单
+
+> AI 写完 / 改完代码后,**必须**逐项核对。任何一项未通过都不应交付,需要先修复或显式告诉用户哪条不通过、为什么。
+
+---
+
+## 1. 复用判定 ✓
+
+- [ ] 新建 UI 组件前,查过 `@teamix-evo/ui` 注册表(MCP `list_components` / `find_components`)
+- [ ] 新建 UI 组件前,grep 过本项目 `src/components/`
+- [ ] 新建工具函数前,grep 过 `src/utils/` `src/lib/` `src/hooks/`
+- [ ] 没有重复实现 ui 包已经提供的能力(Button、Input、Dialog、DataTable 等)
+- [ ] 没有 fork ui 包源码改样式(改样式应当走 design token)
+- [ ] 响应里**显式列出**复用决策日志(✅ 复用了哪些 / 🆕 新写了哪些及原因)
+
+## 2. 数据层分层 ✓
+
+- [ ] 组件**没有**直接调 `fetch` / `axios`
+- [ ] 组件**没有**直接读 `import.meta.env` / `process.env`(env 走 `src/lib/env.ts`)
+- [ ] 所有后端调用都落在 `src/services/<domain>.ts`,且是纯函数
+- [ ] Service 函数**不依赖 React**(没有 `useXxx`、没有 `useState`)
+- [ ] Service 函数**不弹通知 / 不跳路由**
+- [ ] 数据 hook 在 `src/hooks/`,使用统一的数据库(react-query / swr,不混用)
+- [ ] 全局只有一份 http 实例,在 `src/lib/http.ts`
+
+## 3. 目录归位 ✓
+
+- [ ] 新文件位于约定的顶层目录(`pages/`、`components/`、`services/`、`hooks/`、`stores/`、`types/`、`utils/`、`lib/`)
+- [ ] **没有**新增同义层(如 `views/`、`api/`、`helpers/` 与现有目录并存)
+- [ ] 仅在单个页面使用的组件 / hook 放在 `src/pages/<id>/_components/` 或 `_hooks/`(下划线前缀)
+- [ ] 跨页面复用的组件 / hook 才升到 `src/components/` `src/hooks/`
+- [ ] React Hook 在 `hooks/`,不在 `utils/`(`utils/` 不依赖 React)
+- [ ] 类型声明文件没有运行时代码(纯类型)
+
+## 4. 命名 ✓
+
+- [ ] 目录 kebab-case(`order-detail/`)
+- [ ] React 组件文件 PascalCase.tsx,文件名 = 组件名
+- [ ] Hook 文件 camelCase.ts,以 `use` 开头(`useOrderList.ts`)
+- [ ] Service 文件按 domain 命名(`order.ts`),不按 HTTP 动词(`getOrders.ts` ❌)
+- [ ] 名字能让下次复用时被 grep 命中(`OrderStatusBadge` ✓ / `MyBadge` ❌)
+
+## 5. Import 边界 ✓
+
+- [ ] 跨目录 import 走 `@/*` 别名,**未使用** `../../../` 相对路径上跳超过 2 层
+- [ ] **未发生反向依赖**:
+  - `components/` 没有 import `pages/`
+  - `services/` 没有 import `hooks/` `components/` `pages/`
+  - `hooks/` 没有 import `pages/`
+  - `utils/` `lib/` `types/` 没有 import 业务层
+- [ ] 页面私有目录(`_components/` `_hooks/`)**没有**被其他页面 import
+
+## 6. 类型 ✓
+
+- [ ] Domain 类型放 `src/types/<domain>.ts`,不在 service / component 文件就地定义
+- [ ] Service 函数有显式的入参 / 返回 `Promise<T>` 类型
+- [ ] 没有 `any`(必要的转义类型用 `unknown` 配合 narrowing,或加注释说明原因)
+- [ ] Hook 的返回类型由 `react-query` / `swr` 自动推断,无需手写
+
+## 7. 依赖卫生 ✓
+
+- [ ] 没有引入与项目内现有库**功能重复**的新依赖(如同时有 `lodash` 和 `lodash-es`)
+- [ ] 日期 / 数据请求 / 表单 / 状态等核心库**全项目统一**(看现有 `package.json`,不要新加同类)
+- [ ] 没有 `import` 未在 `package.json` 声明的包
+
+## 8. 副作用与可测性 ✓
+
+- [ ] Service 函数是纯函数(同样输入 → 同样输出,无隐式全局读写)
+- [ ] 工具函数(`src/utils/`)是纯函数
+- [ ] 没有在模块顶层(import 时)发请求 / 弹通知 / 改全局状态
+- [ ] 异步操作有错误处理路径(hook 暴露 `error`,UI 有 fallback)
+
+## 9. 表单与校验 ✓
+
+(若改动涉及表单 — 详见 [`forms-and-validation.md`](forms-and-validation.md))
+
+- [ ] 表单状态用 `react-hook-form`,**未用** `useState` 拼字段
+- [ ] 校验用 `zod` schema,schema 落 `src/services/<domain>.schema.ts`
+- [ ] 类型从 schema 推导(`z.infer<...>`),**未手写**重复 interface
+- [ ] 错误信息写在 schema 里,UI 只读取,**未在组件里硬编码**校验文案
+- [ ] 提交走 mutation hook,**未在** `<form onSubmit>` 里直接 fetch
+- [ ] 字段级 / 通用错误分别处理(`form.setError` vs `toast`)
+- [ ] 表单组件使用 `@teamix-evo/ui` 的 `Form` / `FormField`,**未自撸** `<form>`
+
+## 10. 错误与加载态 ✓
+
+(若改动包含 UI / 数据 hook — 详见 [`error-and-loading.md`](error-and-loading.md))
+
+- [ ] App 根**存在**全局 `ErrorBoundary` + `Toaster`
+- [ ] 全局 `onError` 调 `reportError`(`src/lib/monitor.ts`),**未**静默吞错
+- [ ] 数据 hook 三态全处理:`isPending` → Skeleton、`isError` → 错误面板 + 重试、data → 内容
+- [ ] **未用** `useState<boolean>` + `useEffect` 自管 loading
+- [ ] Mutation 成功 → `toast.success` + 跳转 / invalidate;失败 → `toast.error`,**未用** `alert()`
+- [ ] Skeleton 撑住布局,**未**用空 div 等待数据(防 CLS)
+- [ ] 长操作(> 1s)按钮 `disabled`,**未**允许双击重复提交
+
+## 11. 路由与代码分包 ✓
+
+(若改动涉及路由 — 详见 [`routing-and-codesplit.md`](routing-and-codesplit.md))
+
+- [ ] 新页面用 `React.lazy()` 引入(登录页 / 错误页 / Layout 例外)
+- [ ] Lazy 路由有 `<Suspense fallback>` 兜底
+- [ ] 鉴权 / 角色判断在 `src/routes/guards.tsx`,**未**写在每个 page 顶部
+- [ ] 路由声明集中在 `src/routes/index.tsx`,**未**分散在多文件
+- [ ] 404 / 403 / 500 兜底路由存在
+- [ ] 列表筛选 / 分页用 `useSearchParams`,**未**只放 `useState`
+- [ ] 跳转用 `<Link>` / `useNavigate`,**未用** `window.location.href`
+- [ ] 重型第三方库(图表 / 富文本 / PDF)用动态 import,**未**直接顶部 import
+
+## 12. 测试覆盖 ✓
+
+(详见 [`testing.md`](testing.md))
+
+- [ ] 新增纯函数(`src/utils/`、`src/services/`)有同名 `*.test.ts`(**必测**)
+- [ ] 新增 zod schema 有 `parse` 成功 / 失败用例(**必测**)
+- [ ] 关键业务路径(下单 / 支付 / 鉴权)有组件 / hook 测试(**必测**)
+- [ ] 测试文件就近放在 `<source>.test.ts(x)`,**未**集中到顶层 `tests/`
+- [ ] 用 `msw` mock 后端,**未**自己 mock fetch / axios
+- [ ] 测试名是行为描述("保留两位小数"),**不是**函数名("test formatMoney")
+- [ ] **未**为凑覆盖率测无价值代码(ui 包源码 / 三方库)
+- [ ] 跳过测试时显式说明原因(纯组合 / 已有覆盖 / 一次性脚本)
+
+## 13. 与 design 规范的协作 ✓
+
+(若改动包含 UI)
+
+- [ ] 视觉部分按 [`teamix-evo-design-opentrek`](../teamix-evo-design-opentrek/SKILL.md) 自检过 token / 间距 / 圆角 / 动效
+- [ ] 没有硬编码颜色 / 间距 / 字号(交给 ui 包 + design token)
+
+---
+
+## ⚠️ 红线(一票否决)
+
+任何一条触发即必须重写或回退:
+
+1. **组件直接 fetch / axios** —— 数据层未分层
+2. **新建 Button / Input / Dialog 等基础组件** —— 重造 ui 包能力
+3. **services 函数依赖 React** —— 边界穿透
+4. **`src/views/` 与 `src/pages/` 并存(或 `src/api/` 与 `src/services/`)** —— 同义层污染
+5. **响应里没有复用决策日志** —— 流程未跑通
+6. **反向依赖**(service 引 hook、component 引 page) —— 依赖图破坏
+7. **多份 http 实例** —— 鉴权 / 错误处理无法统一
+8. **没有全局 ErrorBoundary** —— 异常直接白屏给用户
+9. **表单用 `useState` 拼字段、用 onChange 手写校验** —— 弃 react-hook-form + zod
+10. **页面顶部 import 不 lazy + 没有 Suspense** —— 首屏 bundle 爆炸 / 进入即崩
+11. **纯函数 / zod schema 无单测** —— ROI 最高的测试缺位
+12. **`alert()` / `window.location.href` 出现在业务代码** —— 用 toast / useNavigate
+
+---
+
+## AI 输出格式建议
+
+完成改动时,在响应末尾附:
+
+```markdown
+## 编码合规自检
+
+- 复用判定: ✅ 复用 ui 包 Button / DataTable;🆕 新写 OrderStatusBadge(原因:业务状态映射)
+- 数据层: ✅ services/order.ts 纯函数;✅ hooks/useOrderList.ts 包 react-query;✅ 组件未 fetch
+- 目录: ✅ 页面在 pages/orders/;✅ 跨页面组件在 components/
+- 命名: ✅ kebab 目录 / Pascal 组件 / camel hook
+- 边界: ✅ 全部走 @/\*;✅ 无反向依赖
+- 类型: ✅ types/order.ts 集中声明
+- 表单(若涉及): ✅ useForm + zodResolver;✅ schema 在 services/order.schema.ts
+- 错误/加载(若涉及): ✅ 三态全处理;✅ ErrorBoundary 已在 App 根;✅ mutation toast
+- 路由(若涉及): ✅ React.lazy + Suspense;✅ 守卫已复用;✅ 404 兜底已存在
+- 测试: ✅ 新增 formatXxx → formatXxx.test.ts(5 case);✅ schema parse 失败用例已加
+- 红线: ✅ 全过
+
+未通过项: 无
+```
+
+如有未通过项,明确写出"❌ 第 X 条:<原因> → <处理方式>"。

package/src/teamix-evo-code-opentrek/error-and-loading.md

@@ -0,0 +1,269 @@
+# 错误与加载态规范
+
+> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兜底必须存在。**不允许**白屏 / 红屏直出给用户。
+
+---
+
+## 三层兜底
+
+```
+┌──────────────────────────────────────────┐
+│  App 根:全局 ErrorBoundary + Toaster     │  最后一道:防白屏 / 兜未捕获
+└──────────────┬───────────────────────────┘
+               │
+┌──────────────────────────────────────────┐
+│  路由 / 关键 widget:页面级 ErrorBoundary │  范围隔离:一页崩不带垮全站
+└──────────────┬───────────────────────────┘
+               │
+┌──────────────────────────────────────────┐
+│  数据 hook:isPending / isError           │  细粒度:每块数据自己的 loading
+└──────────────────────────────────────────┘
+```
+
+---
+
+## §1 · 全局 ErrorBoundary
+
+每个 teamix-evo 业务应用**必须**在根挂一个全局 ErrorBoundary,以及一个 toast 容器。
+
+### 推荐实现:`react-error-boundary`
+
+业界主流(2024+,Vercel / shadcn 模板默认),比手写 class component 更易组合。
+
+```tsx
+// src/main.tsx
+import { ErrorBoundary } from 'react-error-boundary';
+import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import { Toaster } from '@/components/ui';
+import { GlobalErrorFallback } from '@/components/GlobalErrorFallback';
+import { reportError } from '@/lib/monitor';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 30_000, retry: 1 },
+    mutations: { retry: 0 },
+  },
+});
+
+createRoot(document.getElementById('root')!).render(
+  <ErrorBoundary
+    FallbackComponent={GlobalErrorFallback}
+    onError={(err, info) => reportError(err, info)}
+  >
+    <QueryClientProvider client={queryClient}>
+      <App />
+      <Toaster />
+    </QueryClientProvider>
+  </ErrorBoundary>,
+);
+```
+
+```tsx
+// src/components/GlobalErrorFallback.tsx
+import { Button } from '@teamix-evo/ui';
+
+export function GlobalErrorFallback({ resetErrorBoundary }: { resetErrorBoundary: () => void }) {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-2xl font-semibold">页面出错了</h1>
+        <p className="text-muted-foreground mt-2">已记录,可尝试刷新或返回首页</p>
+        <Button className="mt-4" onClick={resetErrorBoundary}>重新加载</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+要点:
+
+- `onError` **必须**调 `reportError` 上报(Sentry / 自家日志)
+- fallback **必须**给用户可执行的下一步动作(重试 / 返回 / 联系支持)
+- **不要**只显示 "Something went wrong" —— 用户看到等于白屏
+
+---
+
+## §2 · 路由 / 页面级 ErrorBoundary
+
+跨路由的崩溃不应连带全站。在 router 配置或 Layout 里再嵌一层:
+
+```tsx
+// src/routes/index.tsx
+{
+  path: '/orders/:id',
+  element: (
+    <ErrorBoundary FallbackComponent={PageErrorFallback}>
+      <Suspense fallback={<PageSkeleton />}>
+        <OrderDetailPage />
+      </Suspense>
+    </ErrorBoundary>
+  ),
+}
+```
+
+或使用 react-router v6.4+ 的 `errorElement`(推荐,内置):
+
+```tsx
+{
+  path: '/orders/:id',
+  element: <OrderDetailPage />,
+  errorElement: <PageErrorFallback />,
+}
+```
+
+---
+
+## §3 · 数据加载态(react-query 范式)
+
+**不要**在组件里用 `useState<boolean>` + `useEffect` 自己管 loading。所有异步数据走 react-query:
+
+```tsx
+function OrderListPage() {
+  const { data, isPending, isError, error, refetch } = useOrderList(params);
+
+  if (isPending) return <TableSkeleton rows={10} />;
+  if (isError) return <ErrorPanel message={error.message} onRetry={refetch} />;
+
+  return <OrderTable data={data} />;
+}
+```
+
+### 三种状态都要处理
+
+| 状态 | 必须输出 |
+| --- | --- |
+| `isPending`(首次加载) | Skeleton / Spinner,**不允许**显示空 div |
+| `isError` | 错误面板 + 重试按钮,**不允许**直接 `throw` |
+| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩 |
+
+### Skeleton vs Spinner 怎么选
+
+| 场景 | 用 |
+| --- | --- |
+| 列表 / 卡片 / 详情 | Skeleton(撑住布局,避免 CLS) |
+| 短动作(按钮提交、< 500ms 加载) | Spinner |
+| 全屏切换 | PageSkeleton 或 logo loading |
+
+---
+
+## §4 · Mutation 反馈
+
+```tsx
+const mutation = useCreateOrder();
+
+mutation.mutate(values, {
+  onSuccess: (order) => {
+    toast.success(`订单 ${order.id} 已创建`);
+    navigate(`/orders/${order.id}`);
+  },
+  onError: (err) => {
+    toast.error(err.message); // 已被 lib/http.ts 归一化
+  },
+});
+```
+
+约束:
+
+- 成功 → `toast.success` + 跳转 / invalidate
+- 失败 → `toast.error`,**不要** `alert()`
+- 长操作(> 1s) → 按钮 `disabled` + 文案改"提交中…",**不要**双击重复提交
+- **不要**在 mutation 内部弹 toast —— hook 是数据通道,toast 由组件触发
+
+---
+
+## §5 · Suspense 数据边界(可选,渐进采用)
+
+react-query v5 支持 `useSuspenseQuery`,可把 loading 转给 `<Suspense>`:
+
+```tsx
+function OrderListPage() {
+  const { data } = useSuspenseQuery({ queryKey: ['orders'], queryFn: listOrders });
+  return <OrderTable data={data} />; // 不需要 isPending 分支
+}
+
+// 父级:
+<Suspense fallback={<TableSkeleton rows={10} />}>
+  <OrderListPage />
+</Suspense>
+```
+
+**何时用**:
+
+- 多个 query 需要"全部 ready 才渲染"时,Suspense 比手写 `if (a.isPending || b.isPending)` 简洁
+- 与 `React.lazy` 配合做代码分包(见 [`routing-and-codesplit.md`](routing-and-codesplit.md))
+
+**何时不用**:
+
+- 单一 query 的简单页面,直接 `isPending` 分支更直观
+- 团队对 Suspense 还不熟 → 先用 `isPending`,慢慢迁
+
+---
+
+## §6 · 全局错误上报
+
+```ts
+// src/lib/monitor.ts
+import * as Sentry from '@sentry/react';
+
+if (import.meta.env.PROD) {
+  Sentry.init({
+    dsn: import.meta.env.VITE_SENTRY_DSN,
+    tracesSampleRate: 0.1,
+  });
+}
+
+export function reportError(err: unknown, extra?: Record<string, unknown>) {
+  if (import.meta.env.DEV) console.error('[reportError]', err, extra);
+  Sentry.captureException(err, { extra });
+}
+
+// window 级未捕获
+window.addEventListener('unhandledrejection', (e) => reportError(e.reason));
+window.addEventListener('error', (e) => reportError(e.error));
+```
+
+要点:
+
+- 所有 ErrorBoundary 的 `onError` **必须**调 `reportError`
+- mutation `onError` 在归一化 toast 之外也应调 `reportError`
+- **不要**在 component 里直接 `import * as Sentry` —— 走 `monitor.ts` 这一层包装,便于替换
+
+---
+
+## 反模式速查
+
+| 反模式 | 为什么禁 | 应该 |
+| --- | --- | --- |
+| 没有全局 ErrorBoundary | 异常直接白屏 | App 根挂一层 |
+| `useState(false)` + `useEffect` 管 loading | 重复造轮,易漏 cancel | 走 react-query / useSuspenseQuery |
+| 只判 `isLoading` 不判 `isError` | 错误态显示空白 | 三态都处理 |
+| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS | 加 Skeleton |
+| `alert('保存失败')` | 阻断用户、丑、不可样式化 | `toast.error()` |
+| ErrorBoundary 不上报 | 错过线上 bug | `onError` 接 `reportError` |
+| service 里 `try/catch` 吞错 | 上层失去判断依据 | 让 error 抛上来,hook / boundary 决定 |
+
+---
+
+## 与 ui 包的边界
+
+`@teamix-evo/ui` 提供:
+
+- `Skeleton` / `TableSkeleton` / `PageSkeleton`
+- `Toaster` + `toast()` API
+- `Spinner`(短动作)
+- `EmptyState`(无数据态,区别于错误态)
+
+**优先用 ui 包**,不要自己撸 spinner / toast。
+
+---
+
+## AI 必须输出的错误处理日志
+
+```
+## 错误 / 加载态
+
+- 全局: ✅ App 根 ErrorBoundary + reportError 已存在
+- 页面: ✅ /orders/:id 加 errorElement + Suspense fallback
+- 数据: ✅ useOrderList 三态都处理(Skeleton / ErrorPanel / Table)
+- Mutation: ✅ onSuccess toast + navigate;onError toast(已归一化)
+```