99 lines
7.8 KiB
Markdown
99 lines
7.8 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
Historical tracking for resolution dates and remediation plans on compliance items. When a user changes the resolution_date or remediation_plan for a device, the previous value is preserved as an audit trail entry with a timestamp and the identity of the user who made the change. The most recent values remain directly queryable on the compliance_items table so existing VCL reporting queries continue to work without modification.
|
|
|
|
## Glossary
|
|
|
|
- **Compliance_Item**: A row in the `compliance_items` table representing a single non-compliant device/metric pair.
|
|
- **Resolution_Date**: A DATE field on a compliance item indicating when remediation is expected to complete.
|
|
- **Remediation_Plan**: A TEXT field (max 2000 characters) describing the planned remediation approach.
|
|
- **History_Entry**: A row in the `compliance_item_history` table capturing a previous value of resolution_date or remediation_plan before it was overwritten.
|
|
- **Change_Reason**: An optional text field on a History_Entry describing why the change was made.
|
|
- **Detail_Panel**: The ComplianceDetailPanel UI component that displays device-level compliance information and allows editing of metadata fields.
|
|
- **VCL_Report**: The multi-vertical compliance reporting system that uses resolution_date for burndown forecasts and blocked/in-progress donut charts.
|
|
- **Current_Value**: The value stored directly on the compliance_items row, representing the most recent resolution_date or remediation_plan.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Persist History on Field Change
|
|
|
|
**User Story:** As a compliance analyst, I want previous resolution dates and remediation plans to be preserved when I make changes, so that I have an audit trail of what was planned and when plans changed.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a user updates the resolution_date for a hostname via the metadata PATCH endpoint, THE History_Service SHALL insert a History_Entry containing the previous resolution_date value, the field name, the hostname, the timestamp of the change, the username of the user who made the change, and the change_reason if provided.
|
|
2. WHEN a user updates the remediation_plan for a hostname via the metadata PATCH endpoint, THE History_Service SHALL insert a History_Entry containing the previous remediation_plan value, the field name, the hostname, the timestamp of the change, the username of the user who made the change, and the change_reason if provided.
|
|
3. WHEN the previous value is NULL and the user sets a new value, THE History_Service SHALL insert a History_Entry with the old_value recorded as NULL.
|
|
4. WHEN the new value is identical to the current value, THE History_Service SHALL NOT create a History_Entry.
|
|
5. WHEN a bulk update changes resolution_date or remediation_plan for multiple hostnames, THE History_Service SHALL insert one History_Entry per hostname per changed field.
|
|
6. THE History_Service SHALL accept an optional change_reason field in the metadata PATCH request body.
|
|
|
|
### Requirement 2: History Storage Schema
|
|
|
|
**User Story:** As a system administrator, I want history entries stored in a dedicated table with proper indexing, so that history queries are fast and do not impact existing compliance_items queries.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Database SHALL store history entries in a `compliance_item_history` table with columns: id (serial primary key), hostname (text, not null), field_name (text, not null), old_value (text), new_value (text), change_reason (text), changed_by (text, not null), changed_at (timestamptz, default NOW()).
|
|
2. THE Database SHALL index the `compliance_item_history` table on (hostname, field_name) for efficient per-device history lookups.
|
|
3. THE Database SHALL index the `compliance_item_history` table on (changed_at) for chronological queries.
|
|
4. THE compliance_items table SHALL continue to store the current resolution_date and remediation_plan directly as columns, unchanged from the existing schema.
|
|
|
|
### Requirement 3: Reporting Isolation
|
|
|
|
**User Story:** As a VCL report consumer, I want burndown forecasts and donut charts to use only the current resolution_date, so that historical changes do not cause double-counting or incorrect projections.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE VCL_Report SHALL read resolution_date exclusively from the compliance_items table for burndown and donut calculations.
|
|
2. THE VCL_Report SHALL NOT join or reference the compliance_item_history table for any reporting query.
|
|
3. WHEN multiple History_Entries exist for a hostname, THE VCL_Report SHALL use only the Current_Value from compliance_items.resolution_date for forecasting.
|
|
|
|
### Requirement 4: History Retrieval API
|
|
|
|
**User Story:** As a compliance analyst, I want to retrieve the change history for a device's resolution date and remediation plan, so that I can see who changed what and when.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a client requests the detail for a hostname, THE Compliance_API SHALL return the history of resolution_date and remediation_plan changes alongside the current values and notes.
|
|
2. THE Compliance_API SHALL return history entries sorted by changed_at in descending order (most recent first).
|
|
3. THE Compliance_API SHALL return a maximum of 10 history entries per hostname.
|
|
4. THE Compliance_API SHALL include the fields: field_name, old_value, new_value, change_reason, changed_by, and changed_at for each History_Entry.
|
|
5. IF no history entries exist for a hostname, THE Compliance_API SHALL return an empty array for the history field.
|
|
|
|
### Requirement 5: History Display in Detail Panel
|
|
|
|
**User Story:** As a compliance analyst, I want to see the history of changes to resolution date and remediation plan in the device detail panel, so that I can understand how plans have evolved over time.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Detail_Panel SHALL display a "Change History" section showing all History_Entries for the selected hostname.
|
|
2. WHEN a History_Entry exists, THE Detail_Panel SHALL display the field that changed, the old value, the new value, who made the change, when the change occurred, and the change reason if one was provided.
|
|
3. THE Detail_Panel SHALL display history entries in reverse chronological order (most recent change at the top).
|
|
4. WHEN no history entries exist, THE Detail_Panel SHALL display a message indicating no changes have been recorded.
|
|
5. THE Detail_Panel SHALL format resolution_date values as YYYY-MM-DD and remediation_plan values as truncated text with a tooltip or expandable view for long entries.
|
|
6. THE Detail_Panel SHALL include a text input for change_reason when saving resolution_date or remediation_plan changes.
|
|
|
|
### Requirement 6: Bulk Update History Tracking
|
|
|
|
**User Story:** As a compliance analyst, I want bulk xlsx updates to also track history, so that mass changes to resolution dates and remediation plans are auditable.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the bulk update commit endpoint applies changes to resolution_date or remediation_plan, THE History_Service SHALL create History_Entries for each hostname where the value changed.
|
|
2. THE History_Service SHALL record the changed_by as the username of the user who initiated the bulk update.
|
|
3. WHEN a bulk update row contains the same value as the current value for a hostname, THE History_Service SHALL NOT create a History_Entry for that field.
|
|
|
|
### Requirement 7: Database Migration
|
|
|
|
**User Story:** As a developer, I want the history table created via a standard migration script, so that it can be applied to existing deployments without manual intervention.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Migration SHALL create the `compliance_item_history` table if it does not already exist.
|
|
2. THE Migration SHALL create the required indexes on the `compliance_item_history` table.
|
|
3. THE Migration SHALL be idempotent and safe to run multiple times without error.
|
|
4. THE Migration SHALL NOT modify the existing compliance_items table structure.
|