@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/localized/zh-CN/skills/fec-browser-storage/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-browser-storage
+description: 用于选择、实现或审查 localStorage、sessionStorage、IndexedDB、cookie、客户端持久化、离线数据、安全存储或清理策略等浏览器存储方案；中文触发词包括 浏览器存储、客户端持久化。
+---
+
+# 浏览器存储
+
+## 用途
+
+根据数据大小、安全要求和生命周期选择合适的客户端存储方案。
+
+## 流程
+
+1. 先判断数据敏感度、体积、生命周期、是否需要跨 Tab、是否需要随请求发送。
+2. 小量非敏感偏好用 localStorage；Tab 级临时数据用 sessionStorage；大量结构化数据或离线缓存用 IndexedDB；认证态优先 httpOnly cookie。
+3. 封装统一 key 前缀、JSON parse/stringify、异常处理、过期清理和 quota 兜底。
+4. 敏感数据按安全规则处理，不把明文 token、密码、信用卡信息放进可被 JS 读取的存储。
+5. 审查隐私模式、存储配额、清理策略和跨浏览器兼容性。
+
+## 详细参考
+
+涉及存储选型表、localStorage/sessionStorage 封装、IndexedDB 示例、Cookie 辅助方法和敏感数据规则时，加载 [references/storage-patterns.md](references/storage-patterns.md)。
+
+## 约束
+
+- localStorage/sessionStorage 是同步 API，大数据读写会阻塞主线程。
+- 除 httpOnly cookie 外，客户端存储都可被 XSS 读取。
+- Cookie 每次请求自动携带，不适合大数据。
+- IndexedDB 配额和隐私模式行为有浏览器差异。
+- URL 中不要传 token 或敏感数据。
+
+## 预期输出
+
+产出统一的 storage/cookie/db 封装，key 有命名空间，数据有过期或清理策略，敏感数据只进入合适的安全边界。

package/localized/zh-CN/skills/fec-browser-storage/references/storage-patterns.md

@@ -0,0 +1,65 @@
+# 浏览器存储模式
+
+## 选型表
+
+| 存储 | 容量 | API | 是否发送服务端 | 适用场景 | 安全性 |
+| --- | --- | --- | --- | --- | --- |
+| LocalStorage | ~5MB | 同步 | 否 | 用户偏好、非敏感持久数据 | XSS 可读取 |
+| SessionStorage | ~5MB | 同步 | 否 | Tab 级临时数据 | XSS 可读取 |
+| IndexedDB | 大 | 异步 | 否 | 大数据、文件、离线缓存 | XSS 可读取 |
+| Cookie | ~4KB | 同步 | 是 | 认证 Session/httpOnly token | httpOnly 可防 JS 读取 |
+
+## localStorage 封装
+
+```ts
+const STORAGE_PREFIX = "app:";
+
+export const storage = {
+  get<T>(key: string): T | null {
+    try {
+      const raw = localStorage.getItem(STORAGE_PREFIX + key);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  },
+  set<T>(key: string, value: T): void {
+    localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(value));
+  },
+  remove(key: string): void {
+    localStorage.removeItem(STORAGE_PREFIX + key);
+  },
+  clear(): void {
+    Object.keys(localStorage)
+      .filter((key) => key.startsWith(STORAGE_PREFIX))
+      .forEach((key) => localStorage.removeItem(key));
+  },
+};
+```
+
+## IndexedDB
+
+```ts
+import { openDB } from "idb";
+
+export const db = openDB("app-offline-db", 1, {
+  upgrade(database) {
+    if (!database.objectStoreNames.contains("requests")) {
+      database.createObjectStore("requests", { keyPath: "id" });
+    }
+  },
+});
+```
+
+## Cookie
+
+- httpOnly 只能由服务端设置。
+- 认证 Cookie 使用 `Secure`、`SameSite=Lax/Strict`。
+- 需要跨站点嵌入时才考虑 `SameSite=None; Secure`。
+
+## 敏感数据规则
+
+- 认证 token、刷新 token、Session ID：优先 httpOnly cookie。
+- 用户偏好：localStorage。
+- 表单草稿：sessionStorage 或 IndexedDB，避免敏感字段。
+- 离线数据：IndexedDB，但不要缓存隐私或高价值敏感数据。

package/localized/zh-CN/skills/fec-canvas-threejs/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fec-canvas-threejs
+description: 用于构建或审查 Canvas 2D、Three.js/WebGL、React Three Fiber、GLSL shader、ShaderToy 到 WebGL 适配、2D/3D 可视化、游戏渲染、动画循环、GPU 资源清理或渲染性能。不要用于标准 DOM UI、已有图表库覆盖的图表或非图形类性能工作；中文触发词包括 Canvas、Three.js、WebGL、GLSL、Shader、3D、数据可视化、游戏。
+---
+
+# Canvas 与 Three.js
+
+## 用途
+
+在浏览器中实现高性能 2D/3D 图形渲染。
+
+## 流程
+
+1. 先选渲染层：标准 UI 用 DOM；简单 2D 图形/签名/粒子用 Canvas 2D；3D 模型、空间交互和复杂粒子用 Three.js/WebGL；React 项目中的声明式 3D 用 React Three Fiber。
+2. 为渲染容器定义稳定尺寸、DPI 适配和 resize 行为；Canvas 不会自动随 CSS 清晰缩放。
+3. 动画循环使用 `requestAnimationFrame`，不可见或无变化时暂停，卸载时取消。
+4. Three.js 必须释放 geometry/material/texture/renderer，并移除事件监听和 observer。
+5. Shader/WebGL 任务先识别是 SDF、ray marching、noise、particle、post-processing、multipass 还是调试问题，再决定是否需要原生 WebGL2、Three.js ShaderMaterial 或 R3F。
+6. WebGL2 适配时检查 GLSL 版本、入口函数、varying/in-out、texture API、uniform 使用和函数声明顺序，避免白屏只留控制台错误。
+7. 对不可访问的图形内容提供 `aria-label`、替代文本或 DOM 版摘要；交互式图形要有键盘兜底。
+
+## 核心模式
+
+```ts
+const dpr = Math.min(window.devicePixelRatio || 1, 2);
+canvas.width = width * dpr;
+canvas.height = height * dpr;
+canvas.style.width = `${width}px`;
+canvas.style.height = `${height}px`;
+ctx.scale(dpr, dpr);
+```
+
+```ts
+let animationId = 0;
+function animate() {
+  animationId = requestAnimationFrame(animate);
+  renderer.render(scene, camera);
+}
+
+return () => {
+  cancelAnimationFrame(animationId);
+  geometry.dispose();
+  material.dispose();
+  renderer.dispose();
+};
+```
+
+## 详细参考
+
+涉及 Canvas 2D 绘图、动画循环、Three.js 场景搭建、React Three Fiber、InstancedMesh 和性能清理时，加载 [references/rendering-patterns.md](references/rendering-patterns.md)。
+
+涉及着色器路由、WebGL2 适配、GLSL 调试、多 pass 预算和视觉验证时，加载 [references/shader-webgl-patterns.md](references/shader-webgl-patterns.md)。
+
+## 约束
+
+- Canvas/WebGL 内容对屏幕阅读器不可见，必须提供替代语义。
+- WebGL 消耗 GPU，低端设备需限制像素比、面数和纹理大小。
+- Three.js 资源不会自动释放，遗漏 `dispose()` 会造成 GPU 内存泄漏。
+- Canvas 响应式必须同步 CSS 尺寸、绘图尺寸和相机/viewport。
+- 复杂布局/路径规划可联用后台线程 workflow，但渲染本身仍在主线程/渲染线程协调。
+- Shader 主循环、采样层数和多 pass 数量必须有预算；低端设备上要降低 DPR、步数、粒子数或禁用重后处理。
+- 交付前必须确认 canvas 非空、尺寸正确、resize 后不拉伸、控制台无 shader compile/link 错误。
+
+## 预期输出
+
+2D/3D 场景清晰、响应式、可清理，关键设备上接近 60fps；用户能通过替代文本或键盘路径理解/操作核心内容。

package/localized/zh-CN/skills/fec-canvas-threejs/references/rendering-patterns.md

@@ -0,0 +1,67 @@
+# Canvas、Three.js 与 R3F 模式
+
+## Canvas 2D
+
+```ts
+const canvas = document.getElementById("chart") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d");
+if (!ctx) throw new Error("Canvas 2D is unavailable");
+
+ctx.fillStyle = "#3b82f6";
+ctx.fillRect(10, 10, 50, 50);
+ctx.beginPath();
+ctx.arc(100, 100, 30, 0, Math.PI * 2);
+ctx.fill();
+```
+
+## 动画循环
+
+```ts
+let animationId = 0;
+
+function animate() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  updateParticles();
+  drawParticles(ctx);
+  animationId = requestAnimationFrame(animate);
+}
+
+animate();
+return () => cancelAnimationFrame(animationId);
+```
+
+## Three.js 基础场景
+
+```ts
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
+const geometry = new THREE.BoxGeometry(1, 1, 1);
+const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
+const cube = new THREE.Mesh(geometry, material);
+scene.add(cube);
+```
+
+## React Three Fiber
+
+```tsx
+<Canvas camera={{ position: [0, 0, 5], fov: 75 }} role="img" aria-label="3D 产品预览">
+  <ambientLight intensity={0.5} />
+  <directionalLight position={[5, 5, 5]} />
+  <mesh>
+    <boxGeometry />
+    <meshStandardMaterial color="hotpink" />
+  </mesh>
+  <OrbitControls />
+</Canvas>
+```
+
+## 性能与清理
+
+- 纹理尽量压缩并限制尺寸，常规上限先按 2048px 评估。
+- 重复几何体用 `InstancedMesh`。
+- 不需要持续重绘时暂停 animation loop。
+- 卸载时释放 geometry、material、texture、renderer、controls。
+- ResizeObserver 更新相机 aspect 和 renderer size。

package/localized/zh-CN/skills/fec-canvas-threejs/references/shader-webgl-patterns.md

@@ -0,0 +1,67 @@
+# Shader 与 WebGL 模式
+
+## 技术选型参考
+
+| 目标               | 推荐起点           | 注意事项                       |
+| ------------------ | ------------------ | ------------------------------ |
+| 数学几何 3D 形态   | SDF + 光线步进     | 步数上限、法线质量、软阴影开销 |
+| 有机运动效果       | 噪声 + 域扭曲      | 过度绘制、重复噪声调用         |
+| 粒子效果           | 实例化或着色器粒子 | 移动端粒子数量上限、混合开销   |
+| 泛光/故障/色彩调整 | 后处理通道         | 额外帧缓冲区显存               |
+| 持续模拟           | 乒乓帧缓冲区       | 纹理格式支持                   |
+| 白屏调试           | 编译/链接日志      | 函数顺序、被优化掉的 uniform   |
+
+## WebGL2 适配清单
+
+- 片元着色器以 `#version 300 es` 开头。
+- 添加 `precision highp float;` 和 `out vec4 fragColor;`。
+- 用 `in`/`out` 替代旧版 `varying`。
+- 用 `texture()` 替代 `texture2D()`。
+- 将 ShaderToy 风格的 `mainImage` 包装为标准 `main`。
+- 使用 `gl_FragCoord.xy` 获取片元坐标。
+- 辅助函数必须在被调用前声明。
+- 预计算常量，不要在宏定义中放函数调用。
+
+## 运行时骨架
+
+```ts
+const gl = canvas.getContext("webgl2");
+if (!gl) throw new Error("WebGL2 is unavailable");
+
+function compile(type: number, source: string) {
+  const shader = gl.createShader(type);
+  if (!shader) throw new Error("Cannot create shader");
+  gl.shaderSource(shader, source.trim());
+  gl.compileShader(shader);
+
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    throw new Error(gl.getShaderInfoLog(shader) ?? "Shader compile failed");
+  }
+
+  return shader;
+}
+```
+
+## 性能预算
+
+- 光线步进步数：从 64 起步，仅在出现伪影且证明必要时再提升。
+- 体积采样：桌面端每条射线 16-24 次，移动端酌情降低。
+- FBM 倍频：从 4 开始；避免在光线循环内嵌套 FBM。
+- DPR：桌面端上限 2，移动端重度场景上限 1.5。
+- 纹理尺寸：使用压缩或缩放资源；不要假设 4K 纹理是安全的。
+
+## 调试视图
+
+- 法线：输出归一化后的法线，映射到 0-1 范围。
+- 步数：输出当前步数除以最大步数。
+- 距离/深度：以灰度输出命中距离。
+- UV：映射后输出 `vec3(uv, 0.0)`。
+- 材质 ID：将 ID 映射到少量固定调色板。
+
+## 视觉验证
+
+- 桌面端和移动端尺寸下 Canvas 不为空白。
+- 缩放时更新绘制缓冲区、视口、相机纵横比和 uniform。
+- 低功耗模式下仍能响应，或有静态降级方案。
+- 控制台无着色器编译/链接错误。
+- 卸载或场景隐藏时停止动画。

package/localized/zh-CN/skills/fec-code-review/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: fec-code-review
+description: 用于用户要求通用前端代码评审、PR 评审、合并就绪评估、架构可维护性、类型安全、渲染/状态风险、样式一致性、可测性缺口或横向评审总结时。深度安全、无障碍、E2E 或性能问题应委托对应专项 skill；中文触发词包括 代码审查、代码评审、review。
+---
+
+# 前端代码评审
+
+## 用途
+
+从架构、类型安全、可访问性、样式一致性、性能和可测试性等 8 个维度审查前端代码质量，输出分级评审报告。
+
+## 流程
+
+1. 先读项目事实：package scripts、框架、目录约定、最近 diff、现有测试和相关规则。
+2. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
+3. 用五轴收敛结论：正确性、可维护性、类型/接口、用户体验、验证覆盖。
+4. 对安全、无障碍、E2E、性能等深水区只做初筛；需要专项调查时明确分流。
+5. 多维评审时先按职责拆分，再合并同类发现；同一文件同一根因只保留一条主发现，避免重复噪声。
+6. 报告先列阻塞问题，再列建议项；没有证据的问题不要写成确定结论。
+
+## 多维评审编排
+
+当改动跨越多个质量维度时，按“主评审 + 专项分流”组织，而不是让所有维度重复检查同一处代码。
+
+| 维度                | 触发条件                                             | 分流边界                             |
+| ------------------- | ---------------------------------------------------- | ------------------------------------ |
+| TypeScript 工程与类型契约 | DTO、泛型、公共类型、类型守卫、`any`、断言、tsconfig | 深入类型建模和 TS 配置交给 TypeScript 流程 |
+| 状态管理            | 状态归属、全局 store、URL 状态、派生状态、跨页面同步 | 状态选型与迁移交给状态管理专项流程   |
+| 安全                | 用户输入、HTML 渲染、token、上传、第三方脚本         | 漏洞级分析交给安全专项流程           |
+| 无障碍              | 弹窗、菜单、表单、键盘操作、焦点管理                 | WCAG 细查交给无障碍专项流程          |
+| 性能                | 大列表、重依赖、重复请求、长任务、包体积             | 性能证据与预算交给性能专项流程       |
+| E2E                 | 关键用户路径、登录态、支付、跨页面流程               | 浏览器用例与 trace 交给 E2E 专项流程 |
+
+发现合并规则：
+
+- 同一根因出现在多个维度时，只保留最高严重级别，并在 `Dimension` 中列出相关维度。
+- 同一文件多处重复模式，合并为一条模式级发现，列出代表性位置。
+- 置信度不足的问题放入 Open Questions，不升级为阻塞项。
+- 自动化可稳定捕获的格式问题交给 lint/format，不作为人工评审主发现。
+
+## 评审维度
+
+1. 架构
+
+- 组件边界是否清晰
+- 展示逻辑与业务逻辑是否分离
+- 是否有可复用抽象
+- 是否存在上帝组件
+
+2. 类型安全
+
+- 是否存在不必要的 `any`
+- props 类型是否明确
+- hooks/composables 返回值是否稳定
+- 在可行情况下 API 契约是否有类型约束
+
+3. 渲染与状态
+
+- 是否存在不必要的重复渲染
+- key 的使用是否稳定
+- 可推导状态是否被重复存储
+- 本地状态是否耦合过深
+- 全局 store 是否只保存真正跨边界共享的客户端状态
+- URL 状态、服务端状态、表单状态和浏览器持久化是否边界清晰
+
+4. 样式
+
+- 已有 Token 时是否还在使用 magic number
+- 类名是否与仓库约定一致
+- 响应式处理是否明确
+- 是否无必要地混用了多套样式体系
+
+5. 可访问性
+
+- 语义结构是否合理
+- 是否在需要时正确使用 label 和 aria
+- 是否支持键盘操作
+- 浮层和菜单的焦点管理是否正确
+
+6. 可维护性
+
+- 组件/页面文件规模是否合理（宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分，见共享 React / Vue 规则中的「组件文件规模」）
+- 命名质量是否良好
+- 是否有应该提取的重复逻辑
+- 是否存在死代码、过期注释或临时性 hack
+- 业务状态、类型、标识是否用裸数字/裸字符串（应对齐 `templates/shared/rules/fec-typescript.md`「禁止 Magic Number / Magic String」）
+
+7. 测试
+
+- 是否缺少关键测试覆盖
+- 是否存在脆弱的选择器或不稳定的测试模式
+
+8. 安全
+
+- 无明显 XSS 风险（dangerouslySetInnerHTML / v-html 必须审查）
+- 无敏感信息硬编码
+- 无未校验的用户输入直接渲染
+
+9. 性能与体验证据
+
+- 是否引入首屏重依赖、重复请求、大列表渲染或长任务
+- loading、empty、error、disabled、focus 等状态是否完整
+- 响应式布局是否有可验证断点和文本溢出保护
+
+10. 必检项（阻塞合并）
+
+- [ ] TypeScript 类型完整，无 `any`
+- [ ] 外部输入、DTO、公共类型边界无无守卫断言
+- [ ] 无 XSS 风险
+- [ ] 无敏感信息硬编码
+- [ ] 核心逻辑有单元测试
+
+11. 质量项（建议修改）
+
+- [ ] 组件文件规模符合约定（约 300 行内为佳；逾 500 行或高复杂度已拆子组件 / Hooks / Composables / utils）
+- [ ] 无重复代码（DRY 原则）
+- [ ] 无未使用的 import
+
+12. 规范项（风格建议）
+
+- [ ] 命名语义清晰
+- [ ] 注释覆盖复杂逻辑
+
+## 详细参考
+
+撰写代码评审报告时，加载 [references/report-template.md](references/report-template.md)。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。
+
+## 约束
+
+- 不把个人风格偏好写成阻塞问题；阻塞项必须有明确用户影响、运行时风险、安全风险或维护成本证据。
+- 不在缺少 diff、文件位置或复现线索时给确定结论。
+- 深度安全、无障碍、E2E 和性能问题只做初筛；需要证据链时分流到专项 skill。
+- 同一根因不要重复报多条；合并为一条代表性发现并列出影响范围。
+- 自动化工具稳定覆盖的格式问题交给 lint/format，不作为人工评审主发现。
+
+## 预期输出
+
+- 分级评审报告（CRITICAL / HIGH / MEDIUM / LOW）
+- 每个问题关联具体文件和行号，附修复建议
+- 阻塞项（CRITICAL）修复前不建议合并
+- 评审报告保存为 `reports/code-review-YYYY-MM-DD-HHmmss.md`
+- 多维评审要合并重复发现，并说明已分流到哪些专项能力
+- 对不确定项标注需要的验证命令或补充上下文，不把猜测写成事实

package/localized/zh-CN/skills/fec-code-review/references/report-template.md

@@ -0,0 +1,29 @@
+# 代码审查报告模板
+
+```markdown
+# 代码审查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## CRITICAL / 必须修改 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## HIGH / 建议优化 (N项)
+- ...
+
+## MEDIUM / 可选优化项 (N项)
+- ...
+
+## LOW / 观察项 (N项)
+- ...
+
+## 做得好的地方
+- ...
+
+## 风险等级：低 / 中 / 高
+
+**总体评价**: 可合并 / 待修改后合并 / 需要重构
+```
+
+评审完成后，将报告保存到 `reports/code-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/skills/fec-component-testing/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: fec-component-testing
+description: 用于编写或审查靠近 UI 代码的前端单元、组件或轻量集成测试，包括 React Testing Library、Vue Test Utils、hooks/composables、props/emits、回调、可访问查询、user-event 交互、mock、loading/error/empty 状态和回归覆盖。若是测试分层规划、真实浏览器旅程或现有验证失败，优先选择对应测试或验证工作流；中文触发词包括 组件测试、组件单测、单元测试、轻量集成测试。
+---
+
+# 组件测试
+
+## 用途
+
+用贴近代码和用户行为的测试验证纯逻辑、组件契约与轻量模块协作，减少重构和 UI 交互回归。
+
+## 流程
+
+### 1. 先确定测试层级
+
+- 单元测试：纯函数、hooks/composables、utils、状态逻辑、schema。
+- 组件测试：props/emits、回调、用户交互、loading/error/empty、mock 边界。
+- 轻量集成测试：表单 + API mock + Router/Store/Provider 上下文。
+
+跨页面真实浏览器流程分流到 E2E workflow；测试层选择不清楚时先做测试分层规划。
+
+### 2. 优先按用户可感知行为测试
+
+每个测试保持 Arrange / Act / Assert 清晰分段：准备数据和渲染、执行用户动作、断言用户可见结果或公开契约。
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SearchBox } from "./SearchBox";
+
+test("submits the entered keyword", async () => {
+  const user = userEvent.setup();
+  const onSearch = vi.fn();
+
+  render(<SearchBox onSearch={onSearch} />);
+
+  await user.type(screen.getByRole("searchbox", { name: /keyword/i }), "orders");
+  await user.click(screen.getByRole("button", { name: /search/i }));
+
+  expect(onSearch).toHaveBeenCalledWith("orders");
+});
+```
+
+### 3. Vue 组件使用可访问查询或明确文本断言
+
+```ts
+import { mount } from "@vue/test-utils";
+import UserMenu from "./UserMenu.vue";
+
+test("emits logout when the logout item is clicked", async () => {
+  const wrapper = mount(UserMenu, {
+    props: { userName: "Ada" },
+  });
+
+  await wrapper.get('[data-testid="logout-button"]').trigger("click");
+
+  expect(wrapper.emitted("logout")).toHaveLength(1);
+});
+```
+
+优先使用角色、标签和可见文本；仅在没有稳定语义时使用 `data-testid`。
+
+### 4. 控制 mock 边界
+
+```ts
+vi.mock("../api/users", () => ({
+  fetchUsers: vi.fn(async () => [{ id: "1", name: "Ada" }]),
+}));
+```
+
+- mock 网络、时间、路由和浏览器 API。
+- 不 mock 被测组件的内部函数。
+- 对设计系统基础组件只做轻量 mock，保留可访问行为。
+- mock 数据应表达业务场景，不使用只有测试作者能理解的随意字符串。
+- 共享 fixture 应保持可读，复杂对象用 builder 补默认值；每个测试只覆盖与场景相关的字段。
+- mock 网络时优先模拟用户可见结果和错误形状，不复制后端实现细节。
+
+### 5. 覆盖关键状态
+
+每个复杂组件至少覆盖：
+
+- 默认渲染。
+- 用户交互和回调。
+- loading / empty / error。
+- 权限或禁用态。
+- 键盘交互和焦点行为（适用时）。
+
+### 6. 保持测试可维护
+
+```ts
+function setup() {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<ProfileForm onSubmit={onSubmit} />);
+  return { user, onSubmit };
+}
+```
+
+将重复渲染逻辑放入 `setup`，但不要隐藏测试的核心操作和断言。
+
+### 7. 回归测试先证明问题
+
+- Bug 修复先写能复现失败的最小测试。
+- 失败原因应指向用户行为或公开契约，而不是导入错误、测试环境或等待方式。
+- 修复后保留回归测试，避免把验证只留在手工步骤里。
+
+## 约束
+
+- 避免测试实现细节，例如内部 state 名称、私有函数调用、DOM 层级快照。
+- 不把 snapshot 作为交互组件的主要断言；它只能辅助检查稳定静态输出。
+- 异步断言使用 `findBy*` 或 `waitFor`，不要用固定延迟。
+- 测试名称应描述用户场景，而不是函数名。
+- 组件测试不能替代 E2E；路由、真实浏览器兼容和跨页流程仍需 E2E。
+- 不在测试里复制组件实现逻辑；否则测试会和错误实现一起通过。
+- 不在测试间共享可变 fixture、全局 store 或 fake timer 状态；每个用例独立 setup 和 cleanup。
+
+## 预期输出
+
+产出与组件同目录或项目约定目录下的测试文件，覆盖核心交互、状态和回归场景。验证时运行项目现有 test 命令，确认失败信息能定位到用户行为或组件契约。

package/localized/zh-CN/skills/fec-data-fetching/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: fec-data-fetching
+description: 用于实现或审查前端服务端状态流程：类型化查询、请求缓存、失效、mutation、乐观更新、无限查询、预取、SSR hydration 或 API 层整合。不要用于本地 UI 状态或 Service Worker 缓存；中文触发词包括 数据获取、缓存、乐观更新。
+---
+
+# Server State 数据获取
+
+## 用途
+
+为前端 server state 建立清晰的数据获取、缓存、失效和提交边界，避免请求状态散落在页面组件中。
+
+## 流程
+
+1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用请求缓存方案；纯本地 UI 状态用组件 state 或 store。
+2. 先沿用项目已有数据获取库；新增依赖时 React/Vue/Solid/Svelte 可考虑 TanStack Query，也可沿用 SWR、Nuxt/Nitro 数据获取或项目封装。
+3. 设计稳定 cache key/query key：结构包含实体、动作和所有影响结果的参数。
+4. API 函数保持纯请求函数，数据 hook/composable 负责缓存、select、loading/error/empty 状态。
+5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在失败时回滚。
+
+## React 快速开始
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export function UserList({ keyword }: { keyword: string }) {
+  const query = useQuery({
+    queryKey: ["users", "list", { keyword }],
+    queryFn: () => getUserList({ keyword, page: 1, pageSize: 20 }),
+    select: (response) => response.list,
+  });
+
+  if (query.isLoading) return <Skeleton />;
+  if (query.isError) return <ErrorFallback onRetry={() => query.refetch()} />;
+  if (!query.data?.length) return <EmptyState />;
+
+  return query.data.map((user) => <UserRow key={user.id} user={user} />);
+}
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+  });
+}
+```
+
+## 详细参考
+
+涉及是否需要查询库、QueryClient 默认配置、Vue adapter、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
+
+## 约束
+
+- 相同数据必须复用相同 cache key/query key；参数缺失会造成缓存串读。
+- `staleTime` 过长会显示旧数据，过短会造成频繁请求。
+- 请求缓存库不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
+- 乐观更新必须保存快照并在失败时回滚。
+- SSR/SSG 场景必须使用框架支持的预取、水合或服务端数据边界。
+
+## 预期输出
+
+数据获取层具备 loading/error/empty/data 状态，重复请求自动去重，mutation 后缓存正确失效或回滚，API 层与 UI 层边界清晰。