# Design Document: Remediation Plan History

## Overview

Adds an append-only audit trail for resolution_date and remediation_plan changes on compliance items. The design preserves the existing compliance_items schema (current values remain directly queryable) and introduces a new `compliance_item_history` table for historical entries. The pattern mirrors how `compliance_notes` works — separate rows with timestamps and attribution.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     ComplianceDetailPanel                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │ Resolution   │  │ Remediation  │  │ Change Reason (text)  │ │
│  │ Date Input   │  │ Plan Input   │  │                       │ │
│  └──────┬───────┘  └──────┬───────┘  └───────────┬───────────┘ │
│         │                  │                      │              │
│         └──────────────────┴──────────────────────┘              │
│                            │                                     │
│                   PATCH /metadata                                 │
│                   { resolution_date, remediation_plan,            │
│                     change_reason }                               │
│                            │                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Change History Section                          │ │
│  │  [date] [field] [old→new] [by user] [reason]               │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Backend (compliance.js)                        │
│                                                                  │
│  PATCH /items/:hostname/metadata                                 │
│    1. Validate inputs                                            │
│    2. SELECT current values from compliance_items                 │
│    3. Compare old vs new — skip if identical                     │
│    4. INSERT into compliance_item_history (per changed field)     │
│    5. UPDATE compliance_items with new values                    │
│                                                                  │
│  GET /items/:hostname                                            │
│    (existing) + SELECT from compliance_item_history              │
│    LIMIT 10 ORDER BY changed_at DESC                             │
│                                                                  │
│  POST /vcl/bulk-commit                                           │
│    For each hostname: same compare-then-insert pattern           │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PostgreSQL                                 │
│                                                                  │
│  compliance_items (unchanged)                                    │
│    resolution_date DATE                                           │
│    remediation_plan TEXT                                          │
│                                                                  │
│  compliance_item_history (new)                                   │
│    id, hostname, field_name, old_value, new_value,               │
│    change_reason, changed_by, changed_at                         │
└─────────────────────────────────────────────────────────────────┘
```

## Data Model

### New Table: compliance_item_history

```sql
CREATE TABLE IF NOT EXISTS compliance_item_history (
    id SERIAL PRIMARY KEY,
    hostname TEXT NOT NULL,
    field_name TEXT NOT NULL CHECK (field_name IN ('resolution_date', 'remediation_plan')),
    old_value TEXT,
    new_value TEXT,
    change_reason TEXT,
    changed_by TEXT NOT NULL,
    changed_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_compliance_history_hostname_field
    ON compliance_item_history(hostname, field_name);
CREATE INDEX IF NOT EXISTS idx_compliance_history_changed_at
    ON compliance_item_history(changed_at);
```

### Existing Table: compliance_items (no changes)

The `resolution_date` and `remediation_plan` columns remain as-is. They continue to hold the current/latest value for direct querying by VCL reports.

## API Changes

### PATCH /api/compliance/items/:hostname/metadata

**Request body changes:**

```json
{
  "resolution_date": "2026-03-15",
  "remediation_plan": "Upgrade firmware to v4.2",
  "change_reason": "Vendor pushed back delivery date"
}
```

New optional field: `change_reason` (string, max 500 characters, nullable).

**Behavior changes:**

1. Before updating compliance_items, query the current values:
   ```sql
   SELECT DISTINCT ON (hostname) resolution_date, remediation_plan
   FROM compliance_items
   WHERE hostname = $1 AND status = 'active'
   ORDER BY hostname, id DESC
   LIMIT 1
   ```

2. For each field being updated, compare old vs new. If different, insert a history row:
   ```sql
   INSERT INTO compliance_item_history (hostname, field_name, old_value, new_value, change_reason, changed_by)
   VALUES ($1, $2, $3, $4, $5, $6)
   ```

3. Then proceed with the existing UPDATE as before.

**Response:** unchanged (`{ updated: number }`).

### GET /api/compliance/items/:hostname

**Response changes:**

Add a `history` array to the response:

```json
{
  "hostname": "server01.example.com",
  "ip_address": "10.0.1.5",
  "device_type": "Server",
  "team": "STEAM",
  "resolution_date": "2026-03-15",
  "remediation_plan": "Upgrade firmware to v4.2",
  "metrics": [...],
  "notes": [...],
  "history": [
    {
      "id": 42,
      "field_name": "resolution_date",
      "old_value": "2026-02-01",
      "new_value": "2026-03-15",
      "change_reason": "Vendor pushed back delivery date",
      "changed_by": "jsmith",
      "changed_at": "2026-01-20T14:30:00.000Z"
    },
    {
      "id": 41,
      "field_name": "remediation_plan",
      "old_value": null,
      "new_value": "Upgrade firmware to v4.2",
      "change_reason": null,
      "changed_by": "jsmith",
      "changed_at": "2026-01-15T09:00:00.000Z"
    }
  ]
}
```

Query:
```sql
SELECT id, field_name, old_value, new_value, change_reason, changed_by, changed_at
FROM compliance_item_history
WHERE hostname = $1
ORDER BY changed_at DESC
LIMIT 10
```

### POST /api/compliance/vcl/bulk-commit

**Behavior changes:**

Within the transaction, before updating each hostname:
1. Query current values for that hostname
2. Compare each field (resolution_date, remediation_plan) against the incoming value
3. Insert history rows for changed fields with `changed_by` set to `req.user.username`

No request/response shape changes. The `change_reason` is not supported for bulk updates (would require per-row reasons which adds complexity without clear value for mass imports).

## Frontend Changes

### ComplianceDetailPanel.js

**New state:**
- `changeReason` (string) — text input value for the reason field
- `history` (array) — populated from the API response

**New UI elements:**

1. **Change Reason input** — a single-line text input placed between the remediation plan save button and the notes section. Cleared after each successful save.

2. **Change History section** — a new `<Section>` component placed between the Remediation Plan section and the Notes section. Displays up to 10 history entries in reverse chronological order.

**History entry display format:**
```
[field_name icon] old_value → new_value
                  username · 2026-01-20  [reason if present]
```

- Resolution date entries: show dates as YYYY-MM-DD, NULL shown as "—"
- Remediation plan entries: truncate old/new values to 60 characters with "…" suffix; full text shown on hover via title attribute
- Change reason: displayed in muted text below the change line when present

**Save flow update:**
- The `handleSaveMetadata` function passes `change_reason` alongside the field values
- After successful save, clear the `changeReason` input and re-fetch detail (which now includes updated history)

## Error Handling

- If the history INSERT fails, the entire PATCH operation should fail (history is part of the same logical operation). Use a transaction wrapping both the history insert and the compliance_items update.
- If the history SELECT for the GET endpoint fails, return the device detail without history (graceful degradation) and log the error.
- `change_reason` validation: max 500 characters, trimmed. If over 500, return 400 with descriptive error.

## Migration

File: `backend/migrations/add_compliance_item_history.js`

```javascript
const pool = require('../db');

async function run() {
    console.log('Starting compliance_item_history migration...');
    try {
        await pool.query(`
            CREATE TABLE IF NOT EXISTS compliance_item_history (
                id SERIAL PRIMARY KEY,
                hostname TEXT NOT NULL,
                field_name TEXT NOT NULL CHECK (field_name IN ('resolution_date', 'remediation_plan')),
                old_value TEXT,
                new_value TEXT,
                change_reason TEXT,
                changed_by TEXT NOT NULL,
                changed_at TIMESTAMPTZ DEFAULT NOW()
            )
        `);
        console.log('✓ compliance_item_history table created (or already exists)');

        await pool.query(`
            CREATE INDEX IF NOT EXISTS idx_compliance_history_hostname_field
            ON compliance_item_history(hostname, field_name)
        `);
        console.log('✓ hostname/field_name index created');

        await pool.query(`
            CREATE INDEX IF NOT EXISTS idx_compliance_history_changed_at
            ON compliance_item_history(changed_at)
        `);
        console.log('✓ changed_at index created');

        console.log('Migration complete.');
    } catch (err) {
        console.error('Migration failed:', err.message);
        throw err;
    }
}

module.exports = { run };
```

## Reporting Isolation

No changes to VCL reporting queries. The following queries continue to read directly from `compliance_items.resolution_date`:

- Donut chart: `SELECT hostname, MAX(resolution_date) FROM compliance_items WHERE status = 'active' GROUP BY hostname`
- Burndown forecast: `SELECT resolution_date FROM compliance_items WHERE status = 'active' AND resolution_date IS NOT NULL`
- Per-vertical burndown in vclMultiVertical.js

The `compliance_item_history` table is never referenced by any reporting query.

## Performance Considerations

- History inserts are lightweight (single row per field change). Even bulk updates with 500 hostnames produce at most 1000 history rows per commit — well within PostgreSQL's transaction capacity.
- The LIMIT 10 on history retrieval prevents unbounded result sets for devices with many changes.
- Indexes on (hostname, field_name) and (changed_at) ensure fast lookups without full table scans.
- No additional queries are added to the VCL reporting paths.