# 质量门禁仪表板指南 > **[EN](../../guides/quality-dashboard.md)** | [PT](../../pt/guides/quality-dashboard.md) | [ES](../../es/guides/quality-dashboard.md) | **中文 (ZH)** --- > 用于监控所有3层质量指标的可视化仪表板。 **版本:** 1.0 **最后更新:** 2025-12-05 --- ## 概述 质量门禁仪表板提供从所有三个质量门禁层收集的质量指标的实时可视化。它帮助技术主管和开发人员监控代码质量趋势、识别问题并跟踪质量门禁系统的有效性。 ### 关键功能 | 功能 | 描述 | | --------------------- | --------------------------------------------------- | | **3层指标** | 查看预提交、PR审查和人工审查的通过率 | | **趋势图表** | 跟踪过去30天的自动捕获率 | | **实时更新** | 每60秒自动刷新 | | **响应式设计** | 适配桌面、平板和移动设备 | | **无障碍访问** | 符合WCAG 2.1 AA标准 | | **深色模式** | 根据系统偏好自动切换 | --- ## 访问仪表板 ### 开发模式 ```bash # 导航到仪表板目录 cd tools/quality-dashboard # 同步指标并启动开发服务器 npm run dev:sync # 或单独同步 npm run sync-metrics npm run dev ``` 仪表板将在 `http://localhost:3000` 打开。 ### 生产构建 ```bash # 生产构建 cd tools/quality-dashboard npm run build # 预览生产构建 npm run preview # 从dist/目录提供服务 npx serve dist ``` ### 直接文件访问 打开预构建的仪表板: ``` tools/quality-dashboard/dist/index.html ``` --- ## 理解仪表板 ### 页头部分 ``` ┌─────────────────────────────────────────────────────────┐ │ 📊 质量门禁仪表板 │ │ 最后更新: 2025年12月5日 14:30:00 │ │ [🔄 刷新] [自动刷新: 60秒 ▼] │ └─────────────────────────────────────────────────────────┘ ``` | 元素 | 描述 | | ------------------ | ----------------------------------------- | | **最后更新** | 最近数据获取的时间戳 | | **刷新按钮** | 无需重新加载页面的手动刷新 | | **自动刷新** | 可配置的间隔（30秒、60秒、5分钟、关闭） | ### 层级卡片 每个质量门禁层都有自己的指标卡: ``` ┌─────────────────────────────────────────────────────────┐ │ 层级1: 预提交 ● 正常 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 通过率: 94.5% 平均时间: 32秒 总运行: 156 │ │ ████████████████░░ │ │ │ │ [点击展开] │ └─────────────────────────────────────────────────────────┘ ``` #### 层级1: 预提交 | 指标 | 描述 | | -------------- | ------------------------------------------------------- | | **通过率** | 通过所有检查的提交百分比（lint、test、typecheck） | | **平均时间** | 完成所有层级1检查的平均时间 | | **总运行数** | 时间段内预提交运行的数量 | #### 层级2: PR审查 | 指标 | 描述 | | ----------------------- | ---------------------------------------- | | **通过率** | 通过自动审查的PR百分比 | | **CodeRabbit发现** | CodeRabbit发现的问题（按严重程度） | | **Quinn发现** | @qa代理发现的问题 | | **自动捕获率** | 人工审查前捕获的问题百分比 | **展开视图（点击展开）:** ``` ┌─────────────────────────────────────────────────────────┐ │ 层级2: PR审查 ● 警告 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 通过率: 87.2% 平均时间: 4分 32秒 总计: 45个PR │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ CodeRabbit分布 │ │ │ │ 严重: 3 │ 高: 12 │ 中: 28 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Quinn (@qa) 发现 │ │ │ │ 阻碍: 2 │ 警告: 8 │ 信息: 15 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ ``` #### 层级3: 人工审查 | 指标 | 描述 | | ----------------- | ----------------------------------------- | | **通过率** | 首次审查就被批准的PR百分比 | | **平均时间** | 从PR创建到批准的平均时间 | | **修订率** | 需要修订的PR百分比 | ### 趋势图表 趋势图显示过去30天的自动捕获率: ``` 自动捕获率趋势 (30天) 100% ┤ 90% ┤ ╭──────────╮ 80% ┤ ╭────╯ ╰────╮ 70% ┤───╯ ╰─── 60% ┤ └──────────────────────────── 第1周 第2周 第3周 第4周 ``` **自动捕获率** = (层级1 + 层级2捕获的问题) / 总问题数 越高越好 - 说明在人工审查前捕获了更多问题。 --- ## 指标数据源 ### 位置 指标存储在: ``` .aiox/data/quality-metrics.json ``` ### 数据格式 ```json { "generated": "2025-12-05T14:30:00.000Z", "version": "1.0", "summary": { "overallHealth": "healthy", "autoCatchRate": 0.945, "totalRuns": 156 }, "layers": { "layer1": { "name": "预提交", "passRate": 0.945, "avgTimeSeconds": 32, "totalRuns": 156, "checks": { "lint": { "passRate": 0.98, "avgTime": 12 }, "test": { "passRate": 0.95, "avgTime": 45 }, "typecheck": { "passRate": 0.99, "avgTime": 28 } } }, "layer2": { "name": "PR审查", "passRate": 0.872, "avgTimeSeconds": 272, "totalRuns": 45, "coderabbit": { "critical": 3, "high": 12, "medium": 28, "low": 45 }, "quinn": { "blockers": 2, "warnings": 8, "info": 15 } }, "layer3": { "name": "人工审查", "passRate": 0.78, "avgTimeSeconds": 86400, "totalRuns": 38, "revisionRate": 0.22 } }, "trends": { "autoCatchRate": [ { "date": "2025-11-05", "value": 0.82 }, { "date": "2025-11-12", "value": 0.87 }, { "date": "2025-11-19", "value": 0.91 }, { "date": "2025-11-26", "value": 0.93 }, { "date": "2025-12-03", "value": 0.945 } ] } } ``` ### 同步指标 仪表板从公共文件夹读取指标。要更新: ```bash # 从.aiox/data同步到仪表板 npm run sync-metrics # 或使用组合命令 npm run dev:sync ``` 这会复制 `.aiox/data/quality-metrics.json` 到 `tools/quality-dashboard/public/.aiox/data/`。 --- ## 解释趋势 ### 健康的趋势 | 指标 | 含义 | | -------------------------------- | -------------------------------------------------------- | | **自动捕获率上升** | 自动捕获的问题增多 - 质量门禁有效运作 | | **层级3修订率下降** | 人工审查发现的问题减少 | | **稳定的通过率 > 90%** | 开发人员前期编写代码质量更好 | ### 警告信号 | 指标 | 含义 | 行动 | | ------------------------------- | -------------------------------- | ------------------------ | | **自动捕获率下降** | 自动化检查遗漏问题 | 查看CodeRabbit配置 | | **层级1通过率 < 80%** | 过多提交失败 | 检查lint/test规则 | | **层级2有很多严重问题** | 安全/质量问题 | 查看代码实践 | | **层级3修订率 > 30%** | 人工审查发现很多问题 | 改进自动化 | --- ## 配置 ### 自动刷新间隔 点击刷新按钮旁的下拉菜单: | 选项 | 用例 | | -------------- | --------------------------------- | | **30秒** | 发布期间的主动监控 | | **60秒** | 日常使用的默认选项 | | **5分钟** | 后台监控 | | **关闭** | 仅手动刷新 | ### 深色模式 仪表板自动遵循您的系统偏好。无需手动切换。 --- ## 无障碍访问 仪表板符合WCAG 2.1 AA标准: | 功能 | 实现 | | ----------------------- | ----------------------------------------- | | **颜色对比度** | 所有文本最少4.5:1对比度比例 | | **键盘导航** | 完整键盘支持和可见焦点 | | **屏幕阅读器** | 所有交互元素上的ARIA标签 | | **减少运动** | 遵守 `prefers-reduced-motion` | | **焦点管理** | 整个页面的逻辑制表序列 | --- ## 故障排除 ### 仪表板显示过期数据 ```bash # 手动同步指标 cd tools/quality-dashboard npm run sync-metrics # 刷新页面 ``` ### 找不到指标文件 确保指标收集器已运行: ```bash # 检查指标文件是否存在 ls -la .aiox/data/quality-metrics.json # 如果缺失，用示例数据初始化 npx aiox metrics seed ``` ### 图表未呈现 1. 清除浏览器缓存 2. 确保JavaScript已启用 3. 尝试使用不同浏览器 ### 自动刷新不工作 自动刷新在以下情况下会暂停: - 浏览器标签在后台 - 网络连接丢失 - 焦点在交互元素上 --- ## 相关文档 - [质量门禁指南](./quality-gates.md) --- _Synkra AIOX质量门禁仪表板 v1.0_