《互联网产品的客户端架构·规模化与架构演进》10.3 无障碍测试与验收

// file: src/a11y/a11y-audit.ts
// tier: L1
// verify: node --test test/a11y/a11y-audit.test.ts

export type Severity = "blocker" | "serious" | "moderate" | "minor";

export type RuleCategory = "semantics" | "keyboard" | "screen-reader" | "visual" | "forms";

export type AuditRule = {
  id: string;
  title: string;
  severity: Severity;
  category: RuleCategory;
  wcag: string;
  manual: boolean;
};

export type Finding = { ruleId: string; node: string; detail: string };

export type ManualCheck = { id: string; label: string; required: boolean };

export type ManualResult = ManualCheck & { passed: boolean; note?: string };

export type GatePolicy = {
  maxBlocker: number;
  maxSerious: number;
  maxModerate: number;
  minCoverage: number;
  requireManual: boolean;
};

export type GateInput = { findings: Finding[]; manual: ManualResult[]; executed: string[] };

export type GateResult = { accepted: boolean; reasons: string[] };

export type AuditReport = {
  findings: Finding[];
  manual: ManualResult[];
  severityCounts: Record<Severity, number>;
  coverage: number;
  coverageMissing: string[];
  manualProgress: number;
  gate: GateResult;
};

export const RULES: AuditRule[] = [
  { id: "name-required", title: "交互控件必须有可访问名称", severity: "blocker", category: "semantics", wcag: "4.1.2", manual: false },
  { id: "role-valid", title: "角色与属性必须匹配", severity: "serious", category: "semantics", wcag: "4.1.2", manual: false },
  { id: "heading-order", title: "标题层级不得跳级", severity: "moderate", category: "semantics", wcag: "1.3.1", manual: false },
  { id: "focus-order", title: "焦点顺序与视觉顺序一致", severity: "serious", category: "keyboard", wcag: "2.4.3", manual: false },
  { id: "focus-trap", title: "不得存在无法退出的焦点陷阱", severity: "blocker", category: "keyboard", wcag: "2.1.2", manual: false },
  { id: "keyboard-all", title: "所有功能可用键盘完成", severity: "blocker", category: "keyboard", wcag: "2.1.1", manual: true },
  { id: "focus-visible", title: "焦点必须可见", severity: "serious", category: "visual", wcag: "2.4.7", manual: true },
  { id: "contrast-text", title: "正文对比度不低于 4.5:1", severity: "serious", category: "visual", wcag: "1.4.3", manual: false },
  { id: "reflow-320", title: "320px 宽度下内容不横向滚动", severity: "moderate", category: "visual", wcag: "1.4.10", manual: false },
  { id: "text-spacing", title: "文本间距可调整", severity: "moderate", category: "visual", wcag: "1.4.12", manual: false },
  { id: "form-label", title: "表单控件必须有关联标签", severity: "serious", category: "forms", wcag: "3.3.2", manual: false },
  { id: "error-suggestion", title: "错误提示必须说明如何修正", severity: "moderate", category: "forms", wcag: "3.3.3", manual: false },
  { id: "status-message", title: "状态变化必须被读屏播报", severity: "serious", category: "screen-reader", wcag: "4.1.3", manual: false },
  { id: "sr-flow", title: "读屏可完整走通主流程", severity: "blocker", category: "screen-reader", wcag: "4.1.3", manual: true },
  { id: "motion-reduce", title: "减少动效偏好必须生效", severity: "moderate", category: "visual", wcag: "2.3.3", manual: true },
];

export const MANUAL_CHECKS: ManualCheck[] = [
  { id: "m-keyboard", label: "仅用键盘完成一次下单或提交", required: true },
  { id: "m-focus", label: "逐项检查焦点可见且顺序可预测", required: true },
  { id: "m-reader", label: "用读屏软件走通主流程并记录障碍", required: true },
  { id: "m-zoom", label: "200% 缩放后内容不丢失", required: true },
  { id: "m-reflow", label: "320px 视口下完成核心任务", required: false },
  { id: "m-motion", label: "开启减少动效后动画停止", required: true },
  { id: "m-error", label: "表单错误可被读屏定位并说明修正方式", required: true },
  { id: "m-captions", label: "视频有字幕且可关闭", required: false },
];

export const DEFAULT_POLICY: GatePolicy = {
  maxBlocker: 0,
  maxSerious: 0,
  maxModerate: 3,
  minCoverage: 0.8,
  requireManual: true,
};

export function severityRank(severity: Severity): number {
  switch (severity) {
    case "blocker": return 4;
    case "serious": return 3;
    case "moderate": return 2;
    case "minor": return 1;
  }
}

export function ruleById(id: string): AuditRule | undefined {
  return RULES.find((rule) => rule.id === id);
}

export function automatedRules(): AuditRule[] {
  return RULES.filter((rule) => !rule.manual);
}

export function unknownRuleIds(findings: Finding[]): string[] {
  return [...new Set(
    findings.filter((finding) => ruleById(finding.ruleId) === undefined)
      .map((finding) => finding.ruleId),
  )].sort();
}

function findingRank(finding: Finding): number {
  const rule = ruleById(finding.ruleId);
  return rule ? severityRank(rule.severity) : 5;
}

export function normalizeFindings(findings: Finding[]): Finding[] {
  const seen = new Set<string>();
  const kept: Finding[] = [];
  for (const finding of findings) {
    const key = `${finding.ruleId}::${finding.node}`;
    if (seen.has(key)) continue;
    seen.add(key);
    kept.push(finding);
  }
  return kept.sort(
    (a, b) => findingRank(b) - findingRank(a)
      || a.ruleId.localeCompare(b.ruleId)
      || a.node.localeCompare(b.node),
  );
}

export function countBySeverity(findings: Finding[]): Record<Severity, number> {
  const out: Record<Severity, number> = { blocker: 0, serious: 0, moderate: 0, minor: 0 };
  for (const finding of findings) {
    const rule = ruleById(finding.ruleId);
    if (rule) out[rule.severity] += 1;
  }
  return out;
}

export function coverageMissing(executed: string[]): string[] {
  const done = new Set(executed);
  return automatedRules().filter((rule) => !done.has(rule.id)).map((rule) => rule.id);
}

export function coverageScore(executed: string[]): number {
  const rules = automatedRules();
  if (rules.length === 0) return 1;
  const done = new Set(executed);
  let total = 0;
  let covered = 0;
  for (const rule of rules) {
    const weight = severityRank(rule.severity);
    total += weight;
    if (done.has(rule.id)) covered += weight;
  }
  return Math.round((covered / total) * 1000) / 1000;
}

export function manualProgress(results: ManualResult[]): number {
  if (results.length === 0) return 0;
  const passed = results.filter((result) => result.passed).length;
  return Math.round((passed / results.length) * 1000) / 1000;
}

export function evaluateGate(input: GateInput, policy: GatePolicy = DEFAULT_POLICY): GateResult {
  const reasons: string[] = [];
  const unknown = unknownRuleIds(input.findings);
  if (unknown.length > 0) reasons.push(`发现未登记规则：${unknown.join(", ")}`);
  const counts = countBySeverity(input.findings);
  if (counts.blocker > policy.maxBlocker) {
    reasons.push(`阻断级问题 ${counts.blocker} 个，上限 ${policy.maxBlocker}`);
  }
  if (counts.serious > policy.maxSerious) {
    reasons.push(`严重问题 ${counts.serious} 个，上限 ${policy.maxSerious}`);
  }
  if (counts.moderate > policy.maxModerate) {
    reasons.push(`中等问题 ${counts.moderate} 个，上限 ${policy.maxModerate}`);
  }
  const coverage = coverageScore(input.executed);
  if (coverage < policy.minCoverage) {
    reasons.push(`规则覆盖度 ${(coverage * 100).toFixed(1)}%，低于 ${(policy.minCoverage * 100).toFixed(0)}%`);
  }
  if (policy.requireManual) {
    const failed = input.manual
      .filter((item) => item.required && !item.passed)
      .map((item) => item.label);
    if (failed.length > 0) reasons.push(`必做人工检查未通过：${failed.join("；")}`);
  }
  return { accepted: reasons.length === 0, reasons };
}

export function buildReport(input: GateInput, policy: GatePolicy = DEFAULT_POLICY): AuditReport {
  const findings = normalizeFindings(input.findings);
  return {
    findings,
    manual: input.manual,
    severityCounts: countBySeverity(findings),
    coverage: coverageScore(input.executed),
    coverageMissing: coverageMissing(input.executed),
    manualProgress: manualProgress(input.manual),
    gate: evaluateGate({ findings, manual: input.manual, executed: input.executed }, policy),
  };
}

export function topFindings(findings: Finding[], limit = 5): Finding[] {
  return normalizeFindings(findings).slice(0, Math.max(0, limit));
}

✔ 规则 id 唯一 (0.596291ms)
✔ 每条规则都带 WCAG 编号 (0.17325ms)
✔ 规则集区分自动规则与人工规则 (0.065542ms)
✔ 严重级别可以排序 (0.094375ms)
✔ 未知规则返回 undefined (0.074875ms)
✔ 同一规则同一节点只保留一条发现 (7.928083ms)
✔ 发现按严重级别从高到低排序 (0.443959ms)
✔ 未登记规则被单独列出 (0.073209ms)
✔ 按严重级别统计发现 (0.086708ms)
✔ 全部自动规则执行时覆盖度为 1 (0.154333ms)
✔ 覆盖度按严重级别加权，而不是简单计数 (0.063708ms)
✔ 未执行的自动规则出现在缺失清单里 (0.055458ms)
✔ 人工规则不参与自动覆盖度计算 (0.065042ms)
✔ 人工检查通过率按条目计算 (0.062916ms)
✔ 没有任何人工检查结果时通过率为零 (0.0485ms)
✔ 干净报告可以通过默认验收门槛 (0.1315ms)
✔ 存在阻断级问题时验收失败 (0.065458ms)
✔ 覆盖度低于门槛时验收失败 (0.056709ms)
✔ 必做人工检查未通过时验收失败 (0.058084ms)
✔ 非必做人工检查失败不影响验收 (0.044459ms)
✔ 未登记规则会直接导致验收失败 (0.04475ms)
✔ 构建报告汇总发现、覆盖度与门槛结论 (0.077333ms)
✔ 报告沿用自定义门槛 (0.04675ms)
✔ topFindings 按严重级别返回前若干条 (0.0565ms)
ℹ tests 24
ℹ suites 0
ℹ pass 24
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 138.820083