From 9c215b16552bb599131a3d8632dea87e2bcd33c4 Mon Sep 17 00:00:00 2001 From: ReLoia Date: Fri, 19 Jun 2026 23:38:27 +0200 Subject: [PATCH] feat: added README --- README.md | 159 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 106 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 25b5821..9d7efb5 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,128 @@ -# Nuxt Minimal Starter +

+ +Visione +

-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. +# Visione -## Setup +Un'occhio per la sicurezza del cittadino. -Make sure to install dependencies: +**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](https://nuxt.com/) (Vue 3) con rendering SSR attivato. +- **UI / Styling:** [Bootstrap Italia](https://italia.github.io/bootstrap-italia/) per componenti accessibili e conformi + agli standard AGID. +- **Mappe e Georeferenziazione:** [Leaflet](https://leafletjs.com/) 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 ```bash -# npm -npm install - -# pnpm -pnpm install - -# yarn yarn install - -# bun -bun install ``` -## Development Server +### 2. Configurazione Variabili d'Ambiente (.env) -Start the development server on `http://localhost:3000`: +Copia il file di esempio per creare la tua configurazione locale: ```bash -# npm -npm run dev - -# pnpm -pnpm dev - -# yarn -yarn dev - -# bun -bun run dev +cp .env.example .env ``` -## Production +Il file `.env` richiede le seguenti chiavi: -Build the application for production: +- `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 ```bash -# npm -npm run build - -# pnpm -pnpm build - -# yarn -yarn build - -# bun -bun run build +yarn run dev ``` -Locally preview production build: +Il server sarà accessibile all'indirizzo [http://localhost:3000](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: ```bash -# npm -npm run preview - -# pnpm -pnpm preview - -# yarn -yarn preview - -# bun -bun run preview +docker compose up -d --build ``` -Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. +### 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).