netgescon-day0/docs/sviluppo/scambio.md

# Checklist operativa `.200` -> `.202` Mini AI

Questa checklist serve sulla macchina `.200` per verificare che la mini AI della `.202` sia davvero attiva, raggiungibile e letta correttamente da NetGescon.

## Obiettivo

Verificare tre punti distinti:

1. la configurazione Laravel/NetGescon sulla `.200`
2. la raggiungibilita HTTP della mini AI sulla `.202`
3. il funzionamento del comando applicativo `netgescon:mini-ai-incassi`

Se uno di questi tre passaggi fallisce, la UI puo mostrare messaggi come:

- `Mini AI non abilitata`
- `Q/A #22 · Mini AI non abilitata: impostare MINI_AI_ENABLED=true`

## Configurazione attesa nel `.env` della `.200`

Nel file `.env` del progetto NetGescon devono essere presenti almeno queste variabili:

```env
MINI_AI_ENABLED=true
MINI_AI_BASE_URL=http://192.168.0.202:8000
MINI_AI_RECONCILIATION_PATH=/api/v1/reconciliation/incassi
MINI_AI_TIMEOUT=30
```

Se sulla `.202` e attiva autenticazione bearer, aggiungere anche:

```env
MINI_AI_TOKEN=<token-locale-della-202>
```

## 1. Verifica del file `.env`

Dal root del progetto NetGescon sulla `.200`:

```bash
grep -E 'MINI_AI_ENABLED|MINI_AI_BASE_URL|MINI_AI_RECONCILIATION_PATH|MINI_AI_TIMEOUT|MINI_AI_TOKEN' .env
```

Controlli attesi:

- `MINI_AI_ENABLED=true`
- `MINI_AI_BASE_URL=http://192.168.0.202:8000`
- `MINI_AI_RECONCILIATION_PATH=/api/v1/reconciliation/incassi`

## 2. Pulizia cache Laravel

Se il file `.env` e corretto ma la UI continua a dire che la mini AI non e abilitata, svuotare la cache configurazione:

```bash
php artisan config:clear
php artisan cache:clear
```

## 3. Verifica configurazione letta da Laravel

Eseguire:

```bash
php artisan tinker --execute='dump(config("services.mini_ai"));'
```

Esito atteso minimo:

```php
array:4 [
  "enabled" => true
  "base_url" => "http://192.168.0.202:8000"
  "reconciliation_path" => "/api/v1/reconciliation/incassi"
  "timeout" => 30
]
```

Se `enabled` risulta `false` o `null`, il problema e interno alla `.200` e non dipende dalla `.202`.

## 4. Test HTTP diretto verso la `.202`

Questo test bypassa Laravel e verifica solo che la `.202` risponda davvero.

```bash
curl -sS -X POST 'http://192.168.0.202:8000/api/v1/reconciliation/incassi' \
  -H 'Content-Type: application/json' \
  -d '{
    "task": "reconcile_incassi_movimenti_bancari",
    "mode": "read_only_suggestions",
    "snapshot": {
      "records": [
        {
          "legacy_key": "inc:test",
          "incasso_id": 1,
          "importo": 10.00,
          "data": "2025-04-30",
          "descrizione": "Canone mensile banca aprile"
        }
      ]
    }
  }'
```

Esito atteso:

```json
{
  "summary": "1 record analizzati; 1 ignore.",
  "warnings": [
    "Alcuni record sono stati classificati come spese bancarie o non riconciliabili."
  ],
  "suggestions": [
    {
      "legacy_key": "inc:test",
      "confidence": 0.98,
      "suggested_incasso_id": 1,
      "suggested_movimento_id": null,
      "suggested_action": "ignore",
      "reason": "Caso facile: spesa bancaria ricorrente o onere banca; non va collegato a incassi condominiali."
    }
  ]
}
```

Se questo `curl` fallisce, il problema e di rete o endpoint. Se invece funziona, la `.202` e sana.

## 5. Test comando NetGescon a secco

Una volta verificata la config, eseguire:

```bash
php artisan netgescon:mini-ai-incassi --codice-stabile=0016 --limit=2 --dry-run
```

Se il comando e configurato correttamente, deve:

- generare la richiesta
- inviare la POST alla `.202`
- ricevere una risposta JSON valida
- salvare il traffico in `ai_requests`

## 6. Test con caso reale `mov:15523`

```bash
php artisan netgescon:mini-ai-incassi --movimento-id=15523 --limit=30 --dry-run > payload-barone-15523.json

curl -sS -X POST 'http://192.168.0.202:8000/api/v1/reconciliation/incassi' \
  -H 'Content-Type: application/json' \
  -d @payload-barone-15523.json
```

Esito atteso sintetico:

- `legacy_key = mov:15523`
- `suggested_movimento_id = 15523`
- `suggested_action = link`
- `confidence ~= 0.98`
- `allocations[]` valorizzato
- totale `allocations.amount = 1285.70`

## 7. Test con caso reale `mov:15953`

```bash
php artisan netgescon:mini-ai-incassi --movimento-id=15953 --limit=40 --dry-run > payload-barone-15953.json

curl -sS -X POST 'http://192.168.0.202:8000/api/v1/reconciliation/incassi' \
  -H 'Content-Type: application/json' \
  -d @payload-barone-15953.json
```

Esito atteso sintetico:

- `legacy_key = mov:15953`
- `suggested_movimento_id = 15953`
- `suggested_action = link`
- `confidence ~= 0.98`
- `allocations[]` valorizzato
- presente conguaglio negativo `rate_id=42546 amount=-0.61`
- totale `allocations.amount = 960.79`

## 8. Test con caso alias `mov:15803`

```bash
php artisan netgescon:mini-ai-incassi --movimento-id=15803 --limit=40 --dry-run > payload-curatola-15803.json

curl -sS -X POST 'http://192.168.0.202:8000/api/v1/reconciliation/incassi' \
  -H 'Content-Type: application/json' \
  -d @payload-curatola-15803.json
```

Esito atteso sintetico:

- `legacy_key = mov:15803`
- `suggested_movimento_id = 15803`
- `suggested_action = link`
- `confidence ~= 0.98`
- `allocations[]` con 12 rate
- totale `allocations.amount = 1968.23`
- il motivo puo citare la coerenza di `payer_reference` e alias anagrafici

## 9. Diagnosi rapida per errore `Mini AI non abilitata`

Se compare ancora il messaggio:

- `Mini AI non abilitata`

allora il problema e quasi certamente questo:

1. `MINI_AI_ENABLED` non e presente o non e `true`
2. Laravel usa ancora config cache vecchia
3. il codice della `.200` legge un path config diverso dal `.env`

Controllo minimo:

```bash
php artisan tinker --execute='dump(config("services.mini_ai"));'
```

Finche questo comando non mostra `enabled => true`, la `.200` non chiamera la `.202`.

## 10. Se serve prova completa da UI

Dopo i controlli sopra:

1. aprire `admin-filament/contabilita/incassi`
2. verificare che non compaia piu `Mini AI non abilitata`
3. inviare un caso test
4. controllare che `ai_requests` riceva richiesta e risposta

## Criterio finale di ok

Il collegamento `.200` -> `.202` e considerato corretto quando:

- `config("services.mini_ai")` restituisce `enabled => true`
- il `curl` diretto verso `192.168.0.202:8000` risponde JSON valido
- `php artisan netgescon:mini-ai-incassi ...` produce richieste e risposte salvate
- la UI non mostra piu `Mini AI non abilitata`