frontend/README.md

Visione

Un'occhio per la sicurezza del cittadino.

Visione è una piattaforma progettata per gestire le segnalazioni dei cittadini, implementando un flusso operativo sicuro, trasparente e istituzionalmente conforme.

Punti di Forza e Funzionalità Principali

• Conformità Istituzionale e UX/UI Standardizzata: Il frontend è sviluppato utilizzando Bootstrap Italia (creato da Designers Italia). Questa scelta assicura un'identità visiva coerente con i servizi pubblici italiani, garantendo uniformità, riconoscibilità e accessibilità.
• Trasparenza e Open Data: Il sistema espone un endpoint pubblico Open Data con dataset anonimizzati relativi alle segnalazioni chiuse o risolte, favorendo la trasparenza amministrativa.
• Automazione e Smistamento Intelligente: Il calcolo automatico della "Zona" di competenza tramite le coordinate geografiche elimina i colli di bottiglia durante il triage iniziale, instradando immediatamente la segnalazione all'operatore corretto.
• Sicurezza e Onboarding Smart: L'autenticazione è gestita tramite OTP (One-Time Password) e integrazione con * *CIE (Carta d'Identità Elettronica)**, riducendo l'uso di password statiche e garantendo identità verificate.
• Infrastruttura DevOps e CI/CD: Sfruttiamo un'istanza self-hosted di Gitea per il versionamento del codice e un flusso di deployment automatizzato basato su webhook con Dokploy, assicurando un rilascio continuo e stabile.
• Ottimizzazione SEO e Reperibilità: Configurazione avanzata per sitemap e robots.txt (via @nuxtjs/robots e @nuxtjs/sitemap) per esplicitare chiaramente le pagine pubbliche e separarle dalle aree private.

Tecnologie Utilizzate

Il progetto è costruito su uno stack moderno orientato a performance, accessibilità e manutenibilità:

• Framework Core: Nuxt 4 (Vue 3) con rendering SSR attivato.
• UI / Styling: Bootstrap Italia per componenti accessibili e conformi agli standard AGID.
• Mappe e Georeferenziazione: Leaflet interfacciato con Nominatim/OpenStreetMap per il suggerimento e la validazione degli indirizzi.
• PWA e Ottimizzazione: Modulo @vite-pwa/nuxt per Progressive Web App (manifest auto-generato) e moduli ufficiali Nuxt per icone, font (Google Fonts: Lora, Roboto Mono, Titillium Web) ed elaborazione immagini.
• Infrastruttura: Docker, Docker Compose, NodeJS 22.
• Package Manager: Yarn.

Limiti e Punti di Attenzione

L'attuale architettura presenta alcune criticità e aree di miglioramento individuate durante i test:

1. Rischio di Abuso e Moderazione: L'apertura della piattaforma all'invio di messaggi e allegati potrebbe generare un elevato carico di moderazione. In futuro, andranno valutati filtri automatici o code dedicate.
2. Dipendenza da API Cartografiche di Terze Parti: L'utilizzo di Nominatim/OpenStreetMap per il geocoding esonera dal lock-in di provider commerciali (es. Google Maps), ma introduce dipendenze su disponibilità e policy d'uso di servizi esterni.
3. Barriere all'Ingresso: I flussi OTP e CIE, seppur estremamente sicuri, possono rappresentare un "attrito" ( digital divide) per le fasce di utenza più anziane o meno avvezze agli strumenti digitali.

---

Come utilizzare il progetto (Sviluppo)

Requisiti

• Node.js (v22 o superiore consigliato)
• Yarn (utilizza esclusivamente yarn, non npm)

1. Installazione Dipendenze

yarn install

2. Configurazione Variabili d'Ambiente (.env)

Copia il file di esempio per creare la tua configurazione locale:

cp .env.example .env

Il file .env richiede le seguenti chiavi:

• NUXT_PUBLIC_URL: URL pubblico dell'applicativo frontend (es. http://localhost:3000).
• NUXT_PUBLIC_API: URL base per il backend API (es. http://localhost:5555).

(Nota: il proxy integrato in nuxt.config.ts inoltrerà già le richieste di /api/v1 al target di staging configurato https://api.visionebari.it in ambiente di sviluppo).

3. Avvio del Server di Sviluppo

yarn run dev

Il server sarà accessibile all'indirizzo http://localhost:3000.

---

Distribuzione e Produzione (Docker)

Il progetto è ottimizzato per essere deployato tramite container Docker, sfruttando processi multi-stage per generare un'immagine finale snella e performante basata su node:22-bookworm.

Build locale e avvio tramite Docker Compose

Il file docker-compose.yml espone il servizio visione-frontend.

1. Assicurati che il file .env sia valorizzato correttamente.
2. Esegui il build e avvia in background:

docker compose up -d --build

Dettagli sul Dockerfile

• Fase di Build (AS build): Copia package.json e yarn.lock, esegue yarn install, copia i sorgenti ed esegue yarn run build. Iniettando gli argomenti di environment per le API.
• Fase di Run (AS run): Esegue yarn install --production per alleggerire le dipendenze finali. Trasferisce l'artefatto compilato .output e avvia il webserver sulla porta 80 tramite node /app/server/index.mjs.

Testing e Azioni Migliorative Future

I test attuali coprono con successo i flussi primari (registrazione, autenticazione, gestione segnalazioni, moderazione). Prossimi step suggeriti:

• Consolidamento con test end-to-end (E2E) automatici per le rotte critiche (in particolare CIE/OTP).
• Verifiche di regressione per gli endpoint Open Data per garantirne l'integrità.
• Monitoraggio della qualità del dato geografico (segnalazioni in aree limite).