127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
# 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):
|
||
|
||
```text
|
||
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)
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
1. Salva risposta AI su tabella staging (es. `ai_incassi_match_suggestions`).
|
||
2. Se `MATCH`: proponi precompilazione associazione con badge "AI" (non auto-confermare senza regola hard).
|
||
3. Se `DUBBIO`: crea task operatore con domanda/evidenze.
|
||
4. 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.
|