analytics-flow

analytics-flow

描述：项目指标、文档分析、进度跟踪和趋势分析

类别：数据分析与报告

复杂度：中等（数据聚合 + 可视化）

---

目的

让项目进度、文档质量、需求覆盖率和开发速度一目了然。从 SDD 工件中生成可执行的洞察，以识别瓶颈并优化工作流。

---

功能

1. 文档覆盖率指标

• 按类型统计文档总数（BRD、PRD、REQ、BDD 等）
• Token 数量分布
• 文档完整度百分比
• 识别过时文档
• 跟踪文档债务

2. 需求跟踪

• 按类别统计需求总数
• 需求状态（草稿、已批准、已实现、已测试）
• 需求覆盖率（REQ → BDD → TASK 映射）
• 孤立需求
• 需求时长和陈旧度

3. 可追溯性分析

• 完整的可追溯链（BRD → ... → 代码）
• 已断开的可追溯链接
• 可追溯性覆盖率百分比
• 识别缺口
• 检测循环依赖

4. 实现进度

• 已完成任务数与任务总数
• 实现阶段进度
• 受阻与进行中的任务
• 时间线执行情况
• 里程碑跟踪

5. 速度跟踪

• 每个冲刺/每周完成的需求数
• 实现速度
• 文档编写速度
• 测试覆盖率增长速度
• 随时间变化的趋势分析

6. 质量指标

• 代码审查评分随时间的变化
• 测试覆盖率趋势
• 安全漏洞趋势
• 代码复杂度趋势
• 文档质量评分

7. 瓶颈识别

• 停滞的需求（没有进展）
• 受阻任务
• 资源限制
• 阻碍进展的依赖链
• 审查瓶颈

8. 自定义报告生成

• 执行摘要
• 冲刺/每周报告
• 里程碑报告
• 团队绩效报告
• 风险评估报告

---

分析工作流

graph TD
    A[SDD Artifacts] --> B[Data Collection]
    B --> C[Parse Documents]
    C --> D[Extract Metadata]

    D --> E[Requirement Analysis]
    D --> F[Traceability Analysis]
    D --> G[Progress Analysis]
    D --> H[Quality Analysis]

    E --> I[Requirement Metrics]
    F --> J[Traceability Matrix]
    G --> K[Progress Dashboard]
    H --> L[Quality Dashboard]

    I --> M[Aggregate Data]
    J --> M
    K --> M
    L --> M

    M --> N[Calculate KPIs]
    N --> O[Identify Trends]
    O --> P[Detect Anomalies]
    P --> Q[Generate Insights]

    Q --> R{Report Type}
    R -->|Executive| S[Executive Summary]
    R -->|Technical| T[Technical Report]
    R -->|Sprint| U[Sprint Report]

    S --> V[Distribute Reports]
    T --> V
    U --> V

---

使用说明

生成项目仪表板

analytics-flow dashboard --output reports/dashboard.html

生成的仪表板版块：

Project Overview Dashboard
==========================

Overall Health: 78/100 (Good)

Documentation Coverage:
├─ BRD Documents: 3/3 (100%) ✓
├─ PRD Documents: 2/3 (67%) ⚠️
├─ Requirements: 146/150 (97%) ✓
├─ BDD Scenarios: 89/146 (61%) ⚠️
├─ ADR Documents: 12/12 (100%) ✓
├─ SPEC Documents: 5/8 (63%) ⚠️
└─ TASK Documents: 45/89 (51%) ❌

Implementation Progress:
├─ Phase 1: 100% (Completed) ✓
├─ Phase 2: 75% (In Progress) →
├─ Phase 3: 0% (Not Started) ○
└─ Overall: 58% complete

Traceability Coverage:
├─ Forward Traceability: 94% ✓
├─ Backward Traceability: 91% ✓
└─ Complete Chains: 87% ✓

Quality Metrics:
├─ Code Coverage: 87% ✓
├─ Code Review Score: 82/100 ✓
├─ Security Issues: 3 (1 Critical) ⚠️
└─ Documentation Quality: 89% ✓

Velocity (Last 4 Weeks):
├─ Requirements: 12/week (avg)
├─ Implementation: 8 tasks/week
├─ Tests Written: 45 tests/week
└─ Trend: ↗ Improving

Bottlenecks Identified:
├─ REQ-AUTH-015: Stuck for 3 weeks
├─ BDD Scenarios: 39% gap vs requirements
└─ Phase 2 Dependency: Blocked by external API

生成需求报告

analytics-flow requirements --format json --output reports/requirements.json

输出：

{
  "summary": {
    "total_requirements": 146,
    "by_priority": {
      "MUST": 130,
      "SHOULD": 12,
      "MAY": 4
    },
    "by_status": {
      "draft": 5,
      "approved": 85,
      "implemented": 45,
      "tested": 38,
      "deployed": 30
    },
    "by_category": {
      "authentication": 15,
      "authorization": 12,
      "data_processing": 45,
      "api": 38,
      "ml_models": 32,
      "infrastructure": 4
    }
  },
  "coverage": {
    "with_bdd_scenarios": 89,
    "with_tasks": 78,
    "with_tests": 67,
    "complete_traceability": 127
  },
  "age_analysis": {
    "average_age_days": 45,
    "oldest_requirement": {
      "id": "REQ-AUTH-01",
      "age_days": 120,
      "status": "implemented"
    },
    "stale_requirements": [
      {"id": "REQ-ML-015", "age_days": 90, "status": "draft"}
    ]
  },
  "orphaned_requirements": [
    "REQ-AUTH-015",
    "REQ-DATA-023"
  ]
}

生成可追溯性矩阵

analytics-flow traceability --format mermaid --output reports/traceability.mmd

生成的 Mermaid 图表：

graph LR
    BRD001[BRD-SYSTEM-001] --> PRD001[PRD-FEATURES-001]
    PRD001 --> REQ001[REQ-AUTH-01]
    PRD001 --> REQ002[REQ-AUTH-002]

    REQ001 --> BDD001[BDD-LOGIN-001]
    REQ001 --> BDD002[BDD-LOGIN-002]
    REQ002 --> BDD003[BDD-LOGOUT-001]

    BDD001 --> TASK001[TASK-AUTH-001]
    BDD002 --> TASK002[TASK-AUTH-002]
    BDD003 --> TASK003[TASK-AUTH-003]

    TASK001 --> CODE001[auth/login.py]
    TASK002 --> CODE001
    TASK003 --> CODE002[auth/logout.py]

    CODE001 --> TEST001[test_login.py]
    CODE002 --> TEST002[test_logout.py]

    style BRD001 fill:#e1f5ff
    style PRD001 fill:#e8f5e9
    style REQ001 fill:#fff3e0
    style REQ002 fill:#fff3e0
    style BDD001 fill:#f3e5f5
    style BDD002 fill:#f3e5f5
    style BDD003 fill:#f3e5f5

生成冲刺报告

analytics-flow sprint \
  --start-date 2025-01-01 \
  --end-date 2025-01-14 \
  --output reports/sprint-report.md

生成的报告：

# Sprint Report: Jan 1-14, 2025

## Sprint Summary
- Duration: 2 weeks
- Team Size: 5 developers
- Sprint Goal: Complete Phase 2 authentication features

## Accomplishments
✓ Completed: 12 requirements
✓ Implemented: 18 tasks
✓ Tests Written: 67 tests
✓ Code Coverage: 87% → 91% (+4%)

## Requirements Completed
1. REQ-AUTH-01: User login with JWT ✓
2. REQ-AUTH-002: User logout ✓
3. REQ-AUTH-003: Password reset ✓
4. REQ-AUTH-004: Email verification ✓
... (8 more)

## Velocity Metrics
- Requirements: 6/week (target: 5/week) ↗
- Tasks: 9/week (target: 8/week) ↗
- Tests: 33.5/week (target: 25/week) ↗

## Quality Metrics
- Code Review Score: 85/100 (+3 from last sprint)
- Security Issues: 2 (down from 5)
- Test Coverage: 91% (up from 87%)

## Blockers Resolved
1. External API integration (blocked 5 days) → Resolved
2. Database migration issue → Resolved

## Current Blockers
1. Waiting for design review on user profile page (2 days)

## Risks
⚠️ Phase 3 dependency on external service (mitigation: mock implementation)

## Next Sprint Goals
- Complete remaining 8 authentication requirements
- Begin authorization framework
- Improve test coverage to 93%

跟踪速度趋势

analytics-flow velocity --weeks 12 --output reports/velocity.json

包含趋势分析的输出：

{
  "period": "12 weeks",
  "metrics": [
    {
      "week": "2025-W01",
      "requirements_completed": 8,
      "tasks_completed": 15,
      "tests_written": 42,
      "code_coverage": 85
    },
    {
      "week": "2025-W02",
      "requirements_completed": 12,
      "tasks_completed": 18,
      "tests_written": 67,
      "code_coverage": 91
    }
  ],
  "trends": {
    "requirements": {
      "average": 10,
      "trend": "increasing",
      "velocity_change": "+15%"
    },
    "tasks": {
      "average": 16.5,
      "trend": "stable",
      "velocity_change": "+2%"
    },
    "tests": {
      "average": 54.5,
      "trend": "increasing",
      "velocity_change": "+25%"
    }
  },
  "forecast": {
    "next_sprint_requirements": 13,
    "completion_date_phase_2": "2025-02-15",
    "confidence": "high"
  }
}

---

关键绩效指标（KPI）

文档 KPI

1. 文档覆盖率

   Coverage = (Completed Documents / Total Required Documents) × 100%
   Target: ≥95%
   

2. 文档债务

   Debt = Outdated Documents + Missing Documents
   Target: <5% of total documents
   

3. 文档平均年龄

   Age = Days since last update
   Target: <30 days for active documents
   

需求 KPI

1. 需求覆盖率

   Coverage = (Requirements with Tests / Total Requirements) × 100%
   Target: 100% for MUST requirements
   

2. 需求周期时间

   Cycle Time = Days from draft to deployed
   Target: <14 days (2 sprints)
   

3. 孤立需求

   Orphaned = Requirements without forward/backward links
   Target: 0
   

实现 KPI

1. 实现速度

   Velocity = Tasks completed / Time period
   Track: Weekly, calculate 4-week moving average
   

2. 任务完成率

   Completion = (Completed Tasks / Total Tasks) × 100%
   Target: ≥90% per sprint
   

3. 受阻任务百分比

   Blocked % = (Blocked Tasks / Active Tasks) × 100%
   Target: <10%
   

可追溯性 KPI

1. 正向可追溯性

   Forward = (Requirements with downstream links / Total Requirements) × 100%
   Target: 100%
   

2. 反向可追溯性

   Backward = (Tasks with upstream links / Total Tasks) × 100%
   Target: 100%
   

3. 完整可追溯链

   Complete = (Requirements with full BRD→Code chain / Total) × 100%
   Target: ≥95%
   

质量 KPI

1. 代码覆盖率趋势

   Track: Weekly, target: ≥90%
   Alert: If drops >5% week-over-week
   

2. 代码审查评分

   Track: Per PR, target: ≥80/100
   Alert: If average <70 for 2 consecutive weeks
   

3. 安全漏洞密度

   Density = Critical vulnerabilities / KLOC
   Target: 0 critical vulnerabilities
   

---

报告模板

执行摘要模板

# Executive Project Summary
Date: {date}
Period: {period}

## Overall Status: {status_indicator}

### Progress
- Phase Completion: {phase_progress}%
- On Schedule: {schedule_status}
- Budget Status: {budget_status}

### Key Achievements
1. {achievement_1}
2. {achievement_2}
3. {achievement_3}

### Risks & Mitigation
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| {risk_1} | {impact} | {prob} | {mitigation} |

### Next Milestone
- {milestone_name}: {milestone_date}
- {deliverables}

### Resource Requirements
- {resource_needs}

技术报告模板

# Technical Project Report
Date: {date}

## Architecture
- ADRs Approved: {adr_count}
- Major Decisions: {decisions_summary}

## Implementation
- Requirements Completed: {req_completed}/{req_total}
- Code Coverage: {coverage}%
- Technical Debt: {tech_debt_score}

## Quality Metrics
- Code Review Score: {review_score}/100
- Security Issues: {security_count}
- Performance Benchmarks: {performance_data}

## Infrastructure
- Environments: {env_status}
- Deployments: {deployment_count}
- Uptime: {uptime}%

## Traceability
- Forward Coverage: {forward_trace}%
- Backward Coverage: {backward_trace}%
- Gaps: {gap_count}

---

数据来源

主要来源

• 所有 SDD 工件文件（BRD、PRD、REQ、BDD、ADR、SPEC、TASK、CTR）
• Git 提交历史
• 测试执行结果
• 代码覆盖率报告
• 安全扫描结果
• CI/CD 流水线日志

衍生指标

• 速度计算
• 趋势分析
• 预测
• 异常检测

---

可视化选项

图表类型

1. 燃尽图：冲刺/项目进度
2. 速度图：每周实现速度
3. 覆盖率趋势：随时间变化的测试覆盖率
4. 可追溯性矩阵：需求到代码的映射
5. 依赖关系图：任务依赖关系
6. 风险热力图：风险概率与影响
7. 质量仪表板：多指标可视化

导出格式

• HTML 仪表板（交互式）
• PDF 报告（静态）
• JSON 数据（用于集成）
• Markdown 报告（用于 Git）
• Mermaid 图表（用于文档）
• CSV 数据（用于电子表格）

---

工具访问权限

必需工具：

• Read：读取所有 SDD 工件
• Glob：查找所有文档
• Grep：搜索模式和 ID
• Bash：执行分析脚本

必需库：

• pandas：数据分析
• matplotlib/plotly：可视化
• jinja2：报告模板
• pyyaml：YAML 解析

---

集成点

与 doc-flow 集成

• 从生成的文档中提取元数据
• 跟踪文档工作流进度
• 识别文档缺口

与 test-automation 集成

• 汇总测试覆盖率数据
• 跟踪测试执行趋势
• 将测试与需求关联

与 code-review 集成

• 跟踪代码质量趋势
• 汇总评审评分
• 识别质量模式

与 project-mngt 集成

• 验证时间线执行情况
• 跟踪里程碑进度
• 分析资源利用率

---

最佳实践

1. 更新频率：每日自动收集，每周生成报告
2. 建立基线：在项目开始时设定基线指标
3. 趋势分析：关注趋势，而非绝对数值
4. 可执行的洞察：每项指标都应为决策提供依据
5. 异常检测：对异常模式发出警报
6. 历史数据：保留至少 6 个月的历史数据
7. 利益相关者协调：根据受众定制报告
8. 持续改进：根据反馈不断完善指标

---

限制

1. 要求 SDD 工件结构一致
2. 历史分析受可用数据限制
3. 预测准确度取决于数据质量
4. 无法衡量主观质量因素
5. 需要定期收集数据以确保准确性

---

成功标准

• 提供实时仪表板
• 报告生成时间 <5 分钟
• 数据准确率 100%
• 自动跟踪所有 KPI
• 趋势分析的预测准确率达 90%
• 无需手动收集数据
• 利益相关者满意度 ≥4/5

---

备注

• 报告保存至 reports/analytics/
• 历史数据存储在 metrics/history.json
• 仪表板每 15 分钟自动刷新
• 已配置 KPI 阈值超限警报
• 可通过 .analytics.yml 配置自定义指标