lingjing-project-template/dashboard

LingJing 项目质量可视化 Dashboard

概述

这是一个完全定制化的项目质量可视化大屏，集成了 QA、进度、CI/CD、风险分析等多维度数据展示。

核心特性

• ✅ QA Score 总览 - 实时质量评分（0-100分）
• ✅ 测试结果可视化 - 通过率、失败用例 Top 10
• ✅ 覆盖率分析 - 整体覆盖率 + 模块热力图
• ✅ 趋势分析 - 最近 30 天质量趋势
• ✅ 模块质量雷达图 - 多维度模块对比
• ✅ CI/CD 状态 - dev/staging/prod 部署状态
• ✅ 风险预警 - 自动识别高风险点
• ✅ 多项目支持 - 可同时监控多个项目

技术栈

• 前端框架: Vue 3 + TypeScript
• 构建工具: Vite
• 图表库: ECharts + vue-echarts
• 样式: TailwindCSS
• 状态管理: Pinia
• 路由: Vue Router

快速开始

1. 安装依赖

cd dashboard
npm install

2. 收集质量数据

# 在项目根目录运行
python3 dashboard/collect_quality_data.py

# 数据将保存到 dashboard/public/data/quality-data.json

3. 启动开发服务器

cd dashboard
npm run dev

访问: http://localhost:5174

4. 构建生产版本

npm run build

# 构建产物在 dashboard/dist/

数据源配置

Dashboard 支持两种数据源模式：

模式 1: 本地 JSON 文件（默认）

数据文件位置：dashboard/public/data/quality-data.json

# 手动收集数据
python3 dashboard/collect_quality_data.py

# 或在 CI 中自动收集
# .gitea/workflows/ci.yml
- name: Collect Quality Data
  run: |
    python3 dashboard/collect_quality_data.py

模式 2: API 实时获取

修改 dashboard/src/api/quality.ts：

// 从 API 获取数据
export async function fetchQualityData() {
  const response = await axios.get('/api/quality/data')
  return response.data
}

Dashboard 布局

┌─────────────────────────────────────────────────────────────┐
│  LingJing 项目质量大屏                          2025-12-10  │
├──────────────┬──────────────────────────┬───────────────────┤
│              │                          │                   │
│   QA Score   │    测试结果统计          │    覆盖率         │
│     85       │  Passed: 245 Failed: 3   │     78%           │
│   优秀 🟢    │  Pass Rate: 98.8%        │  趋势: ↗          │
│              │                          │                   │
├──────────────┴──────────────────────────┴───────────────────┤
│                                                              │
│                   质量趋势图（最近 30 天）                    │
│                                                              │
├──────────────┬────────────────────────────┬─────────────────┤
│              │                            │                 │
│  模块质量    │     失败用例 Top 10        │   风险预警      │
│  雷达图      │                            │                 │
│              │  1. test_user_login()      │  🔴 3个高风险   │
│              │  2. test_payment()         │  🟡 5个中风险   │
│              │  3. ...                    │                 │
│              │                            │                 │
├──────────────┴────────────────────────────┴─────────────────┤
│                                                              │
│                 CI/CD 状态 & 部署历史                        │
│                                                              │
│  dev:      ✅ v0.3.1  (2h ago)                              │
│  staging:  ✅ v0.3.0  (1d ago)                              │
│  prod:     ✅ v0.2.5  (7d ago)                              │
│                                                              │
└──────────────────────────────────────────────────────────────┘

数据格式

quality-data.json 结构

{
  "timestamp": "2025-12-10T19:30:00+08:00",
  "project_name": "lingjing-project",
  "qa_score": {
    "score": 85.0,
    "level": "excellent",
    "color": "green",
    "components": {
      "test_pass_rate": 98.8,
      "coverage": 78.0,
      "code_quality": 80.0,
      "ci_stability": 95.0,
      "deployment_success": 100.0
    }
  },
  "test_results": {
    "total": 248,
    "passed": 245,
    "failed": 3,
    "skipped": 0,
    "pass_rate": 98.8,
    "failed_tests": [
      {
        "name": "test_user_login_invalid_password",
        "module": "backend.tests.test_auth",
        "error": "AssertionError: Expected 401, got 500"
      }
    ],
    "duration": 45.2
  },
  "coverage": {
    "total": 78.0,
    "by_module": {
      "backend": 85.0,
      "frontend": 72.0,
      "scripts": 60.0
    }
  },
  "git_metrics": {
    "total_commits": 156,
    "recent_commits": 12,
    "contributors": 3,
    "active_branches": 5
  },
  "modules": [
    {
      "name": "backend",
      "quality_score": 85.0,
      "test_coverage": 85.0,
      "lines_of_code": 5200,
      "last_modified": "2025-12-10"
    }
  ],
  "risks": [
    {
      "level": "high",
      "category": "testing",
      "description": "3 个测试失败",
      "impact": "影响交付质量"
    }
  ],
  "trends": {
    "qa_score": [
      {"date": "2025-12-01", "value": 82.0},
      {"date": "2025-12-02", "value": 83.5},
      {"date": "2025-12-10", "value": 85.0}
    ]
  }
}

主要组件

1. QAScoreCard.vue

QA 总分展示卡片，包含：

• 分数（0-100）
• 等级（优秀/良好/一般/差）
• 环形进度图
• 各维度雷达图

2. TestResultsChart.vue

测试结果统计图表：

• 通过/失败/跳过 饼图
• 通过率趋势线图
• 失败用例列表

3. CoverageChart.vue

覆盖率可视化：

• 整体覆盖率仪表盘
• 模块覆盖率热力图
• 覆盖率趋势

4. TrendChart.vue

质量趋势图：

• QA Score 趋势
• 测试通过率趋势
• 覆盖率趋势

5. ModuleRadar.vue

模块质量雷达图：

• 多维度对比（质量、覆盖率、复杂度）
• 支持多模块对比

6. RiskPanel.vue

风险预警面板：

• 高/中/低风险分级
• 风险类别标签
• 影响分析

7. DeploymentStatus.vue

部署状态展示：

• dev/staging/prod 环境
• 版本信息
• 部署时间
• 成功/失败状态

自定义配置

颜色主题

编辑 dashboard/src/utils/theme.ts：

export const theme = {
  colors: {
    primary: '#3b82f6',
    success: '#10b981',
    warning: '#f59e0b',
    danger: '#ef4444',
    // ...
  }
}

图表配置

编辑 dashboard/src/utils/chartConfig.ts：

export const chartDefaults = {
  grid: { left: '3%', right: '4%', bottom: '3%', top: '10%' },
  tooltip: { trigger: 'axis' },
  // ...
}

QA Score 计算权重

编辑 dashboard/collect_quality_data.py：

weights = {
    "test_pass_rate": 0.30,      # 测试通过率 30%
    "coverage": 0.25,             # 覆盖率 25%
    "code_quality": 0.20,         # 代码质量 20%
    "ci_stability": 0.15,         # CI 稳定性 15%
    "deployment_success": 0.10    # 部署成功率 10%
}

CI/CD 集成

Gitea CI

在 .gitea/workflows/ci.yml 中添加：

- name: Collect Quality Data
  run: |
    python3 dashboard/collect_quality_data.py

- name: Build Dashboard
  run: |
    cd dashboard
    npm install
    npm run build

- name: Deploy Dashboard
  run: |
    # 部署到静态服务器
    scp -r dashboard/dist/* user@server:/var/www/dashboard/

自动更新

添加定时任务，每小时更新一次数据：

# crontab -e
0 * * * * cd /path/to/project && python3 dashboard/collect_quality_data.py

Grafana 集成（Plan B）

如果需要使用 Grafana，请查看 grafana/README.md。

两套方案可以并存：

• Vue3 Dashboard：用于项目内部展示、客户演示
• Grafana：用于运维监控、历史数据分析

多项目支持

Dashboard 支持同时监控多个项目：

# 收集多个项目的数据
python3 dashboard/collect_quality_data.py --project-root /path/to/project1
python3 dashboard/collect_quality_data.py --project-root /path/to/project2

# 合并数据
python3 dashboard/merge_projects.py

在 Dashboard 中切换项目：

<ProjectSelector :projects="projects" @change="switchProject" />

常见问题

Q: 数据多久更新一次？

A: 默认每次打开页面时从 JSON 文件读取。可以配置自动刷新或使用 API 实时获取。

Q: 如何添加自定义指标？

A:

1. 在 collect_quality_data.py 中添加数据收集逻辑
2. 在 Dashboard 中创建对应的可视化组件
3. 更新数据格式文档

Q: 支持移动端吗？

A: 当前主要针对桌面大屏设计，移动端支持有限。可以使用响应式布局优化。

Q: 如何导出报告？

A: 可以使用浏览器打印功能导出 PDF，或者实现截图功能。

开发指南

目录结构

dashboard/
├── src/
│   ├── components/          # 可复用组件
│   │   ├── QAScoreCard.vue
│   │   ├── TestResultsChart.vue
│   │   ├── CoverageChart.vue
│   │   ├── TrendChart.vue
│   │   ├── ModuleRadar.vue
│   │   ├── RiskPanel.vue
│   │   └── DeploymentStatus.vue
│   ├── views/               # 页面视图
│   │   ├── DashboardView.vue
│   │   └── ProjectCompareView.vue
│   ├── api/                 # API 接口
│   │   └── quality.ts
│   ├── utils/               # 工具函数
│   │   ├── theme.ts
│   │   ├── chartConfig.ts
│   │   └── formatters.ts
│   ├── types/               # TypeScript 类型
│   │   └── quality.ts
│   ├── assets/              # 静态资源
│   ├── App.vue
│   └── main.ts
├── public/
│   └── data/                # 数据文件
│       ├── quality-data.json
│       └── history.json
├── collect_quality_data.py  # 数据收集脚本
├── package.json
├── vite.config.ts
├── tsconfig.json
├── tailwind.config.js
└── README.md

添加新组件

1. 创建组件文件：src/components/MyComponent.vue
2. 在主视图中引入：import MyComponent from '@/components/MyComponent.vue'
3. 添加数据类型：src/types/quality.ts
4. 更新数据收集脚本：collect_quality_data.py

调试技巧

# 生成 Mock 数据
python3 dashboard/generate_mock_data.py

# 启动开发服务器
npm run dev

# TypeScript 类型检查
npm run type-check

相关文档

• Grafana 集成方案
• Plane 状态协调系统
• 测试套件文档
• 快速入门指南

许可证

MIT License