#39 feat(visura-api): robustezza, performance e retry login pre-produzione

[Anonymous]

Originally created by: zornade
Originally owned by: zornade

Issue collegata

Risolve [#38]

Descrizione

PR di consolidamento del lavoro post-#36 sul branch feat/sister-direct-login: robustezza login/sessione SISTER, normalizzazione nomi province/comuni, performance MVP+MVP-2, retry automatico del login su timeout della push SPID.

Risultato live (97 particelle bulk test, particelle in tutta Italia):

• 6.7s avg / 91.8% success / 0 timeout wait_for_selector
• Da baseline pre-MVP ~10.3s a 6.7s (-35%)

Cosa cambia (sintesi)

Robustezza login SPID

• BrowserManager.login() ora ritenta automaticamente fino a LOGIN_MAX_ATTEMPTS volte (default 3) quando la push SPID non viene approvata in tempo (PlaywrightTimeoutError). Pausa configurabile via LOGIN_RETRY_DELAY_S (default 5s).
• Fail-fast preservato per credenziali errate (15s) — non si ribombarda di push se username/password sono sbagliati.
• Single-flight lock su login concorrente; fix TOCTOU su browser readiness.

Normalizzazione input

• Alias province (Reggio nell'Emilia → Reggio Emilia, Valle d'Aosta/Vallée d'Aoste, Monza e della Brianza, …).
• Match comune case-insensitive + accent-fold.
• codice_belfiore opzionale → match nativo SISTER tramite chiave CB#… (più affidabile del match per nome).
• Fail-fast esplicito su Trento/Bolzano (catasto autonomo).

Performance

• Resource blocking (immagini/font/analytics).
• Dropdown cache TTL + fast_options JS path.
• Cache comuni provincia-scoped (fix poisoning cross-provincia).
• Hot path wait_for_selector(state="attached", timeout=15s) invece di wait_for_load_state(domcontentloaded, 30s).

Resilienza

• TTLCache su risultati visura.
• Fallback T↔F catasto opzionale.
• Rate-limit (HTTP 429) su richieste concorrenti.

Tipo di modifica

• [x] Bug fix (corregge un problema senza rompere funzionalità esistenti)
• [x] Nuova feature (aggiunge funzionalità senza rompere quelle esistenti)
• [ ] Breaking change
• [ ] Documentazione
• [ ] Refactoring (nessun cambio funzionale)

Checklist

• [x] Ho letto CONTRIBUTING.md
• [x] La mia PR è basata sull'ultimo main (ho fatto rebase/merge dopo [#36])
• [x] Ho testato le modifiche localmente (104/104 pytest + bulk test live 97 particelle)
• [x] Il codice passa ruff check . e black --check .
• [ ] Ho aggiornato il CHANGELOG.md (verrà fatto al rilascio versione)
• [x] Ho aggiunto/aggiornato i test (+50 nuovi test pytest)
• [x] Non ho committato credenziali, dati personali o file .env

Uso di strumenti AI

• [x] Ho usato strumenti AI come supporto: GitHub Copilot (Claude) per assistenza alla scrittura del codice, dei test e dei messaggi di commit. Tutto il codice è stato revisionato e validato localmente con test unitari e bulk test live contro l'ambiente reale SISTER.

Log / Numeri

Bulk test v7 (97 particelle, varietà geografica nord/centro/sud):

Total          97
HTTP 200       96/97  (99%)
Success        89/97  (91.8%)
Avg latency    6.7s
P50 latency    5.9s
P95 latency    11.2s
wait_for_selector timeouts  0

Pytest:

104 passed in 0.38s

Note per il reviewer

Il branch contiene 14 commit logicamente distinti (P0 audit, perf MVP, perf MVP-2, cache fix, hot path D, retry login). Suggerito squash merge in modo da avere un singolo commit consolidato su main che riassume "robustezza + performance + retry login pre-produzione".

[Anonymous]

• assigned_to: zornade

[Anonymous]

Ticket changed by: zornade

• status: open --> closed

[Anonymous]

Ticket changed by: zornade

• status: closed --> open

[Anonymous]

Ticket changed by: zornade

• status: open --> closed