Protocollo operativo AI locale – Match Incassi ↔ Unità immobiliari

Data: 2026-03-03 Obiettivo: associare in modo affidabile i movimenti banca/incassi ai nominativi/unità, con gestione casi dubbi e apprendimento supervisionato operatore.

1) Dati da preparare (input)

Per ogni movimento da classificare, inviare all'AI locale un JSON con:

movement_id (id univoco movimento banca/incasso)
data_movimento (YYYY-MM-DD)
importo (positivo/negativo)
descrizione_estesa
causale
iban_conto
riferimento (se presente: rif., CRO/TRN, MAV, ecc.)
condominio_codice / stabile_id
candidate_units (top candidati, max 20) con:
- unita_id
- persona_id
- nominativo
- scala
- interno
- cod_cond_legacy (se disponibile)
- score_regole (score deterministico iniziale)
known_aliases (alias nominativi già noti)
history_last_matches (ultimi movimenti già confermati simili)

2) Prompt consigliato da inviare all'AI locale

Usare questo schema (adattando il JSON):

Sei un assistente di riconciliazione incassi condominiali.
Task: abbina il movimento al miglior candidato tra candidate_units.
Vincoli:
1) Non inventare nominativi fuori da candidate_units.
2) Privilegia match su riferimento esplicito (MAV, CRO/TRN, rif. rata).
3) In caso di parità, usa storico confermato e similarità testuale su descrizione_estesa.
4) Se confidenza < 0.80 rispondi DUBBIO e chiedi intervento operatore.

Restituisci SOLO JSON nel formato richiesto.

INPUT:
<JSON_MOVIMENTO>

3) Formato risposta obbligatorio (output AI)

{
  "movement_id": "...",
  "status": "MATCH|DUBBIO|NO_MATCH",
  "best_candidate": {
    "unita_id": 0,
    "persona_id": 0,
    "nominativo": ""
  },
  "confidence": 0.0,
  "evidenze": [
    "testo breve 1",
    "testo breve 2"
  ],
  "alternative_candidates": [
    {"unita_id": 0, "persona_id": 0, "confidence": 0.0}
  ],
  "operatore_question": "domanda precisa se status=DUBBIO"
}

Regole:

MATCH solo se confidence >= 0.80
DUBBIO se 0.55 <= confidence < 0.80
NO_MATCH se < 0.55

4) Aggancio risposta al gestionale

Pipeline consigliata:

Salva risposta AI su tabella staging (es. ai_incassi_match_suggestions).
Se MATCH: proponi precompilazione associazione con badge "AI" (non auto-confermare senza regola hard).
Se DUBBIO: crea task operatore con domanda/evidenze.
Se NO_MATCH: lascia in coda da lavorare manualmente.

Campi minimi staging:

movement_id, status, unita_id_suggested, persona_id_suggested, confidence, evidenze_json, alternatives_json, raw_response_json, created_at.

5) Feedback loop (apprendimento supervisionato)

Quando l'operatore conferma/corregge:

Scrivere record in ai_incassi_feedback con:
- movement_id
- ai_suggestion
- operatore_esito (confermato/corretto/scartato)
- unita_id_finale, persona_id_finale
- motivo_correzione
Aggiornare alias/lessico interno (known_aliases) con nuove varianti valide.
Rieseguire valutazione periodica (precision@1, % dubbi, % correzioni) per affinare soglie.

6) Politica casi dubbi

Se omonimia o importo uguale su più unità -> DUBBIO obbligatorio.
Se descrizione troppo corta (es. "BONIFICO", "PAGAMENTO") senza altri segnali -> DUBBIO.
Se match storico contraddice anagrafica attuale -> DUBBIO.

7) KPI da monitorare

% MATCH confermati senza correzioni
% DUBBIO risolti al primo passaggio
Tempo medio risoluzione dubbio
% NO_MATCH su totale flusso

Target iniziale realistico:

precision@1 >= 92%
dubbi <= 20%

8) Primo test consigliato (pilot)

Prendi 200 movimenti già quadrati manualmente.
Nascondi etichetta reale e fai predire l'AI.
Confronta output vs verità operatore.
Regola soglie 0.80 / 0.55 solo dopo il pilot.

3.8 KiB Executable File Raw Blame History Unescape Escape