cve-dashboard/.kiro/specs/compliance-multi-metric-notes/requirements.md

Requirements Document

Introduction

The compliance detail panel currently allows users to add notes to a single metric at a time via a dropdown selector. When a remediation action, vendor ticket, or status update applies to multiple metrics on the same device, users must repeat the same note for each metric individually. This feature adds multi-metric selection to the note creation flow so that a single note can be associated with multiple metrics in one action, while preserving the existing per-metric note history and display.

Glossary

• Detail_Panel: The slide-out panel (ComplianceDetailPanel.js) that opens when a user clicks a device row on the Compliance page. It displays failing metrics, resolved metrics, upload history, and notes for a single hostname.
• Note: A timestamped, user-attributed text entry stored in the compliance_notes table, keyed on (hostname, metric_id). Notes persist across uploads and form a historical record.
• Metric_Selector: The UI control in the Detail_Panel's notes section that allows the user to choose which metric(s) a note applies to. Currently a single-select dropdown; this feature replaces it with a multi-select control.
• Metric_Chip: A small colored badge displaying a metric ID, used throughout the compliance UI to visually identify metrics by category color.
• Notes_API: The POST /api/compliance/notes endpoint that persists a note to the database.
• Active_Metric: A compliance item with status = 'active' for the selected hostname — these are the metrics currently failing.

Requirements

Requirement 1: Multi-Metric Selection UI

User Story: As a compliance analyst, I want to select multiple metrics when adding a note, so that I can document a single remediation action that covers several metrics without repeating myself.

Acceptance Criteria

1. WHEN the Detail_Panel is open for a hostname with more than one Active_Metric, THE Metric_Selector SHALL display all Active_Metrics as individually selectable options.
2. WHEN the user interacts with the Metric_Selector, THE Metric_Selector SHALL allow the user to select one or more Active_Metrics simultaneously.
3. WHEN the Detail_Panel is open for a hostname with exactly one Active_Metric, THE Metric_Selector SHALL pre-select that metric and remain visible as a single non-removable selection.
4. WHEN the Detail_Panel first opens for a hostname with multiple Active_Metrics, THE Metric_Selector SHALL pre-select the first Active_Metric by default.
5. THE Metric_Selector SHALL display each option using the Metric_Chip component with the metric's category color, so that metrics are visually distinguishable.

Requirement 2: Select All / Deselect All

User Story: As a compliance analyst, I want a quick way to select or deselect all metrics, so that I can efficiently apply a note to every failing metric on a device.

Acceptance Criteria

1. WHEN the hostname has more than one Active_Metric, THE Metric_Selector SHALL display a "Select All" toggle that selects all Active_Metrics when activated.
2. WHEN all Active_Metrics are already selected, THE "Select All" toggle SHALL change to "Deselect All" and deselect all Active_Metrics when activated.
3. WHEN the user manually selects all Active_Metrics one by one, THE toggle label SHALL update to "Deselect All" to reflect the current state.

Requirement 3: Multi-Metric Note Submission

User Story: As a compliance analyst, I want the system to save my note against all selected metrics in one action, so that the historical record accurately reflects which metrics the note covers.

Acceptance Criteria

1. WHEN the user submits a note with multiple metrics selected, THE Notes_API SHALL create one compliance_notes row per selected metric, all sharing the same note text, created_by, and created_at timestamp.
2. WHEN the user submits a note with a single metric selected, THE Notes_API SHALL create exactly one compliance_notes row, preserving backward compatibility with the existing behavior.
3. IF the note text is empty or contains only whitespace, THEN THE Notes_API SHALL reject the submission and return a validation error.
4. IF no metrics are selected, THEN THE Detail_Panel SHALL disable the submit button and prevent submission.
5. WHEN a multi-metric note is successfully saved, THE Detail_Panel SHALL clear the note text field, refresh the notes list, and retain the current metric selection.

Requirement 4: Multi-Metric Note Display

User Story: As a compliance analyst, I want to see which metrics a note was applied to, so that I can understand the scope of past remediation actions.

Acceptance Criteria

1. WHEN a note was submitted for multiple metrics simultaneously, THE Detail_Panel SHALL display all associated Metric_Chips together on that note entry, visually grouped.
2. WHEN a note was submitted for a single metric, THE Detail_Panel SHALL continue to display a single Metric_Chip on that note entry, matching the current behavior.
3. THE Detail_Panel SHALL display notes in reverse chronological order, with the newest note first, regardless of how many metrics each note covers.

Requirement 5: Backend Multi-Metric Notes Endpoint

User Story: As a developer, I want the notes API to accept an array of metric IDs, so that the frontend can submit a note for multiple metrics in a single request.

Acceptance Criteria

1. THE Notes_API SHALL accept a metric_ids field (array of strings) in the request body as an alternative to the existing metric_id field (single string).
2. WHEN metric_ids is provided, THE Notes_API SHALL validate that each entry is a non-empty string of 50 characters or fewer.
3. WHEN metric_ids is provided, THE Notes_API SHALL insert one compliance_notes row per metric ID, all within the same database transaction, sharing the same created_at timestamp.
4. WHEN the legacy metric_id field is provided instead of metric_ids, THE Notes_API SHALL continue to function as before, inserting a single row.
5. IF both metric_id and metric_ids are provided, THEN THE Notes_API SHALL use metric_ids and ignore metric_id.
6. IF any metric ID in the metric_ids array fails validation, THEN THE Notes_API SHALL reject the entire request and return a 400 error without inserting any rows.
7. THE Notes_API SHALL return all created note rows in the response, so the frontend can update the display without a separate fetch.

Requirement 6: Note Grouping Identifier

User Story: As a developer, I want notes that were created together to share a group identifier, so that the frontend can visually group multi-metric notes in the display.

Acceptance Criteria

1. WHEN multiple notes are created from a single submission, THE Notes_API SHALL assign the same group_id value to all rows in that batch.
2. WHEN a single note is created, THE Notes_API SHALL assign a unique group_id to that row.
3. THE group_id SHALL be stored as a text column in the compliance_notes table.
4. THE Detail_Panel SHALL use the group_id to visually group notes that were submitted together, displaying them as a single note entry with multiple Metric_Chips rather than as separate entries.