@captain_z/zsk-skills 0.1.0

package/design-handoff/ue-mcp/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: zsk:ue-mcp
+description: Design Source capture & MCP readout for modules with Figma/design
+  input — Design Source (URL/node-id), MCP readout status, module-specific UE
+  deviations from system baselines, and implementation mapping. Produces
+  docs/{module}/ue-mcp.md + structured description.md snapshot in design-assets.
+  Only records deviations, not duplicated baseline rules.
+category: resource
+domain: design-handoff
+tier: optional
+related:
+  - ../figma-to-code/SKILL.md
+  - ../../frontend/a11y-web/SKILL.md
+  - ../../sdlc/spec/SKILL.md
+triggers:
+  - UE MCP context
+  - figma snapshot
+  - design source reference
+  - module UE deviation
+  - implementation mapping
+---
+
+# Supporting Template: UE / MCP
+
+> **定位**：阶段 2（Spec）和阶段 3（Design）的支撑模板 — 模块视觉/交互差异记录
+> **核心原则**：**Figma 与 SRS 是唯一事实源**。本文件只沉淀 MCP 读取事实与本模块特殊差异，不重复抄写系统级交互规范。
+> **静态资源存放**：`{{config.paths.design_assets}}/{module}/`
+> **完整 Figma → Code 方法论**：见 [`zsk:figma-to-code`](../figma-to-code/SKILL.md)
+> **系统级规范归**：`SYSTEM-SPEC.md`（UI 组件库、通用交互约定、a11y / 响应式基线 — 见 [`system/nfr-baseline`](../../system/nfr-baseline/SKILL.md) + [`frontend/a11y-web`](../../frontend/a11y-web/SKILL.md) + [`frontend/nfr-web`](../../frontend/nfr-web/SKILL.md)）
+
+## Skill 映射
+
+| 场景 | Primary Skill |
+| --- | --- |
+| 读取 Figma | `mcp__figma-mcp-go__*` 系列 MCP 工具 |
+| 视觉评审 | `plan-design-review` / `design-review` |
+| 视觉规范咨询 | `design-consultation` |
+| 系统规范研究 | `context7`（ARIA APG / WCAG 文档） |
+
+## 两类产物的边界
+
+| 产物 | 位置 | 作用 | 更新时机 |
+| --- | --- | --- | --- |
+| `docs/{module}/ue-mcp.md` | 模块目录 | **人读摘要 + 选定的 UE 契约** | 当前版本演进 |
+| `{{config.paths.design_assets}}/{module}/{snapshot}/description.md` | 静态资源目录 | **结构化快照**（所见即所得的数据） | 快照点不可变 |
+
+**分工**：ue-mcp.md 说"我们选择这样做"；description.md 说"当时 Figma 长这样"。
+
+## 为什么存在
+
+解决以下问题：
+
+- Figma / MCP 读取信息散落
+- 视觉状态无法追踪到具体设计源
+- 设计稿变更后无法快速识别受影响模块
+- MCP 会话数据仅停留在上下文而不落盘
+
+**不解决**（属系统规范职责）：
+
+- 通用交互规则（弹窗、表单、按钮、焦点环）
+- 组件库导入策略（由项目 SYSTEM-SPEC.md 约定）
+- 键盘导航通用矩阵（见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md)）
+- 响应式断点基线（见 [`frontend/nfr-web`](../../frontend/nfr-web/SKILL.md)）
+
+## 必填结构（精简版）
+
+1. **Design Source** — Figma URL / Node ID / 页面名 + **本地归档路径**
+2. **MCP Source** — 服务名 / 读取时间 / 可用性
+3. **模块特有状态** — 仅记录偏离系统基线的状态
+4. **Implementation Mapping** — UE 区域 → 实现文件
+5. **Gaps / Risks** — 缺失项与降级方案
+
+（结构化节点 / 尺寸 / token 等详细机器元数据放到 `{{config.paths.design_assets}}/{module}/{snapshot}/description.md`，不在本文件重抄）
+
+## 核心要求
+
+### 1. MCP 读取落盘
+
+- 优先通过 `.mcp.json` 声明的 MCP 服务读取
+- 无法读取时显式记录"已尝试但资源未暴露"及降级方案
+- 读取结果落到 `{{config.paths.design_assets}}/{module}/{snapshot}/`，包括：
+  - `description.md`（结构化 YAML frontmatter + 人读章节）
+  - `screenshot-*.png`（截图）
+  - `raw/mcp-response.json`（可选，`.gitignore`）
+
+### 2. 只记录"差异"，不重抄通用规范
+
+- 与系统基线一致的状态（如 `hover / focus-visible / disabled`）直接引用 `SYSTEM-SPEC.md`
+- 仅当本模块有**偏离系统基线**的状态时才展开
+
+### 3. a11y / 响应式 / 动效
+
+- 遵循系统基线（WCAG 2.1 AA、Reduced Motion — 见 `quality/a11y-principles`）
+- 仅记录本模块**偏离基线**或**超出基线**的特殊要求
+
+### 4. 与 Figma / SRS 的关系
+
+- Figma 缺字段 → SRS 补
+- SRS 与 Figma 冲突 → 记录待确认，不自行判断
+- 本文件不重新定义结构/布局/状态，只做"映射 + 读取事实 + 选定契约"
+
+## ue-mcp.md 最小模板
+
+```md
+# {模块} UE / MCP Context
+
+## 1. Design Source
+
+- Figma URL:
+- Node ID:
+- 页面 / Frame:
+- 最后确认日期:
+- **本地归档**: `{{config.paths.design_assets}}/{module}/{snapshot-name}/`
+- **结构化描述**: `{{config.paths.design_assets}}/{module}/{snapshot-name}/description.md`
+
+## 2. MCP Source
+
+- `.mcp.json` 服务名:
+- MCP 读取时间:
+- MCP 可用性:
+- 读取方式:
+
+## 3. 模块特有状态（偏离系统基线）
+
+> 系统基线状态（hover / focus-visible / disabled / selected）默认遵循 `SYSTEM-SPEC.md` 与 `quality/a11y-principles`，本节仅记录偏离或独有状态。
+
+| 状态 | 触发条件 | 偏离点 | 视觉表现 |
+| --- | --- | --- | --- |
+
+## 4. Implementation Mapping
+
+| UE 区域 | 实现文件 | 说明 |
+| --- | --- | --- |
+
+## 5. Gaps / Risks
+
+- MCP 暂不可达的资源：
+- 与 Figma 的差异：
+- 等待后端 / 设计确认项：
+```
+
+## description.md 模板（存放在 `{{config.paths.design_assets}}/{module}/{snapshot}/description.md`）
+
+```md
+---
+module_id: {module-id}
+snapshot_name: {YYYY-MM-DD}-{描述}
+figma_url: https://www.figma.com/...?node-id=...
+node_id: "<int:int>"
+page: {Figma 页面名}
+frame: {Frame 名}
+generated_at: {ISO 8601 时间}
+mcp_service: figma-mcp-go
+purpose: {本次快照的触发原因，如"Spec 冻结基线"}
+---
+
+# {模块} Figma 快照：{snapshot-name}
+
+## 节点层级
+## 布局（Auto-layout / Flex / Grid）
+## 设计 Token
+## 状态矩阵
+## 交互（如有 Figma 原型）
+## Gaps / 差异
+## 附件清单
+```
+
+## 高保真验收规则
+
+- 没有 `ue-mcp.md` + 对应 `{{config.paths.design_assets}}/{module}/` 快照，不得声称"已完成高保真还原"
+- 缺 node-id / 状态表 / 差异记录时，不得通过视觉验收
+- MCP 无法读取时必须显式记录原因和降级方案
+- a11y 矩阵未填时，不得通过可访问性验收
+
+## 质量门禁
+
+- [ ] `docs/{module}/ue-mcp.md` 存在
+- [ ] `{{config.paths.design_assets}}/{module}/{snapshot}/description.md` 存在
+- [ ] Design Source 含 URL + node-id + 确认日期 + 本地归档路径
+- [ ] MCP 读取结果已落盘（即便为空也有记录）
+- [ ] 未重抄系统级规范
+- [ ] 仅记录本模块偏离基线的状态
+- [ ] Implementation Mapping 与实际文件一致
+- [ ] Gaps / Risks 已记录

package/frontend/a11y-web/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: zsk:a11y-web
+description: React/JSX accessibility implementation — label association
+  (htmlFor/wrap), aria props usage, Modal focus trap (inert + initialFocus +
+  restoreFocus), dialog role, live regions for async, skip link, axe-core +
+  jsx-a11y toolchain, keyboard event handlers, prefers-reduced-motion.
+  Implementation layer; principles (WCAG, POUR, contrast) live in
+  quality/a11y-principles.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-components/SKILL.md
+  - ../i18n/SKILL.md
+  - ../testing-web/SKILL.md
+  - ../../quality/a11y-principles/SKILL.md
+triggers:
+  - jsx a11y
+  - focus trap
+  - Modal accessibility
+  - axe-core
+  - aria implementation
+  - skip link
+  - live region
+  - reduced motion
+  - keyboard events React
+---
+
+# a11y-web · 无障碍实现（JSX 层）
+
+> **范围**：React / JSX 的**实现细节** — label 关联 / aria 属性 / Modal 焦点陷阱 / 键盘 handler / 工具链
+> **原则层**（WCAG / POUR / 键盘矩阵 / 对比度 / Reduced Motion 原则）→ 见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md)
+> **前置**：本文件假设你已读过原则层
+
+## 1. label 关联（表单）
+
+```tsx
+// ✅ 强关联（优先）
+<label htmlFor="email">邮箱</label>
+<input id="email" type="email" />
+
+// ✅ wrap（无 id 需求时）
+<label>邮箱 <input type="email" /></label>
+```
+
+**禁用**：无关联 label / `<div>` 当 label / `placeholder` 代替 label。
+
+## 2. 命名与描述
+
+**组件命名优先级**：可见文字 > `aria-labelledby` > `aria-label`（仅图标按钮等无可见文字时）。
+
+```tsx
+<button>删除订单</button>                                    // ✅ 可见文字
+<button aria-label={t('app.order.btn.delete', '删除订单')}>  // ✅ 图标按钮
+  <IconTrash aria-hidden="true" />
+</button>
+<button aria-label="删除">删除订单</button>                  // ❌ 冲突
+```
+
+**描述**：`aria-describedby` 关联提示与错误。
+
+```tsx
+<input id="password" aria-describedby="pwd-hint pwd-error" />
+<p id="pwd-hint">至少 8 位，含字母与数字</p>
+<p id="pwd-error" role="alert">{error}</p>
+```
+
+## 3. aria 实战要点
+
+**最常用状态属性**：
+
+```tsx
+<button aria-expanded={isOpen}>展开</button>
+<li aria-selected={isSelected} role="option">...</li>
+<input aria-invalid={hasError} aria-describedby="err-1" />
+<div aria-hidden="true">{/* 装饰元素 */}</div>
+```
+
+**aria-live**（异步内容变化）：`role="status"` + `aria-live="polite"` 用于礼貌通知；`role="alert"` + `aria-live="assertive"` 仅用于紧急打断（勿滥用）。
+
+**禁用**：同时 `aria-label` + `aria-labelledby`；`aria-hidden="true"` 包可交互元素；装饰元素加 `role`。
+
+## 4. Modal / Dialog 焦点陷阱
+
+**六项硬门禁**：`role="dialog"` + `aria-modal` + `aria-labelledby` / 打开时首焦 / Tab 循环 / Esc 关闭 / 关闭时焦点回归触发按钮 / 背景 `inert`。
+
+**优先用原生 `<dialog>`**（浏览器处理 Esc、焦点陷阱、背景 inert）：
+
+```tsx
+const dialogRef = useRef<HTMLDialogElement>(null);
+const triggerRef = useRef<HTMLButtonElement>(null);
+
+const open = () => { triggerRef.current = document.activeElement as HTMLButtonElement; dialogRef.current?.showModal(); };
+const close = () => { dialogRef.current?.close(); triggerRef.current?.focus(); };
+
+<dialog ref={dialogRef} aria-labelledby="dlg-title">
+  <h2 id="dlg-title">{t('app.confirm.title', '确认')}</h2>
+</dialog>
+```
+
+自研 Modal 必须显式实现全部六项。第三方选一不混：`focus-trap-react` / `@radix-ui/react-dialog` / `react-aria` Dialog。
+
+## 5. 键盘事件 handler
+
+**优先语义元素**（`<button>` / `<a>` 天生支持 Enter / Space）。必须用非语义元素时补齐 `role + tabIndex + onKeyDown`：
+
+```tsx
+<div role="button" tabIndex={0} onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); handleClick(); }
+  }}>
+  ...
+</div>
+```
+
+**组合键位**（列表 / 树 / Select）全集见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md) 键盘矩阵；React 实现按 `switch (e.key)` 分派 Arrow / Home / End / Enter / Escape。
+
+**`:focus-visible` 样式**（禁止裸用 `outline: none`）：
+
+```less
+button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+```
+
+## 6. Skip Link、图片与图标、prefers-reduced-motion
+
+**Skip Link**：`<a href="#main" className="skip-link">...</a>` + `<main id="main" tabIndex={-1}>`；CSS 默认 `left: -9999px`，`:focus-visible` 时 `left: 0; top: 0;`。
+
+**图片 / 图标**：
+
+```tsx
+<img src="/chart.png" alt={t('app.sales.chart.alt', '2026 年销售趋势图')} />  // 信息图
+<img src="/divider.svg" alt="" />                                              // 装饰图
+<IconCheck aria-hidden="true" />                                               // 装饰图标
+<button aria-label={t('app.close', '关闭')}><IconX aria-hidden="true" /></button>  // 图标按钮
+```
+
+**prefers-reduced-motion**：CSS `@media (prefers-reduced-motion: reduce)` 将动画 / 过渡改为 `0.01ms !important`；JS 用 `window.matchMedia('(prefers-reduced-motion: reduce)').matches` 判断后降级装饰性动画。
+
+## 7. 工具链
+
+**Lint**：`eslint-plugin-jsx-a11y` 启用全套规则（`alt-text` / `label-has-associated-control` / `click-events-have-key-events` / `aria-role` / `role-has-required-aria-props` / `no-static-element-interactions` / `anchor-is-valid`），CI 零 error。
+
+**运行时**：DEV 环境动态加载 `@axe-core/react`，扫描 DOM。**硬门禁**：零 `critical` / `serious` violation。
+
+**测试**：`jest-axe` + `@axe-core/playwright` 的集成手法见 [`testing-web`](../testing-web/SKILL.md) 第 8 / 9 节（单元 + E2E axe 扫描）。
+
+**手动**：键盘跑关键流程一遍（不碰鼠标）；VoiceOver / NVDA 抽检；浏览器缩放 200% 检查布局。
+
+## 反模式（禁止）
+
+- ❌ `<div onClick>` 无键盘支持
+- ❌ `outline: none` 不补 `:focus-visible`
+- ❌ Modal 缺 role / Esc / 焦点陷阱 / 焦点回归 任一项
+- ❌ `aria-hidden="true"` 包裹可交互元素
+- ❌ `aria-label` / `alt` / `placeholder` 硬编码文案（应走 i18n）
+- ❌ 关闭 `jsx-a11y` 规则或在 CI 容忍其 warning
+
+## 质量门禁
+
+- [ ] 表单 label 关联（htmlFor / wrap）
+- [ ] 图标按钮有 `aria-label`（经 i18n）
+- [ ] Modal 六项齐全（role / aria / 初始焦点 / 循环 / Esc / 回归 / inert 背景）
+- [ ] 非语义交互元素补全 `role + tabIndex + onKeyDown`
+- [ ] `:focus-visible` 样式存在
+- [ ] `prefers-reduced-motion` 场景降级
+- [ ] `jsx-a11y` lint 零 error
+- [ ] `axe-core` 零 critical / serious violation
+- [ ] 键盘手动回归关键流程通过
+- [ ] 原则层门禁见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md)

package/frontend/api-contract-ts/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: zsk:api-contract-ts
+description: TypeScript frontend × backend API contract — never hand-write API
+  types, always consume from the shared types package or generated codegen.
+  Covers source-of-truth pattern (backend-owned types), codegen workflows
+  (OpenAPI / GraphQL / tRPC / Protobuf), breaking-change handling, version
+  discipline, runtime validation (Zod at boundary), and service-layer shape.
+  Pairs with typescript.md red lines.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../typescript/SKILL.md
+  - ../testing-web/SKILL.md
+  - ../../sdlc/spec/SKILL.md
+  - ../../sdlc/design/SKILL.md
+triggers:
+  - API type sync
+  - do not hand-write API types
+  - OpenAPI codegen
+  - GraphQL codegen
+  - tRPC types
+  - Zod runtime validation
+  - breaking API change
+  - service layer shape
+---
+
+# API Contract TS · 前后端类型契约
+
+> **范围**：TypeScript 前端**不手写** API 类型，类型来自后端单一事实源（SOT）
+> **为什么**：手写类型 = 两处事实源 → 运行时才发现不一致；机器生成的类型随后端变更立即让 `tsc` 报错
+> **配合**：[`typescript`](../typescript/SKILL.md) 红线 · [`testing-web`](../testing-web/SKILL.md) 的 MSW 契约
+
+## 1. 核心原则
+
+- **后端拥有 schema**（OpenAPI / GraphQL SDL / tRPC router / Protobuf）
+- **前端从 schema 生成类型**，不手抄
+- **运行时边界验证**（Zod / io-ts）在 service 层做一次，内部代码信任类型
+- **Service 层是唯一 HTTP 入口**，业务代码只调 service，不直接 fetch
+
+## 2. 类型来源三种模式
+
+### 模式 A：共享 npm 包（monorepo / 私服）
+
+后端 + 前端同一个 monorepo 或后端发布类型包：
+
+```ts
+// frontend/src/services/user.ts
+import type { UserResponse, UserCreateRequest } from '@company/api-types';
+
+export async function getUser(id: string): Promise<UserResponse> {
+  const res = await request.get<UserResponse>(`/api/users/${id}`);
+  return res.data;
+}
+```
+
+优点：完全同步；版本对齐靠 semver。
+
+### 模式 B：从 OpenAPI 生成（REST）
+
+```yaml
+# scripts/codegen-api.sh
+npx openapi-typescript https://api.example.com/openapi.json -o src/types/api.ts
+```
+
+```ts
+// src/types/api.ts（自动生成，不手改）
+export interface paths {
+  '/api/users/{id}': {
+    get: {
+      parameters: { path: { id: string } };
+      responses: { 200: { content: { 'application/json': components['schemas']['User'] } } };
+    };
+  };
+}
+export interface components { schemas: { User: { id: string; name: string; ... } } }
+```
+
+### 模式 C：从 GraphQL 生成
+
+```yaml
+# codegen.yml
+schema: https://api.example.com/graphql
+documents: 'src/**/*.graphql'
+generates:
+  src/types/graphql.ts:
+    plugins:
+      - typescript
+      - typescript-operations
+      - typescript-react-apollo  # 或其他 client
+```
+
+### 模式 D：tRPC（TS-to-TS 一体化）
+
+后端是 TS + tRPC 时，类型**端到端**自动：
+
+```ts
+import type { AppRouter } from '@company/server';
+import { createTRPCProxyClient, httpLink } from '@trpc/client';
+const trpc = createTRPCProxyClient<AppRouter>({ links: [httpLink({ url: '/api/trpc' })] });
+// trpc.user.getById.query('1') 完全类型安全，无 codegen 步骤
+```
+
+### 模式 E：Protobuf（gRPC-Web / Connect）
+
+```sh
+buf generate  # 按 buf.gen.yaml
+```
+
+生成 TS 客户端 + 类型。
+
+## 3. 选型决策
+
+| 后端栈 | 推荐 |
+| --- | --- |
+| Node/TS（同 monorepo） | tRPC 或共享 types 包 |
+| REST + 有 OpenAPI | `openapi-typescript` / `orval` / `openapi-fetch` |
+| GraphQL | `graphql-codegen` |
+| gRPC-Web / Connect | `buf` + `@bufbuild/protoc-gen-es` |
+| 无 schema（老后端） | **先补 schema**，不接受手写类型长期 |
+
+## 4. 禁止：手写 API 类型
+
+```ts
+// ❌ 双事实源
+type UserResponse = { id: string; name: string; email: string };
+
+async function getUser(id: string): Promise<UserResponse> { ... }
+```
+
+**问题**：后端加字段前端看不见；后端改字段类型前端还按旧的用。
+
+```ts
+// ✅ 单事实源
+import type { UserResponse } from '@company/api-types';
+// 或
+import type { components } from '@/types/api';
+type UserResponse = components['schemas']['User'];
+```
+
+## 5. Service 层封装
+
+### 职责
+
+- 唯一 HTTP 调用入口
+- 请求前 URL / 参数归一化
+- 响应后 shape 归一化（`null` ↔ `undefined`、时间字符串 → `Date` 可选）
+- **运行时边界校验**（对抗后端不守契约）
+
+### 形态（示例：REST + openapi-typescript + zod）
+
+```ts
+// src/services/user.ts
+import { z } from 'zod';
+import { request } from './request';
+import type { components } from '@/types/api';
+
+type UserFromApi = components['schemas']['User'];
+
+const UserRuntimeSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  createdAt: z.string().datetime(),
+});
+
+export type User = z.infer<typeof UserRuntimeSchema>;
+
+export async function getUser(id: string): Promise<User> {
+  const res = await request.get<UserFromApi>(`/api/users/${id}`);
+  return UserRuntimeSchema.parse(res.data); // 越界就报错
+}
+```
+
+### 运行时校验的位置
+
+- **入 service 边界**：响应解析（必做）
+- **出 service 边界**：请求参数（可选，有类型基本够了）
+- **UI 组件内部**：**不做**（内部代码信任类型系统）
+
+## 6. Breaking Change 处理
+
+### 后端声明变更
+
+- 提前 1 个 sprint 在 `CHANGELOG.md` 声明 breaking field
+- 前端 codegen 同步 → `tsc` 立即报错 → 修复或 pin 旧版本
+
+### 前端应对策略
+
+1. **版本 pin**：`package.json` 锁住 `@company/api-types@1.x.x`
+2. **迁移期共存**：新旧字段并存，UI 读新优先、fallback 旧
+3. **断舍离**：小项目 / 单用户期直接跟进
+
+### 禁止
+
+- ❌ "我先 `as any` 绕过 TS 报错，后面再补"（永远不会补）
+
+## 7. 版本与同步节奏
+
+```
+// 推荐：每次 PR 都跑一次 codegen（CI）
+- name: sync API types
+  run: npm run codegen:api
+
+- name: check no diff
+  run: git diff --exit-code src/types/api.ts
+```
+
+**门禁**：PR 合并前类型必须同步（无未提交的 codegen 差异）。
+
+## 8. 与 MSW 的契约对齐
+
+MSW handler 的返回类型也应引自生成类型，保证 mock 不漂移：
+
+```ts
+// test/handlers.ts
+import { http, HttpResponse } from 'msw';
+import type { UserResponse } from '@company/api-types';
+
+const mockUser: UserResponse = { id: '1', name: 'Alice', email: 'a@x.com', createdAt: '2026-04-19T00:00:00Z' };
+
+export const handlers = [
+  http.get('/api/users/:id', () => HttpResponse.json(mockUser)),
+];
+```
+
+后端加字段 → `UserResponse` 类型变 → MSW handler 缺字段 → 测试 TS 报错。
+
+## 9. 错误响应也要类型化
+
+```ts
+// api 定义
+type ApiError = components['schemas']['ErrorResponse']; // { code: string; message: string; details?: ... }
+
+// service
+export async function getUser(id: string): Promise<User> {
+  try {
+    const res = await request.get<UserFromApi>(`/api/users/${id}`);
+    return UserRuntimeSchema.parse(res.data);
+  } catch (err) {
+    if (axios.isAxiosError<ApiError>(err)) {
+      throw new ApiError(err.response?.data.code ?? 'UNKNOWN', err.response?.data.message ?? '');
+    }
+    throw err;
+  }
+}
+```
+
+## 10. 实际落地 checklist
+
+- [ ] 项目选定一种类型来源模式（A / B / C / D / E）
+- [ ] `package.json` / CI 有 `codegen:api` 脚本
+- [ ] Service 层是唯一 HTTP 入口
+- [ ] 响应 shape 有运行时校验（Zod / io-ts）
+- [ ] MSW handler 引用生成类型
+- [ ] 无手写的 API 响应 / 请求类型
+- [ ] 后端变更 → `tsc --noEmit` 自动报错
+
+## 反模式（禁止）
+
+- ❌ 手写 `type UserResponse = { ... }` 后调 API
+- ❌ `as any` / `as unknown as X` 绕过类型检查（见 [`typescript`](../typescript/SKILL.md)）
+- ❌ 业务组件直接 fetch（绕过 service 层）
+- ❌ Mock 数据手写 shape（应引生成类型）
+- ❌ 运行时校验放在 UI 组件（应在 service 边界）
+- ❌ "先手写类型、以后换生成"（"以后"永远不来）
+
+## 质量门禁
+
+- [ ] API 类型来自单一事实源（后端 schema）
+- [ ] Service 层有运行时边界校验
+- [ ] `codegen:api` 在 CI 上跑通 + 无未提交 diff
+- [ ] MSW mock 类型对齐
+- [ ] 无手写 API 响应类型（grep 检查）
+- [ ] 无业务代码直接 fetch（service 层统一）