jramos/cve-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a61d254ff998e6243295bf5a413f75ab8e54c5d8
cve-dashboard/.kiro/specs/ccp-metrics-view-restructure/requirements.md
Jordan Ramos a61d254ff9 Sync .kiro/ from master — v2.2.0 release batch 
New specs: archer-template-library, ccp-metrics-view-restructure,
compliance-list-stale-after-sidebar-edit, compliance-metric-estimated-resolution-date,
compliance-remediation-display-fix, flexible-jira-ticket-creation,
forecast-burndown-chart, granite-loader-export, ivanti-queue-clear-completed-fix,
multi-item-jira-ticket, queue-collapsible-sections, vendor-issue-type-dropdown

New steering: archer-template-gen.md

Updated: migration-registration-check hook, remediation-plan-history spec,
gitlab-workflow, tech, versioning steering files
2026-06-04 11:27:31 -06:00

113 lines
10 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink