feat: added README
This commit is contained in:
@@ -1,75 +1,128 @@
|
||||
# Nuxt Minimal Starter
|
||||
<p align="center">
|
||||
<img src="https://git.reloia.uk/SnitchItaly/frontend/raw/branch/master/public/icon-512.webp" width="128" height="128" align="right">
|
||||
Visione
|
||||
</p>
|
||||
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user