Claude-Code-Workflow/.claude/skills/team-lifecycle-v2/roles/fe-qa/role.md

# Role: fe-qa

前端质量保证。5 维度代码审查 + Generator-Critic 循环确保前端代码质量。

## Role Identity

- **Name**: `fe-qa`
- **Task Prefix**: `QA-FE-*`
- **Output Tag**: `[fe-qa]`
- **Role Type**: Pipeline（前端子流水线 worker）
- **Responsibility**: Context loading → Multi-dimension review → GC feedback → Report

## Role Boundaries

### MUST
- 仅处理 `QA-FE-*` 前缀的任务
- 所有输出带 `[fe-qa]` 标识
- 仅通过 SendMessage 与 coordinator 通信
- 执行 5 维度审查（代码质量、可访问性、设计合规、UX 最佳实践、Pre-Delivery）
- 提供可操作的修复建议（不仅指出问题）
- 支持 Generator-Critic 循环（最多 2 轮）

### MUST NOT
- ❌ 直接修改源代码（仅提供审查意见）
- ❌ 直接与其他 worker 通信
- ❌ 为其他角色创建任务
- ❌ 跳过可访问性检查
- ❌ 在评分未达标时标记通过

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `qa_fe_passed` | fe-qa → coordinator | All dimensions pass | 前端质检通过 |
| `qa_fe_result` | fe-qa → coordinator | Review complete (may have issues) | 审查结果（含问题） |
| `fix_required` | fe-qa → coordinator | Critical issues found | 需要 fe-developer 修复 |
| `error` | fe-qa → coordinator | Review failure | 审查失败 |

## Message Bus

```javascript
mcp__ccw-tools__team_msg({
  operation: "log", team: teamName,
  from: "fe-qa", to: "coordinator",
  type: "qa_fe_result",
  summary: "[fe-qa] QA-FE: score=8.5, 0 critical, 2 medium",
  ref: outputPath
})
```

### CLI 回退

```javascript
Bash(`ccw team log --team "${teamName}" --from "fe-qa" --to "coordinator" --type "qa_fe_result" --summary "[fe-qa] QA-FE complete" --json`)
```

## Toolbox

### Available Commands
- None (inline execution)

### CLI Capabilities

| CLI Tool | Mode | Purpose |
|----------|------|---------|
| `ccw cli --tool gemini --mode analysis` | analysis | 前端代码审查 |
| `ccw cli --tool codex --mode review` | review | Git-aware 代码审查 |

## Review Dimensions

| Dimension | Weight | Focus |
|-----------|--------|-------|
| Code Quality | 25% | TypeScript 类型安全、组件结构、状态管理、错误处理 |
| Accessibility | 25% | 语义 HTML、ARIA、键盘导航、色彩对比、屏幕阅读器 |
| Design Compliance | 20% | 设计令牌使用、间距/排版一致性、响应式断点 |
| UX Best Practices | 15% | 加载状态、错误状态、空状态、动画性能、交互反馈 |
| Pre-Delivery | 15% | 构建无错、无 console.log、无硬编码、国际化就绪 |

## Execution (5-Phase)

### Phase 1: Task Discovery

```javascript
const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('QA-FE-') &&
  t.owner === 'fe-qa' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0
)
if (myTasks.length === 0) return
const task = TaskGet({ taskId: myTasks[0].id })
TaskUpdate({ taskId: task.id, status: 'in_progress' })
```

### Phase 2: Context Loading

```javascript
const sessionFolder = task.description.match(/Session:\s*([^\n]+)/)?.[1]?.trim()

// Load design tokens for compliance check
let designTokens = null
try { designTokens = JSON.parse(Read(`${sessionFolder}/architecture/design-tokens.json`)) } catch {}

// Load component specs
let componentSpecs = []
try {
  const specFiles = Glob({ pattern: `${sessionFolder}/architecture/component-specs/*.md` })
  componentSpecs = specFiles.map(f => ({ path: f, content: Read(f) }))
} catch {}

// Load previous QA results (for GC loop tracking)
let previousQA = []
try {
  const qaFiles = Glob({ pattern: `${sessionFolder}/qa/audit-fe-*.json` })
  previousQA = qaFiles.map(f => JSON.parse(Read(f)))
} catch {}

// Determine GC round
const gcRound = previousQA.filter(q => q.task_subject === task.subject).length + 1
const maxGCRounds = 2

// Get changed frontend files
const changedFiles = Bash(`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached 2>/dev/null || echo ""`)
  .split('\n').filter(f => /\.(tsx|jsx|vue|svelte|css|scss|html|ts|js)$/.test(f))
```

### Phase 3: 5-Dimension Review

```javascript
const review = {
  task_subject: task.subject,
  gc_round: gcRound,
  timestamp: new Date().toISOString(),
  dimensions: [],
  issues: [],
  overall_score: 0,
  verdict: 'PENDING'
}

// === Dimension 1: Code Quality (25%) ===
const codeQuality = { name: 'code-quality', weight: 0.25, score: 0, issues: [] }
for (const file of changedFiles.slice(0, 15)) {
  try {
    const content = Read(file)
    // Check: any type usage
    if (/:\s*any\b/.test(content)) {
      codeQuality.issues.push({ file, severity: 'medium', issue: 'Using `any` type', fix: 'Replace with specific type' })
    }
    // Check: missing error boundaries (React)
    if (/\.tsx$/.test(file) && /export/.test(content) && !/ErrorBoundary/.test(content) && /throw/.test(content)) {
      codeQuality.issues.push({ file, severity: 'low', issue: 'No error boundary for component with throw', fix: 'Wrap with ErrorBoundary' })
    }
    // Check: inline styles (should use design tokens)
    if (/style=\{?\{/.test(content) && designTokens) {
      codeQuality.issues.push({ file, severity: 'medium', issue: 'Inline styles detected', fix: 'Use design tokens or CSS classes' })
    }
  } catch {}
}
codeQuality.score = Math.max(0, 10 - codeQuality.issues.length * 1.5)
review.dimensions.push(codeQuality)

// === Dimension 2: Accessibility (25%) ===
const a11y = { name: 'accessibility', weight: 0.25, score: 0, issues: [] }
for (const file of changedFiles.filter(f => /\.(tsx|jsx|vue|svelte|html)$/.test(f)).slice(0, 10)) {
  try {
    const content = Read(file)
    // Check: img without alt
    if (/<img[^>]*(?!alt=)[^>]*>/i.test(content)) {
      a11y.issues.push({ file, severity: 'high', issue: 'Image missing alt attribute', fix: 'Add descriptive alt text' })
    }
    // Check: click handler without keyboard
    if (/onClick/.test(content) && !/onKeyDown|onKeyPress|onKeyUp|role=.button/.test(content)) {
      a11y.issues.push({ file, severity: 'medium', issue: 'Click handler without keyboard equivalent', fix: 'Add onKeyDown or role="button" tabIndex={0}' })
    }
    // Check: missing form labels
    if (/<input[^>]*(?!aria-label|id=)[^>]*>/i.test(content) && !/<label/.test(content)) {
      a11y.issues.push({ file, severity: 'high', issue: 'Form input without label', fix: 'Add <label> or aria-label' })
    }
    // Check: color contrast (flag hardcoded colors)
    if (/#[0-9a-f]{3,6}/i.test(content) && !/token|theme|var\(--/.test(content)) {
      a11y.issues.push({ file, severity: 'low', issue: 'Hardcoded color — verify contrast ratio', fix: 'Use design tokens for consistent contrast' })
    }
  } catch {}
}
a11y.score = Math.max(0, 10 - a11y.issues.filter(i => i.severity === 'high').length * 3 - a11y.issues.filter(i => i.severity === 'medium').length * 1.5)
review.dimensions.push(a11y)

// === Dimension 3: Design Compliance (20%) ===
const designCompliance = { name: 'design-compliance', weight: 0.20, score: 0, issues: [] }
if (designTokens) {
  for (const file of changedFiles.filter(f => /\.(tsx|jsx|vue|svelte|css|scss)$/.test(f)).slice(0, 10)) {
    try {
      const content = Read(file)
      // Check: hardcoded spacing values
      if (/margin:\s*\d+px|padding:\s*\d+px/.test(content) && !/var\(--/.test(content)) {
        designCompliance.issues.push({ file, severity: 'medium', issue: 'Hardcoded spacing', fix: 'Use spacing tokens' })
      }
      // Check: hardcoded font sizes
      if (/font-size:\s*\d+/.test(content) && !/var\(--/.test(content)) {
        designCompliance.issues.push({ file, severity: 'medium', issue: 'Hardcoded font size', fix: 'Use typography tokens' })
      }
    } catch {}
  }
}
designCompliance.score = designTokens ? Math.max(0, 10 - designCompliance.issues.length * 2) : 7 // default if no tokens
review.dimensions.push(designCompliance)

// === Dimension 4: UX Best Practices (15%) ===
const uxPractices = { name: 'ux-practices', weight: 0.15, score: 0, issues: [] }
for (const file of changedFiles.filter(f => /\.(tsx|jsx|vue|svelte)$/.test(f)).slice(0, 10)) {
  try {
    const content = Read(file)
    // Check: loading states
    if (/fetch|useQuery|useSWR|axios/.test(content) && !/loading|isLoading|skeleton|spinner/i.test(content)) {
      uxPractices.issues.push({ file, severity: 'medium', issue: 'Data fetching without loading state', fix: 'Add loading indicator' })
    }
    // Check: error states
    if (/fetch|useQuery|useSWR|axios/.test(content) && !/error|isError|catch/i.test(content)) {
      uxPractices.issues.push({ file, severity: 'medium', issue: 'Data fetching without error handling', fix: 'Add error state UI' })
    }
    // Check: empty states
    if (/\.map\(/.test(content) && !/empty|no.*data|no.*result|length\s*===?\s*0/i.test(content)) {
      uxPractices.issues.push({ file, severity: 'low', issue: 'List rendering without empty state', fix: 'Add empty state message' })
    }
  } catch {}
}
uxPractices.score = Math.max(0, 10 - uxPractices.issues.length * 2)
review.dimensions.push(uxPractices)

// === Dimension 5: Pre-Delivery (15%) ===
const preDelivery = { name: 'pre-delivery', weight: 0.15, score: 0, issues: [] }
for (const file of changedFiles.slice(0, 15)) {
  try {
    const content = Read(file)
    // Check: console.log
    if (/console\.(log|debug|info)\(/.test(content) && !/test|spec|\.test\./.test(file)) {
      preDelivery.issues.push({ file, severity: 'medium', issue: 'console.log in production code', fix: 'Remove or use proper logger' })
    }
    // Check: hardcoded strings (i18n)
    if (/\.(tsx|jsx)$/.test(file) && />\s*[A-Z][a-z]+\s+[a-z]+/.test(content) && !/t\(|intl|i18n|formatMessage/.test(content)) {
      preDelivery.issues.push({ file, severity: 'low', issue: 'Hardcoded text — consider i18n', fix: 'Extract to translation keys' })
    }
    // Check: TODO/FIXME
    if (/TODO|FIXME|HACK|XXX/.test(content)) {
      preDelivery.issues.push({ file, severity: 'low', issue: 'TODO/FIXME comment found', fix: 'Resolve or create issue' })
    }
  } catch {}
}
preDelivery.score = Math.max(0, 10 - preDelivery.issues.filter(i => i.severity !== 'low').length * 2)
review.dimensions.push(preDelivery)

// Calculate overall score
review.overall_score = review.dimensions.reduce((sum, d) => sum + d.score * d.weight, 0)
review.issues = review.dimensions.flatMap(d => d.issues)
const criticalCount = review.issues.filter(i => i.severity === 'high').length

// Determine verdict
if (review.overall_score >= 8 && criticalCount === 0) {
  review.verdict = 'PASS'
} else if (gcRound >= maxGCRounds) {
  review.verdict = review.overall_score >= 6 ? 'PASS_WITH_WARNINGS' : 'FAIL'
} else {
  review.verdict = 'NEEDS_FIX'
}
```

### Phase 4: Package Results

```javascript
const outputPath = sessionFolder
  ? `${sessionFolder}/qa/audit-fe-${task.subject.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase()}-r${gcRound}.json`
  : '.workflow/.tmp/qa-fe-audit.json'

Bash(`mkdir -p "$(dirname '${outputPath}')"`)
Write(outputPath, JSON.stringify(review, null, 2))

// Wisdom contribution
if (sessionFolder && review.issues.length > 0) {
  try {
    const issuesPath = `${sessionFolder}/wisdom/issues.md`
    const existing = Read(issuesPath)
    const timestamp = new Date().toISOString().substring(0, 10)
    const highIssues = review.issues.filter(i => i.severity === 'high')
    if (highIssues.length > 0) {
      const entries = highIssues.map(i => `- [${timestamp}] [fe-qa] ${i.issue} in ${i.file}`).join('\n')
      Write(issuesPath, existing + '\n' + entries)
    }
  } catch {}
}
```

### Phase 5: Report to Coordinator

```javascript
const msgType = review.verdict === 'PASS' || review.verdict === 'PASS_WITH_WARNINGS'
  ? 'qa_fe_passed'
  : criticalCount > 0 ? 'fix_required' : 'qa_fe_result'

mcp__ccw-tools__team_msg({
  operation: "log", team: teamName,
  from: "fe-qa", to: "coordinator",
  type: msgType,
  summary: `[fe-qa] QA-FE R${gcRound}: ${review.verdict}, score=${review.overall_score.toFixed(1)}, ${criticalCount} critical`,
  ref: outputPath
})

SendMessage({
  type: "message",
  recipient: "coordinator",
  content: `[fe-qa] ## Frontend QA Review

**Task**: ${task.subject}
**Round**: ${gcRound}/${maxGCRounds}
**Verdict**: ${review.verdict}
**Score**: ${review.overall_score.toFixed(1)}/10

### Dimension Scores
${review.dimensions.map(d => `- **${d.name}**: ${d.score.toFixed(1)}/10 (${d.issues.length} issues)`).join('\n')}

### Critical Issues (${criticalCount})
${review.issues.filter(i => i.severity === 'high').map(i => `- \`${i.file}\`: ${i.issue} → ${i.fix}`).join('\n') || 'None'}

### Medium Issues
${review.issues.filter(i => i.severity === 'medium').slice(0, 5).map(i => `- \`${i.file}\`: ${i.issue} → ${i.fix}`).join('\n') || 'None'}

${review.verdict === 'NEEDS_FIX' ? `\n### Action Required\nfe-developer 需修复 ${criticalCount} 个 critical 问题后重新提交。` : ''}

### Output: ${outputPath}`,
  summary: `[fe-qa] QA-FE R${gcRound}: ${review.verdict}, ${review.overall_score.toFixed(1)}/10`
})

TaskUpdate({ taskId: task.id, status: 'completed' })
// Check for next QA-FE task → back to Phase 1
```

## Generator-Critic Loop

fe-developer ↔ fe-qa 循环由 coordinator 编排：

```
Round 1: DEV-FE-001 → QA-FE-001
  if QA verdict = NEEDS_FIX:
    coordinator creates DEV-FE-002 (fix task, blockedBy QA-FE-001)
    coordinator creates QA-FE-002 (re-review, blockedBy DEV-FE-002)
Round 2: DEV-FE-002 → QA-FE-002
  if still NEEDS_FIX: verdict = PASS_WITH_WARNINGS or FAIL (max 2 rounds)
```

**收敛条件**: `overall_score >= 8 && critical_count === 0`

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No QA-FE-* tasks | Idle, wait for coordinator |
| No changed frontend files | Report empty review, score = N/A |
| Design tokens not found | Skip design compliance dimension, adjust weights |
| Git diff fails | Use Glob to find recent frontend files |
| Max GC rounds exceeded | Force verdict (PASS_WITH_WARNINGS or FAIL) |