#15 Roadmap v0.2 — copertura completa endpoint SISTER + CLI + SSE

[Anonymous]

Originally created by: zornade

Visura API oggi copre due endpoint del portale SISTER (visura immobili e visura intestati). Il portale ne offre molti altri che hanno richiesto, dalla community e dall'uso reale, una copertura nativa via API. Questa issue traccia la roadmap della v0.2.

Obiettivi

• Estendere la copertura SISTER agli endpoint mancanti più richiesti.
• Mantenere il progetto focalizzato come wrapper API: niente DB pesante, niente web UI, niente workflow engine. Quelle sono responsabilità di chi costruisce sopra visura-api.
• Aggiungere una CLI ergonomica per uso da terminale.
• Introdurre uno streaming di risultati alternativo al polling.
• Mantenere visura-api operabile anche in modalità read-only, senza credenziali SPID, per consumer che leggono solo da cache.

Non-obiettivi (espliciti)

• ❌ Web UI integrata (templates, frontend, theme).
• ❌ Workflow engine multi-hop / orchestrator / due-diligence pipeline.
• ❌ Schema DB complesso con migrations: al massimo cache opzionale.
• ❌ Autenticazione degli utenti finali del servizio (Clerk, OAuth, SSO).
• ❌ Multi-tenancy, billing, dashboard utenti.

Chi ha bisogno di queste cose le costruisce nel proprio fork commerciale, o acquista una licenza commerciale a hello@zornade.com.

---

Milestone 1 — Endpoint SISTER aggiuntivi 🎯

Endpoint del portale SISTER da esporre via API REST. Ogni endpoint ha un issue dedicato dove discutere selettori, modello Pydantic di risposta e casi edge.

• [ ] Persone Non Fisiche (PNF) — ricerca catasto per partita IVA. Endpoint proposto: POST /visura/pnf. Input: partita_iva. Output: lista immobili intestati.
• [ ] Mappa catastale — estratto di mappa per foglio. Endpoint: POST /mappa. Input: provincia, comune, foglio, eventuale particella. Output: immagine + metadata.
• [ ] Export Mappa — esportazione formato standard (PDF / DXF / shape). Endpoint: POST /mappa/export. Input: come sopra + formato. Output: link al file o stream.
• [ ] Elaborato Planimetrico — planimetria di fabbricato/U.I.U. Endpoint: POST /planimetrico. Input: provincia, comune, foglio, particella, subalterno. Output: PDF + metadata.
• [ ] Ispezioni ipotecarie — visure ipotecarie da Conservatoria. Endpoint: POST /ipotecaria. Input: cf/piva del soggetto oppure riferimento immobile. Output: nota / formalità trovate.
• [ ] Riepilogo richieste — riepilogo storico di richieste sul portale. Endpoint: GET /riepilogo. Output: lista paginata richieste degli ultimi N giorni.
• [ ] Stato richieste asincrone — molti endpoint SISTER restituiscono un ID richiesta + esito differito. Endpoint: GET /richieste/{id}.

⚠️ Per ogni nuovo endpoint serve verifica diretta sul portale SISTER da account CONSULTAZIONI - PROFILO B. Apri una issue figlia prima di scrivere codice.

---

Milestone 2 — Streaming e ergonomia client

• [ ] SSE streaming — endpoint alternativo a polling per risultati lunghi. Proposta: GET /visura/{id}/stream come Server-Sent Events. Il polling attuale GET /visura/{id} resta supportato.
• [ ] CAPTCHA handling — SISTER occasionalmente serve un captcha. Detect + retry con back-off, log esplicito quando intervento manuale necessario.
• [ ] Document download — recupero opzionale del PDF generato dal portale. ⚠️ Decidere prima la policy di retention GDPR (vedi Milestone 5).

---

Milestone 3 — CLI

• [ ] visura CLI in Python (Typer) come modulo del package. Comandi minimi:
• visura immobili <provincia> <comune> <foglio> <particella>
• visura intestati <request_id> <subalterno>
• visura pnf <partita_iva>
• visura status <request_id>
• visura health
• [ ] Pubblicazione su PyPI come visura-api con entry point visura.

---

Milestone 4 — Modalità read-only e cache opzionale

• [ ] Flag READ_ONLY=true — il servizio parte senza credenziali SPID, espone solo GET su risultati già in cache. Utile per UI separate e per test.
• [ ] Cache in-memory con TTL — chiave (provincia, comune, foglio, particella, sub?), TTL 24h di default. Disabilitabile via CACHE_TTL=0.
• [ ] Persistenza opzionale via SQLite — solo se attivata da PERSIST_RESPONSES=true. Schema minimale, niente Alembic. Default off per evitare scope creep e responsabilità GDPR su chi non le vuole.

---

Milestone 5 — Compliance e qualità

• [ ] GDPR policy in README.md: dichiarazione esplicita che i dati estratti sono dati personali, raccomandazioni per retention, anonymization dei log HTML in logs/pages/.
• [ ] Mascheramento PII opzionale nei log HTML (MASK_PII=true): sostituisce nominativi, codici fiscali, indirizzi con placeholder.
• [ ] Test di regressione sui form selectors di ciascun endpoint SISTER. Eseguibili manualmente con credenziali reali (non in CI).
• [ ] Refactor: estrai BrowserManager da main.py in visura_api/browser.py per ridurre la dimensione del modulo principale.

---

Contribuire

PR benvenute, a queste condizioni:

1. Apri prima la issue figlia legata all'endpoint o feature che vuoi implementare. Discuti l'API proposta prima di scrivere codice.
2. Firma i commit con DCO (git commit --signoff).
3. Accetta la clausola di relicensing descritta in CONTRIBUTING.md (modello dual-license, identico a MongoDB / Elastic / Grafana).
4. Non riusare codice da fork AGPL di terze parti senza accordo scritto: le tue implementazioni devono essere autonome.

Se non puoi/non vuoi rispettare uno di questi punti, scrivici a hello@zornade.com: troviamo un'alternativa (es. plugin esterno, licenza commerciale).

---

Timeline indicativa

Milestone	Target
M1 — endpoint SISTER (PNF, Mappa, Planimetrico, Ipotecaria)	giugno 2026
M2 — SSE + CAPTCHA + document download	luglio 2026
M3 — CLI + PyPI release	agosto 2026
M4 — read-only mode + cache	autunno 2026
M5 — GDPR + masking + selector regression tests	rolling

Non sono impegni contrattuali. Roadmap revisionata mensilmente in base a priorità e contribuzioni.