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:

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:

MINI_AI_TOKEN=<token-locale-della-202>

1. Verifica del file .env

Dal root del progetto NetGescon sulla .200:

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:

php artisan config:clear
php artisan cache:clear

3. Verifica configurazione letta da Laravel

Eseguire:

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

Esito atteso minimo:

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.

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:

{
  "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:

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

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

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

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:

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