cmdb-insight/docs/DATA-INTEGRITY-PLAN.md

Data Integriteit Plan - Voorkomen van Kapotte Referenties

Probleem

Kapotte referenties ontstaan wanneer attribute_values.reference_object_id verwijst naar objecten die niet in de objects tabel bestaan. Dit kan gebeuren door:

1. Objecten verwijderd uit Jira maar referenties blijven bestaan
2. Onvolledige sync (niet alle gerelateerde objecten zijn gesynchroniseerd)
3. Objecten verwijderd uit cache maar referenties blijven bestaan
4. Race conditions tijdens sync

Strategie: Multi-layer Aanpak

Laag 1: Preventie tijdens Sync (Hoogste Prioriteit)

1.1 Referenced Object Validation tijdens Sync

Doel: Zorg dat alle referenced objects bestaan voordat we referenties opslaan

Implementatie:

• Voeg validatie toe in extractAndStoreRelations() en normalizeObjectWithDb()
• Voor elke reference: check of target object bestaat in cache
• Als target niet bestaat: fetch het object eerst van Jira
• Als object niet in Jira bestaat: sla referentie NIET op (of markeer als "missing")

Code locatie: backend/src/services/normalizedCacheStore.ts

1.2 Deep Sync voor Referenced Objects

Doel: Sync automatisch alle referenced objects tijdens object sync

Implementatie:

• Wanneer een object wordt gesynct, identificeer alle referenced objects
• Queue deze referenced objects voor sync (als ze niet recent gesynct zijn)
• Voer sync uit in dependency order (sync referenced objects eerst)

Code locatie: backend/src/services/syncEngine.ts

1.3 Transactional Reference Storage

Doel: Zorg dat object + referenties atomisch worden opgeslagen

Implementatie:

• Gebruik database transactions voor object + referenties
• Rollback als referenced object niet bestaat
• Valideer alle references voordat commit

Code locatie: backend/src/services/normalizedCacheStore.ts

Laag 2: Database Constraints (Waar Mogelijk)

2.1 Foreign Key Constraints voor Referenties

Doel: Database-level validatie van referenties

Huidige situatie:

• attribute_values.reference_object_id heeft GEEN foreign key constraint
• Dit is bewust omdat referenced objects mogelijk niet in cache zijn

Optie A: Soft Foreign Key (Aanbevolen)

• Voeg een CHECK constraint toe die valideert dat reference_object_id NULL is OF bestaat in objects
• Dit vereist een database trigger of function

Optie B: Staging Table

• Sla nieuwe referenties eerst op in een staging table
• Valideer en migreer alleen valide referenties naar attribute_values
• Cleanup staging table periodiek

Implementatie: Database migration + trigger/function

2.2 Database Triggers voor Cleanup

Doel: Automatische cleanup wanneer objecten worden verwijderd

Implementatie:

• Trigger op DELETE van objects
• Automatisch verwijder of nullify alle attribute_values met reference_object_id = deleted.id
• Log cleanup acties voor audit

Code locatie: Database migration

Laag 3: Validatie en Cleanup Procedures

3.1 Periodieke Validatie Job

Doel: Detecteer en repareer kapotte referenties automatisch

Implementatie:

• Dagelijkse/nachtelijke job die alle broken references detecteert
• Probeer referenced objects te fetchen van Jira
• Als object bestaat: sync en repareer referentie
• Als object niet bestaat: verwijder referentie (of markeer als "deleted")

Code locatie: backend/src/services/dataIntegrityService.ts (nieuw)

Scheduling: Via cron job of scheduled task

3.2 Manual Cleanup Endpoint

Doel: Admin tool om broken references te repareren

Implementatie:

• POST /api/data-validation/repair-broken-references
• Opties:
  • mode: 'delete' - Verwijder kapotte referenties
  • mode: 'fetch' - Probeer objects te fetchen van Jira
  • mode: 'dry-run' - Toon wat er zou gebeuren zonder wijzigingen

Code locatie: backend/src/routes/dataValidation.ts

3.3 Reference Validation tijdens Object Retrieval

Doel: Valideer en repareer referenties wanneer objecten worden opgehaald

Implementatie:

• In reconstructObject(): check alle references
• Als reference broken is: probeer te fetchen van Jira
• Als fetch succesvol: update cache en referentie
• Als fetch faalt: markeer als "missing" in response

Code locatie: backend/src/services/normalizedCacheStore.ts

Laag 4: Sync Verbeteringen

4.1 Dependency-Aware Sync Order

Doel: Sync objecten in de juiste volgorde (dependencies eerst)

Implementatie:

• Analyseer schema om dependency graph te bouwen
• Sync object types in dependency order
• Bijvoorbeeld: sync "Application Function" voordat "Application Component"

Code locatie: backend/src/services/syncEngine.ts

4.2 Batch Sync met Reference Resolution

Doel: Sync batches van objecten en resolve alle references

Implementatie:

• Verzamel alle referenced object IDs tijdens batch sync
• Fetch alle referenced objects in parallel
• Valideer alle references voordat batch commit

Code locatie: backend/src/services/syncEngine.ts

4.3 Incremental Sync met Deletion Detection

Doel: Detecteer verwijderde objecten tijdens incremental sync

Implementatie:

• Vergelijk cache objecten met Jira objecten
• Identificeer objecten die in cache zijn maar niet in Jira
• Verwijder deze objecten (cascade verwijdert referenties)

Code locatie: backend/src/services/syncEngine.ts

Laag 5: Monitoring en Alerting

5.1 Metrics en Dashboard

Doel: Monitor data integriteit in real-time

Implementatie:

• Track broken references count over tijd
• Alert wanneer count boven threshold komt
• Grafiek in dashboard: broken references trend

Code locatie: backend/src/routes/dataValidation.ts + dashboard

5.2 Sync Health Checks

Doel: Valideer data integriteit na elke sync

Implementatie:

• Na sync: check voor broken references
• Log warning als broken references gevonden
• Optioneel: auto-repair tijdens sync

Code locatie: backend/src/services/syncEngine.ts

5.3 Audit Logging

Doel: Track alle data integriteit acties

Implementatie:

• Log wanneer broken references worden gerepareerd
• Log wanneer objecten worden verwijderd
• Log wanneer references worden toegevoegd/verwijderd

Code locatie: Logger service

Implementatie Prioriteiten

Fase 1: Quick Wins (Week 1)

1. ✅ Manual cleanup endpoint (/api/data-validation/repair-broken-references)
2. ✅ Periodieke validatie job (dagelijks)
3. ✅ Metrics in dashboard

Fase 2: Preventie (Week 2-3)

4. Referenced object validation tijdens sync
5. Deep sync voor referenced objects
6. Transactional reference storage

Fase 3: Database Level (Week 4)

7. Database triggers voor cleanup
8. Soft foreign key constraints (waar mogelijk)

Fase 4: Advanced (Week 5+)

9. Dependency-aware sync order
10. Incremental sync met deletion detection
11. Auto-repair tijdens object retrieval

Technische Details

Referenced Object Validation Pattern

async function validateAndFetchReference(
  referenceObjectId: string,
  targetType?: string
): Promise<{ exists: boolean; object?: CMDBObject }> {
  // 1. Check cache first
  const cached = await cacheStore.getObjectById(referenceObjectId);
  if (cached) return { exists: true, object: cached };
  
  // 2. Try to fetch from Jira
  try {
    const jiraObj = await jiraAssetsClient.getObject(referenceObjectId);
    if (jiraObj) {
      // Parse and cache
      const parsed = jiraAssetsClient.parseObject(jiraObj);
      if (parsed) {
        await cacheStore.upsertObject(parsed._objectType, parsed);
        return { exists: true, object: parsed };
      }
    }
  } catch (error) {
    if (error instanceof JiraObjectNotFoundError) {
      return { exists: false };
    }
    throw error;
  }
  
  return { exists: false };
}

Cleanup Procedure

async function repairBrokenReferences(mode: 'delete' | 'fetch' | 'dry-run'): Promise<{
  total: number;
  repaired: number;
  deleted: number;
  failed: number;
}> {
  const brokenRefs = await cacheStore.getBrokenReferences(10000, 0);
  let repaired = 0;
  let deleted = 0;
  let failed = 0;
  
  for (const ref of brokenRefs) {
    if (mode === 'fetch') {
      // Try to fetch from Jira
      const result = await validateAndFetchReference(ref.reference_object_id);
      if (result.exists) {
        repaired++;
      } else {
        // Object doesn't exist, delete reference
        await cacheStore.deleteAttributeValue(ref.object_id, ref.attribute_id);
        deleted++;
      }
    } else if (mode === 'delete') {
      await cacheStore.deleteAttributeValue(ref.object_id, ref.attribute_id);
      deleted++;
    }
    // dry-run: just count
  }
  
  return { total: brokenRefs.length, repaired, deleted, failed };
}

Success Criteria

• ✅ Broken references count < 1% van totaal aantal referenties
• ✅ Geen nieuwe broken references tijdens normale sync
• ✅ Auto-repair binnen 24 uur na detectie
• ✅ Monitoring dashboard toont real-time integriteit status
• ✅ Sync performance blijft acceptabel (< 10% overhead)

Monitoring

Key Metrics

• broken_references_count - Totaal aantal kapotte referenties
• broken_references_rate - Percentage van totaal aantal referenties
• reference_repair_success_rate - Percentage succesvol gerepareerde referenties
• sync_integrity_check_duration - Tijd voor integriteit check
• objects_with_broken_refs - Aantal objecten met kapotte referenties

Alerts

• 🔴 Critical: > 5% broken references
• 🟡 Warning: > 1% broken references
• 🟢 Info: Broken references count veranderd

Rollout Plan

1. Week 1: Implementeer cleanup tools en monitoring
2. Week 2: Repareer bestaande broken references
3. Week 3: Implementeer preventieve maatregelen
4. Week 4: Test en monitor
5. Week 5: Database-level constraints (optioneel)

Risico's en Mitigatie

Risico	Impact	Mitigatie
Sync performance degradation	Hoog	Batch processing, parallel fetching, caching
Database locks tijdens cleanup	Medium	Off-peak scheduling, batch size limits
False positives in validation	Low	Dry-run mode, manual review
Jira API rate limits	Medium	Rate limiting, exponential backoff

Documentatie Updates

• Update sync engine documentatie
• Update data validation dashboard documentatie
• Create runbook voor broken references cleanup
• Update API documentatie voor nieuwe endpoints