Initial commit

skills/frontend-bugfix/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: frontend-bugfix
+description: |
+  Use this skill when debugging frontend test failures (React/TypeScript, Vitest, etc.), fixing bugs in React/TypeScript code, or following TDD methodology for frontend bug fixes. This skill provides the complete bugfix workflow knowledge including error classification, confidence scoring, and TDD best practices.
+version: 2.1.0
+---
+
+# Frontend Bugfix Workflow Skill
+
+本 skill 提供前端测试 bugfix 的完整工作流知识，包括错误分类体系、置信度评分系统和 TDD 最佳实践。
+
+## 错误分类体系
+
+前端测试失败主要分为以下类型（按频率排序）：
+
+### 1. Mock 层次冲突（71%）
+
+**症状**：Mock 不生效，组件行为异常
+
+**识别特征**：
+
+- 同时存在 `vi.mock` 和 `server.use`
+- Hook 返回值与预期不符
+- API 调用未被拦截
+
+**解决策略**：选择单一 Mock 层
+
+```typescript
+// 选项 A：HTTP Mock（推荐用于集成测试）
+server.use(
+  http.get('/api/data', () => HttpResponse.json({ data: 'test' }))
+);
+
+// 选项 B：Hook Mock（用于单元测试）
+vi.mock('@/hooks/useData', () => ({
+  useData: () => ({ data: 'test', isLoading: false })
+}));
+```
+
+### 2. TypeScript 类型不匹配（15%）
+
+**症状**：类型错误、Mock 数据不完整
+
+**识别特征**：
+
+- `as any` 或类型断言
+- 缺少必需字段
+- 类型定义过时
+
+**解决策略**：使用工厂函数
+
+```typescript
+const createMockData = (overrides?: Partial<DataType>): DataType => ({
+  id: 1,
+  name: 'default',
+  ...overrides
+});
+```
+
+### 3. 异步时序问题（8%）
+
+**症状**：测试间歇性失败
+
+**识别特征**：
+
+- 缺少 `await`
+- 使用 `getBy` 而非 `findBy`
+- setTimeout 后立即断言
+
+**解决策略**：正确等待
+
+```typescript
+// Before
+render(<Component />);
+expect(screen.getByText('Loaded')).toBeInTheDocument();
+
+// After
+render(<Component />);
+expect(await screen.findByText('Loaded')).toBeInTheDocument();
+```
+
+### 4. 组件渲染问题（4%）
+
+**症状**：组件未按预期渲染
+
+**识别特征**：
+
+- 条件渲染不触发
+- 状态更新未反映
+- Props 传递错误
+
+**解决策略**：验证渲染条件和状态
+
+### 5. Hook 缓存依赖问题（2%）
+
+**症状**：Hook 返回过时数据
+
+**识别特征**：
+
+- `useEffect` 依赖数组不完整
+- `useMemo`/`useCallback` 缓存问题
+- 闭包陷阱
+
+**解决策略**：检查并修复依赖数组
+
+## 置信度评分系统
+
+### 评分标准（0-100）
+
+| 分数 | 级别 | 行为 |
+| ------ | ------ | ------ |
+| 80+ | 高 | 自动执行 |
+| 60-79 | 中 | 标记验证后继续 |
+| 40-59 | 低 | 暂停询问用户 |
+| <40 | 不确定 | 停止收集信息 |
+
+### 置信度计算
+
+```text
+置信度 = 证据质量(40%) + 模式匹配(30%) + 上下文完整性(20%) + 可复现性(10%)
+```
+
+**证据质量**：
+
+- 高：有代码行号、堆栈、可复现
+- 中：有错误信息但缺上下文
+- 低：仅有模糊描述
+
+**模式匹配**：
+
+- 高：完全匹配已知模式
+- 中：部分匹配
+- 低：未知错误类型
+
+**上下文完整性**：
+
+- 高：测试代码 + 源代码 + 配置
+- 中：只有测试或源代码
+- 低：只有错误信息
+
+**可复现性**：
+
+- 高：稳定复现
+- 中：偶发
+- 低：环境相关
+
+## TDD 流程
+
+### RED Phase（写失败测试）
+
+```typescript
+// 1. 明确期望行为
+it('should display error when API fails', async () => {
+  // 2. 设置失败场景
+  server.use(
+    http.get('/api/data', () => HttpResponse.error())
+  );
+
+  // 3. 渲染组件
+  render(<DataComponent />);
+
+  // 4. 断言期望结果
+  expect(await screen.findByText('Error loading data')).toBeInTheDocument();
+});
+```
+
+### GREEN Phase（最小实现）
+
+```typescript
+// 只写让测试通过的最小代码
+// 不要优化，不要添加额外功能
+```
+
+### REFACTOR Phase（重构）
+
+```typescript
+// 改善代码结构
+// 保持测试通过
+// 消除重复
+```
+
+## 质量门禁
+
+| 检查项 | 标准 |
+| ---------- | ------ |
+| 测试通过率 | 100% |
+| 代码覆盖率 | >= 90% |
+| 新代码覆盖率 | 100% |
+| Lint | 无错误 |
+| TypeCheck | 无错误 |
+
+## 常用命令
+
+```bash
+# 运行前端测试
+make test TARGET=frontend
+
+# 运行特定测试
+make test TARGET=frontend FILTER=ComponentName
+
+# 覆盖率检查
+make test TARGET=frontend MODE=coverage
+
+# 完整 QA
+make qa
+```
+
+## 相关文档
+
+文档路径由配置指定（`best_practices_dir`），使用以下关键词搜索：
+
+- **测试最佳实践**：关键词 "testing", "best-practices"
+- **Mock 策略**：关键词 "mock", "msw", "vi.mock"
+- **问题诊断**：关键词 "troubleshooting", "debugging"
+- **实现指南**：关键词 "implementation", "guide"