cve-dashboard/.kiro/specs/ccp-metrics-view-restructure/requirements.md

Requirements Document

Introduction

This feature restructures the CCP Metrics page drill-down hierarchy from a vertical-first model (Vertical → Metric → Subteam → Devices) to a metric-first model (Metric → Vertical → Subteam → Devices). The overview table changes from showing one row per vertical to one row per metric (aggregated across all verticals), with each metric appearing once with totals summed across verticals. Clicking a metric drills into which verticals have that metric. Additionally, the "By Vertical" contribution table currently rendered below the AggregatedBurndownChart is removed — the burndown chart and summary stats remain.

Two new backend endpoints support the metric-centric view alongside existing vertical-first endpoints, which are preserved for backward compatibility.

Glossary

• CCP_Metrics_Page: The React page component (CCPMetricsPage.js) that displays cross-organizational compliance posture and provides drill-down navigation.
• Overview_Table: The primary data table on the CCP_Metrics_Page overview that users interact with to begin drill-down navigation.
• Metrics_API: The new backend endpoint GET /api/compliance/vcl-multi/metrics that returns all metrics aggregated across verticals.
• Metric_Verticals_API: The new backend endpoint GET /api/compliance/vcl-multi/metric/:id/verticals that returns per-vertical breakdown for a specific metric.
• Devices_API: The existing backend endpoint GET /api/compliance/vcl-multi/vertical/:code/metric/:metricId/devices that returns non-compliant devices filtered by vertical, metric, and optionally team.
• Drill_Down_State: The set of React state variables that track the user's current navigation depth within the metric-centric hierarchy.
• AggregatedBurndownChart: The existing React component that displays the cross-vertical burndown forecast bar chart and summary statistics on the overview page.
• Metric_Row: A single row in the Overview_Table representing one metric with compliance totals summed across all verticals.

Requirements

Requirement 1: Remove "By Vertical" Table from AggregatedBurndownChart

User Story: As a compliance analyst, I want the burndown chart section to show only the forecast chart and summary stats without the per-vertical contribution table, so that the overview page is less cluttered and the vertical breakdown is accessible through the drill-down instead.

Acceptance Criteria

1. THE AggregatedBurndownChart component SHALL render the summary header (total non-compliant, blockers, in-progress, projected clear date) and the bar chart.
2. THE AggregatedBurndownChart component SHALL omit the "By Vertical" contribution table that previously appeared below the bar chart.
3. THE AggregatedBurndownChart component SHALL preserve all existing loading, error, empty-state, and all-blockers display behaviors.

Requirement 2: Metric-Aggregated Overview Table

User Story: As a senior leader, I want the overview table to show one row per metric with totals summed across all verticals, so that I can immediately see which metrics have the most non-compliance across the organization.

Acceptance Criteria

1. THE Overview_Table SHALL display one Metric_Row per distinct metric, with compliance totals (compliant, non_compliant, total, compliance_pct, target) aggregated across all verticals.
2. THE Overview_Table SHALL display columns for metric ID, description, category, compliant count, non-compliant count, total count, compliance percentage, and target percentage.
3. THE Overview_Table SHALL sort Metric_Rows by non-compliant count in descending order by default.
4. WHEN a user clicks a Metric_Row, THE CCP_Metrics_Page SHALL navigate to the metric-vertical drill-down view for that metric.
5. THE Overview_Table SHALL replace the existing VerticalTable component on the overview page.

Requirement 3: Metrics Aggregated API Endpoint

User Story: As a frontend developer, I want a single API endpoint that returns all metrics aggregated across verticals, so that the overview table can display metric-centric data without client-side aggregation.

Acceptance Criteria

1. WHEN a GET request is made to /api/compliance/vcl-multi/metrics, THE Metrics_API SHALL return a JSON response containing a metrics array where each entry represents one distinct metric aggregated across all verticals.
2. THE Metrics_API SHALL compute each metric entry with fields: metric_id, metric_desc, category, non_compliant, compliant, total, compliance_pct, and target.
3. THE Metrics_API SHALL aggregate totals by summing non_compliant, compliant, and total across all verticals for each metric, using only rollup rows (team starting with "ALL:") from the latest upload per vertical.
4. THE Metrics_API SHALL compute compliance_pct as compliant / total for each aggregated metric.
5. THE Metrics_API SHALL compute target as the average target across verticals for each metric.
6. THE Metrics_API SHALL sort the returned metrics array by non_compliant in descending order.
7. WHEN no summary data exists, THE Metrics_API SHALL return an empty metrics array.
8. THE Metrics_API SHALL require authentication via requireAuth() middleware.
9. IF a database error occurs, THEN THE Metrics_API SHALL return HTTP 500 with { "error": "Database error" }.

Requirement 4: Metric-Verticals Drill-Down API Endpoint

User Story: As a frontend developer, I want an API endpoint that returns which verticals have a specific metric and their per-vertical compliance numbers, so that the drill-down view can show vertical breakdown for a selected metric.

Acceptance Criteria

1. WHEN a GET request is made to /api/compliance/vcl-multi/metric/:id/verticals, THE Metric_Verticals_API SHALL return a JSON response containing a verticals array with per-vertical breakdown for the specified metric.
2. THE Metric_Verticals_API SHALL return each vertical entry with fields: vertical, non_compliant, compliant, total, compliance_pct, target, and sub_teams.
3. THE Metric_Verticals_API SHALL include a sub_teams array within each vertical entry containing per-team breakdown with fields: team, non_compliant, compliant, total, compliance_pct.
4. THE Metric_Verticals_API SHALL sort the verticals array by non_compliant in descending order.
5. THE Metric_Verticals_API SHALL also return metric_id, metric_desc, and category fields at the top level for display context.
6. WHEN the specified metric ID does not exist in any vertical, THE Metric_Verticals_API SHALL return an empty verticals array with the metric_id echoed back.
7. IF the metric ID parameter exceeds 50 characters, THEN THE Metric_Verticals_API SHALL return HTTP 400 with { "error": "Invalid metric ID" }.
8. THE Metric_Verticals_API SHALL require authentication via requireAuth() middleware.
9. IF a database error occurs, THEN THE Metric_Verticals_API SHALL return HTTP 500 with { "error": "Database error" }.

Requirement 5: Metric-Centric Drill-Down Hierarchy

User Story: As a compliance analyst, I want to drill down from a metric to see which verticals are affected, then into a vertical's sub-teams, and finally to the device list, so that I can trace non-compliance from the metric level down to individual devices.

Acceptance Criteria

1. WHEN a user clicks a Metric_Row in the Overview_Table, THE CCP_Metrics_Page SHALL display a metric-vertical view showing per-vertical breakdown for that metric.
2. THE metric-vertical view SHALL display the metric ID, description, and category as a header, along with aggregated compliance stats for that metric.
3. THE metric-vertical view SHALL display a table of verticals with columns: vertical name, compliant, non-compliant, total, and compliance percentage.
4. WHEN a user clicks a vertical row in the metric-vertical view, THE CCP_Metrics_Page SHALL display a sub-team breakdown view for that vertical and metric combination.
5. THE sub-team breakdown view SHALL display per-team compliance numbers with columns: team name, compliant, non-compliant, total, and compliance percentage.
6. WHEN a user clicks a sub-team row in the sub-team view, THE CCP_Metrics_Page SHALL display the device list filtered by the selected vertical, metric, and team.
7. THE device list view SHALL reuse the existing Devices_API endpoint (GET /api/compliance/vcl-multi/vertical/:code/metric/:metricId/devices) with the vertical and metric parameters derived from the drill-down context.
8. WHEN a user clicks a "View All Devices" option in the sub-team view, THE CCP_Metrics_Page SHALL display the device list for all teams within that vertical and metric.

Requirement 6: Drill-Down Navigation State

User Story: As a user navigating the drill-down hierarchy, I want clear back-navigation at each level so that I can return to the previous view without losing context.

Acceptance Criteria

1. THE Drill_Down_State SHALL track the selected metric, selected vertical, and selected team to determine which view to render.
2. WHEN the metric-vertical view is displayed, THE CCP_Metrics_Page SHALL provide a "Back to Overview" navigation element that clears the selected metric and returns to the overview.
3. WHEN the sub-team view is displayed, THE CCP_Metrics_Page SHALL provide a "Back to Verticals" navigation element that clears the selected vertical and returns to the metric-vertical view.
4. WHEN the device list view is displayed, THE CCP_Metrics_Page SHALL provide a "Back to Sub-Teams" navigation element that clears the selected team and returns to the sub-team view.
5. THE CCP_Metrics_Page SHALL render the overview (with Overview_Table) when no metric is selected in the Drill_Down_State.

Requirement 7: Backward Compatibility

User Story: As a developer maintaining the system, I want existing vertical-first endpoints to remain functional so that any external consumers or future features relying on them continue to work.

Acceptance Criteria

1. THE backend SHALL preserve the existing GET /api/compliance/vcl-multi/vertical/:code/metrics endpoint with unchanged behavior and response shape.
2. THE backend SHALL preserve the existing GET /api/compliance/vcl-multi/vertical/:code/metric/:metricId/devices endpoint with unchanged behavior and response shape.
3. THE backend SHALL preserve the existing GET /api/compliance/vcl-multi/vertical/:code/burndown endpoint with unchanged behavior and response shape.
4. THE backend SHALL preserve the existing GET /api/compliance/vcl-multi/stats endpoint with unchanged behavior and response shape, including the vertical_breakdown and metric_breakdown fields.