Sistema Avanzato di Gestione Duplicati - Movimenti Bancari

📋 Panoramica

Il nuovo sistema utilizza un approccio multi-livello per rilevare e gestire i duplicati nei movimenti bancari, risolvendo i problemi dell’hash MD5 singolo troppo rigido.

🎯 Caratteristiche Principali

1. Fingerprinting Multiplo

Ogni transazione bancaria viene identificata con 4 hash diversi:

Hash	Descrizione	Utilizzo
`exactHash`	Hash esatto (data + desc normalizzata + importo)	Duplicati identici
`fuzzyHash`	Hash fuzzy (keywords descrizione + importo arrotondato)	Variazioni nella descrizione
`amountDateHash`	Hash data+importo (ignora descrizione)	Descrizioni molto diverse
`transactionHash`	Legacy hash (backward compatibility)	Compatibilità

2. Livelli di Rilevamento Duplicati

🔴 EXACT DUPLICATE (Confidence: 100%)

Hash esatto identico
Azione: Merge automatico dei dati migliorabili

🟡 NEAR DUPLICATE (Confidence: >85%)

Criteri:

Data: ±3 giorni
Descrizione: similarity >85%
Importo: ±5%

Azione:

Confidence >90%: Merge automatico
Confidence 85-90%: Crea nuovo ma logga per review

🟢 POSSIBLE DUPLICATE (Confidence: >50%)

Criteri:

Data: ±7 giorni
Descrizione: similarity >50%
Importo: ±5%

Azione: Crea nuovo (futura implementazione: review queue)

⚪ UNIQUE

Nessun duplicato trovato - transazione nuova

3. Merge Intelligente

Quando viene rilevato un duplicato esatto o near (high confidence), il sistema:

✅ Mantiene i campi critici dell’esistente (data, importo)
✅ Usa la descrizione più lunga/dettagliata
✅ Combina le note (senza duplicare)
✅ Usa la categoria migliore (non “uncategorized”)
✅ Merge AI suggestions (usa il più confident)
✅ Aggiunge info bancarie se mancanti

📊 Esempi di Rilevamento

Esempio 1: Exact Duplicate


Transazione A: 2025-01-15 | "BONIFICO FORNITORE ABC SRL" | -1250.00€
Transazione B: 2025-01-15 | "bonifico fornitore abc srl  " | -1250.00€

✅ Risultato: EXACT DUPLICATE (Hash esatto identico dopo normalizzazione)

Esempio 2: Near Duplicate


Transazione A: 2025-01-15 | "PAGAMENTO FATTURA 123/2025 ABC" | -1250.00€
Transazione B: 2025-01-16 | "PAGAMENTO FT 123/2025 ABC SRL" | -1250.50€

✅ Risultato: NEAR DUPLICATE
   - Date diff: 1 giorno
   - Desc similarity: 87%
   - Amount diff: 0.04%
   - Confidence: 0.91 → Auto-merge

Esempio 3: Possible Duplicate


Transazione A: 2025-01-15 | "BONIFICO FORNITORE XYZ" | -500.00€
Transazione B: 2025-01-20 | "ADDEBITO FORNITORE XYZ SPA" | -502.50€

⚠️ Risultato: POSSIBLE DUPLICATE
   - Date diff: 5 giorni
   - Desc similarity: 62%
   - Amount diff: 0.5%
   - Confidence: 0.67 → Crea nuovo (review futura)

🛠️ File Modificati/Creati

Modelli

✅ backend/models/BankTransaction.ts - Aggiornato con nuovi fingerprints

Utility

✅ src/lib/bankTransactionFingerprinting.ts - Generazione hash e normalizzazione
✅ src/lib/bankTransactionDuplicateDetection.ts - Rilevamento multi-livello

Workers

✅ src/workers/bankStatementProcessWorker.ts - Logica di import con merge

Scripts

✅ scripts/migrate-add-fingerprints.js - Migrazione transazioni esistenti
✅ scripts/test-duplicate-detection.js - Test del sistema

🚀 Deployment e Migrazione

1. Eseguire Migrazione Dati Esistenti


npm run script:migrate-fingerprints
# o
node scripts/migrate-add-fingerprints.js

Questo aggiornerà tutte le transazioni esistenti con i nuovi fingerprints.

2. Verificare la Migrazione


npm run script:test-duplicates
# o
node scripts/test-duplicate-detection.js

3. Monitorare i Log

I worker ora loggano:

Nuove transazioni salvate
Duplicati esatti trovati e merged
Near duplicates con confidence score
Statistiche finali

Esempio log:


[BankStatementWorker] Completed: 150 new, 45 duplicates (30 merged, 15 near-duplicates)

📈 Statistiche e Report

Il sistema ora traccia:

savedCount: Nuove transazioni create
duplicateCount: Duplicati totali trovati
mergedCount: Duplicati merged con dati migliorati
nearDuplicateCount: Near duplicates rilevati
reviewQueueCount: Duplicati incerti aggiunti alla review queue

Queste statistiche vengono restituite dal worker e possono essere visualizzate nell’UI.

🔮 Sviluppi

✅ Fase 2: Review Queue UI (IMPLEMENTATO)

Caratteristiche:

✅ Dashboard /duplicati-bancari per gestire duplicati incerti
✅ Interfaccia per approvare/rifiutare/merge transazioni
✅ Visualizzazione confidence scores e differenze
✅ Storico decisioni per tracciamento
✅ API REST completa per gestione review

Endpoints:

GET /api/duplicate-reviews - Lista reviews con filtri
GET /api/duplicate-reviews/[id] - Dettaglio singola review
PATCH /api/duplicate-reviews/[id] - Decisione su review
DELETE /api/duplicate-reviews/[id] - Elimina review

Modello DuplicateReview:


{
  newTransaction: {...},
  possibleDuplicates: [...],
  status: "pending" | "approved" | "merged" | "rejected",
  decision: {
    action: "import_as_new" | "skip" | "merge_with",
    reason?: string,
    decidedBy: userId,
    decidedAt: Date
  },
  priority: "high" | "medium" | "low"
}

Fase 3: Pattern Learning (FUTURO)

Apprendimento automatico dei pattern di duplicazione per banca
Auto-risoluzione basata su decisioni precedenti
Confidence score adattivi per tenant

Fase 4: Bulk Operations

Import in batch con preview duplicati
Azioni bulk: “Merge tutti high confidence”
Rollback transazioni importate

⚙️ Configurazione

Soglie Personalizzabili (futuro)


const DUPLICATE_CONFIG = {
  nearDuplicate: {
    maxDateDiff: 3, // giorni
    minDescSimilarity: 0.85, // 85%
    maxAmountDiff: 5, // 5%
    autoMergeThreshold: 0.9, // 90% confidence
  },
  possibleDuplicate: {
    maxDateDiff: 7,
    minDescSimilarity: 0.5,
    maxAmountDiff: 5,
  },
};

🐛 Troubleshooting

Troppi falsi positivi (transazioni diverse marcate come duplicati)

Aumentare minDescSimilarity
Ridurre maxDateDiff
Aumentare autoMergeThreshold

Troppi falsi negativi (duplicati reali non rilevati)

Ridurre minDescSimilarity
Aumentare maxDateDiff
Verificare normalizzazione descrizioni

Performance lente su grandi volumi

Assicurarsi che gli indici MongoDB siano creati:
```
db.banktransactions.getIndexes();
```
Dovrebbero esistere indici su:
- { tenant_id: 1, exactHash: 1 }
- { tenant_id: 1, fuzzyHash: 1 }
- { tenant_id: 1, amountDateHash: 1 }

📝 Note Tecniche

Normalizzazione Descrizioni

La funzione normalizeDescription() applica:

Lowercase
Trim spazi
Spazi multipli → singolo spazio
Rimozione caratteri speciali (mantiene lettere, numeri, €, $)
Rimozione timestamp e date embedded

Calcolo Similarity

Usa Levenshtein Distance per calcolare la similarity tra stringhe:


similarity = (len(longer) - editDistance) / len(longer)

Hash MD5

Tutti gli hash usano MD5 per:

Velocità di calcolo
Dimensione fissa (32 caratteri hex)
Non serve crittografia (solo identificazione)

🎓 Best Practices

Reimportazioni: Ora puoi reimportare estratti conto senza creare duplicati
Dati Migliorati: Le reimportazioni migliorano i dati esistenti (categorizzazione, note)
Monitoraggio: Controlla regolarmente i log per confidence scores bassi
Review Periodica: Usa gli script di check per identificare pattern

Versione: 1.0.0
Data: Dicembre 2025
Autore: Sistema FoodCost