Fase 2: Review Queue - Guida Utente

🎯 Panoramica

La Review Queue è il sistema di gestione manuale dei duplicati bancari incerti. Quando il sistema rileva una transazione che potrebbe essere un duplicato con confidence medio-bassa (70-90%), invece di crearla automaticamente o mergiarla, la aggiunge alla review queue per una decisione umana.

📊 Quando una transazione va in Review Queue?

Criteri di Invio alla Queue

1. Near Duplicate con Confidence 0.7-0.9
   • Data: ±3 giorni
   • Descrizione similarity: 85-95%
   • Importo: ±5%
2. Possible Duplicate
   • Data: ±7 giorni
   • Descrizione similarity: 50-85%
   • Importo: ±5%

Criteri di Auto-Merge (NON vanno in queue)

• Exact Duplicate: Hash identico → merge automatico
• Near Duplicate con Confidence >0.9: Molto simile → merge automatico

🖥️ Interfaccia Utente

Accesso alla Dashboard

Vai su: /duplicati-bancari

Sezioni della Dashboard

1. Statistiche: 4 card con conteggi

   • In Attesa (🟠)
   • Approvati (✅)
   • Merged (🔵)
   • Rifiutati (❌)

2. Tabs:

   • In Attesa: Transazioni da revisionare
   • Approvati: Transazioni importate come nuove
   • Merged: Transazioni unite ad esistenti
   • Rifiutati: Transazioni ignorate

Card di Review

Ogni card mostra:

Nuova Transazione:

• Data
• Descrizione
• Importo
• Priorità (Alta/Media/Bassa)

Possibili Duplicati Trovati:

• Confidence score
• Similarity descrizione
• Differenza data (in giorni)
• Differenza importo (%)
• Differenze specifiche

Azioni Disponibili:

1. ✅ Importa come Nuova - Crea una nuova transazione
2. 🔄 Unisci con questa - Merge con transazione esistente specifica
3. ❌ Ignora - Non importare

🎬 Flusso di Lavoro

Passo 1: Import Estratto Conto

Utente carica PDF estratto conto
    ↓
Worker analizza con OpenAI
    ↓
Per ogni transazione estratta:
    ↓
Sistema rileva duplicati
    ↓
Se Confidence 70-90% → Review Queue

Passo 2: Revisione

Utente apre /duplicati-bancari
    ↓
Visualizza transazioni pending
    ↓
Ordinate per priorità (alta → bassa)
    ↓
Esamina ogni caso

Passo 3: Decisione

Utente clicca azione desiderata
    ↓
Si apre dialog di conferma
    ↓
Aggiunge motivo opzionale
    ↓
Conferma
    ↓
Sistema esegue azione

Passo 4: Risultato

• Importa come Nuova: Transazione creata in DB
• Merge: Dati combinati in transazione esistente
• Ignora: Nessuna azione, marcato come rejected

💡 Best Practices

Quando Importare come Nuova

• Transazioni legittime che sembrano simili ma sono distinte
• Pagamenti ricorrenti allo stesso fornitore
• Transazioni con importi molto simili ma scopi diversi

Quando Fare Merge

• Stessa transazione registrata con piccole variazioni
• Differenze solo in formattazione/timestamp
• Confidence >80% e differenze trascurabili

Quando Ignorare

• Duplicati certi già presenti
• Transazioni di test
• Errori di estrazione PDF

📱 API Usage

Fetch Reviews

GET /api/duplicate-reviews?status=pending&page=1&limit=20
 
Response:
{
  success: true,
  reviews: [...],
  pagination: { page, limit, total, pages },
  counts: { pending, approved, merged, rejected }
}

Update Review

PATCH /api/duplicate-reviews/[id]
 
Body:
{
  action: "import_as_new" | "skip" | "merge_with",
  mergeTargetId?: string,  // Required for merge_with
  reason?: string
}
 
Response:
{
  success: true,
  review: {...},
  result: { transactionId } | { mergedInto } | { skipped }
}

🔍 Esempi Pratici

Esempio 1: Pagamento Fornitore Duplicato

Nuova Transazione:

Data: 2025-01-15
Descrizione: "BONIFICO FORNITORE ABC SRL FT 123/2025"
Importo: -1250.00€

Possibile Duplicato:

Data: 2025-01-15
Descrizione: "PAGAMENTO ABC SRL FATTURA 123"
Importo: -1250.00€
Confidence: 87%

Decisione Consigliata: ✅ Merge (stesso pagamento, descrizione diversa)

Esempio 2: Pagamento Ricorrente

Nuova Transazione:

Data: 2025-01-15
Descrizione: "AFFITTO GENNAIO 2025"
Importo: -1500.00€

Possibile Duplicato:

Data: 2024-12-15
Descrizione: "AFFITTO DICEMBRE 2024"
Importo: -1500.00€
Confidence: 75%

Decisione Consigliata: ✅ Importa come Nuova (pagamenti mensili distinti)

Esempio 3: Errore Estrazione

Nuova Transazione:

Data: 2025-01-15
Descrizione: "TOTALE PAGINA 123.45"  ← Errore OCR
Importo: -123.45€

Possibile Duplicato:

Data: 2025-01-14
Descrizione: "COMMISSIONE BANCARIA"
Importo: -123.45€
Confidence: 52%

Decisione Consigliata: ❌ Ignora (errore di estrazione PDF)

🎓 Tips

1. Priorità: Inizia dalle review “Alta priorità” (confidence >85%)
2. Motivi: Aggiungi sempre un motivo per decisioni non ovvie
3. Batch: Processa review simili insieme (es. tutti i pagamenti affitto)
4. Verifica: Dopo merge, controlla la transazione risultante
5. Pattern: Nota pattern ricorrenti per miglioramenti futuri

🔧 Configurazione Worker

Il worker usa queste soglie (modificabili in futuro):

// Auto-merge
if (confidence > 0.9) → Merge automatico
 
// Review Queue
if (0.7 <= confidence <= 0.9) → Review Queue
 
// Auto-create
if (confidence < 0.7 && possible_duplicates.length > 0) → Review Queue
else → Crea nuova

📊 Monitoring

Statistiche da Monitorare

1. Pending Count: Se cresce troppo, ridurre soglie
2. Approved/Merged Ratio: Se >80% approved → soglie troppo permissive
3. High Priority %: Se >50% → confidence thresholds da ottimizzare

Script di Test

# Verifica stato review queue
npx tsx scripts/test-review-queue.js
 
# Output mostra:
# - Conteggi per status
# - Esempi di review pending
# - Distribuzione priorità

🚀 Prossimi Sviluppi

1. Bulk Actions: Approva/rifiuta multipli contemporaneamente
2. Auto-Learn: ML che apprende dalle decisioni umane
3. Filtri Avanzati: Per banca, categoria, range date
4. Export: CSV delle decisioni per audit

Versione: 2.0.0 (Fase 2)
Data: Dicembre 2025