# 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.