backend/docs/TRACCIA.md

Traccia principale del progetto: Caso di studio Segnalazioni urbane Un’amministrazione comunale desidera sviluppare un sistema digitale per permettere ai cittadini di segnalare problemi presenti sul territorio, come buche stradali, illuminazione guasta, rifiuti abbandonati o altri disservizi urbani, con l’obiettivo di migliorare la gestione degli interventi e la qualità della vita in città.

Il sistema deve prevedere due principali tipologie di utenti: da un lato i cittadini, che inviano segnalazioni, dall’altro gli operatori comunali, responsabili della gestione e risoluzione degli interventi.

I cittadini devono potersi registrare e accedere tramite credenziali personali. Una volta autenticati, devono poter inserire una nuova segnalazione specificando il tipo di problema, la posizione e una breve descrizione. Il sistema deve memorizzare le segnalazioni e permettere ai cittadini di visualizzarne lo stato nel tempo, ad esempio in attesa, in lavorazione o risolta.

Gli utenti devono inoltre poter consultare le segnalazioni già presenti, eventualmente filtrandole per categoria o area, e fornire un feedback sull’efficacia degli interventi effettuati.

Dal lato degli operatori comunali, il sistema deve consentire di visualizzare tutte le segnalazioni ricevute, assegnarle a specifiche squadre di intervento e aggiornarne lo stato man mano che vengono gestite. Deve essere possibile monitorare i tempi di risposta e individuare le aree della città con maggior concentrazione di problemi.

Il sistema deve mantenere uno storico delle segnalazioni e degli interventi effettuati, permettendo all’amministrazione di analizzare i dati raccolti per pianificare interventi futuri e migliorare l’efficienza dei servizi.

Dopodichè ho elaborato una serie di feature che il sistema deve implementare anche rielaborazione e idee. ovvero: Feature Segnalazioni urbane – Lo sviluppo del della webapp avverrà su una istanza self hosted di Gitea come gesto di ribellione nei confronti di github che userà i dati sulle repo per trainare i modelli di IA (lo faceva già prima ma ora lo dice) – Il progetto sarà diviso tra frontend e backend. Frontend in probabilmente Vue.js e backend in C++, nello specifico Dragon è stato scelto come framework. Abbiamo scelto di sviluppare una webapp perchè il punto importante di un progetto del genere è la versatilità, la compatibilità su tutti i sistemi e la velocità. – Deve esistere un account amministratore generato dal sistema. Questo profilo lo dovrà teoricamente avere solo chi il tecnico che gestisce la piattaforma di quel comune, dato che da questo profilo si può fare tutto. E’ diverso da un account operatore perchè l’operatore ha meno permessi rispetto ad un admin, l’admin può decidere chi sono gli operatori. (NOTA: eventualmente ci possono essere i permessi customizzabili, quindi l’admin può creare anche altri utenti che hanno permessi in più) – Deve essere possibile registrarsi alla piattaforma con tutti i quanti i dati anagrafici possibili e immaginabili, sarebbe figo avere un sistema che dato il codice fiscale ti auto completa i dati deducibili da quest’ultimo. Integrazione frontend con google maps per l’indirizzo. Deve essere possibile anche collegare CIE. Nella registrazione si richiede verifica a due fattori – Il login deve essere effettuato con email o CIE. Nel caso di email la modalità di default usa OTP, in quanto dimostrato essere più sicuro. – Una volta registrati, se siamo un operatore (comunale, poliziotto, pompiere o chiunque) sarà un admin o un’altro operatore con abbastanza permessi ad assegnarci a quel ruolo e sbloccare i permessi per accedere ad altre parti della piattaforma. – Admin/operatori vari devono poter creare le varie zone in base al perimetro, se questo è fattibile tramite una mappa sarebbe l’ideale, assegnare i vari nomi ecc.. Questo serve sia per le segnalazioni e per l’assegnazione dell’agente/squadra che deve intervenire sia per fini statistici – Al sito non si registrano solo gli agenti che intervengono o gli operatori ma anche i cittadini, che possono effettuare delle segnalazioni. Le segnalazioni devono avere una foto, la posizione con coordinate geografiche e via con numero. Il sistema automaticamente capisce a che zona del comune fa parte – Quando viene creata una segnalazione c’è un indicatore dello stato, tipo: APERTA, IN REVISIONE, AGENTI IN ARRIVO, RISOLTA (sono esempi, vanno migliorati). Di default viene assegnato APERTA. – Nella segnalazione c’è una chat che viene fatta tra l’operatore e il cittadino per fare eventuali domande. L’operatore quindi può aggiornare lo stato, scrivere messaggi, segnalare il cittadino perchè magari ha inviato un pene come segnalazione. – L’agente riceverà un summary della segnalazione + numero di telefono di chi ha segnalato, dato che intervengono sul posto non serve che loro chattano, chiamano direttamente. – La webapp deve avere una pagina con una serie di statistiche – Si può implementare anche una specie di gamification (indiretta, non diciamolo in maniera ovvia nel sito) del sistema per renderlo più interattivo, tipo ogni segnalazione valida vale dei punti che se accumulati portano a buoni / sconti. – L’utente e gli operatori devono poter aggiungere anche dei filtri quando si cercano le varie segnalazioni. Inoltre il cittadino deve anche poter lasciare un feedback sull’intervento che hanno fatto, questo sarà collegato quindi anche all’operatore e agli agenti della squadra che sono intervenuti. – L’operatore deve poter vedere le varie segnalazioni che sta gestendo e anche quelle di altri operatori ma senza poterci interagire / modificarle. – Tutti vedono e possono prendere in carico le segnalazioni aperte.

In aggiunta come feature opzionali e secondarie sarebbe carino implementare:

• Notifiche Multicanale: Obbligare il cittadino a rientrare nell'app per controllare lo stato della segnalazione genera frustrazione. Potresti implementare notifiche via Email o l'integrazione con un Bot Telegram/WhatsApp che avvisa automaticamente l'utente quando lo stato passa da "In Lavorazione" a "Risolta".
• Routing Intelligente: Sfruttando le API delle mappe, il sistema potrebbe calcolare per la squadra operativa il percorso ottimale per risolvere 4 o 5 segnalazioni assegnate nella stessa giornata, minimizzando i tempi di spostamento
• Portale Open Data: Le amministrazioni amano promuovere la trasparenza. Potresti creare una pagina pubblica dove chiunque (cittadini, giornalisti, ricercatori) può scaricare un dataset anonimizzato con l'elenco dei disservizi risolti nell'ultimo anno, esportabile in formati standard come JSON o CSV.

Un mio collega ha definito questo schema per il database, possiamo e dobbiamo sicuramente modificarlo ma può essere un buon punto di partenza: erDiagram UTENTE ||--o{ SEGNALAZIONE : "manda" %%citatdino UTENTE ||--o{ STORICO_STATO : "aggiorna" %%operatore UTENTE ||--o{ ASSEGNAZIONE : "assegna " %%operatore UTENTE ||--o{ FEEDBACK : "lascia " %%citatdino UTENTE ||--o{ MESSAGGIO : "scrive"

CATEGORIA_SEGNALAZIONE ||--o{ SEGNALAZIONE : "classifica"
AREA ||--o{ SEGNALAZIONE : "localizza"
AREA ||--o{ SQUADRA : "ha"
%%che relaziobne diu merda

CATEGORIA_SQUADRA ||--o{ SQUADRA : "ha"

SEGNALAZIONE ||--o{ STORICO_STATO : "traccia"
SEGNALAZIONE ||--o{ ASSEGNAZIONE : "riceve"
SEGNALAZIONE ||--o| FEEDBACK : "valutata"
SEGNALAZIONE ||--o{ FOTO_SEGNALAZIONE : "documentata"
SEGNALAZIONE ||--o{ MESSAGGIO : "discussa"

SQUADRA ||--o{ ASSEGNAZIONE : "incaricata"

UTENTE {
    int id PK
    string nome
    string cognome
    string email UK
    string codice_fiscale UK
    date data_nascita
    string luogo_nascita
    enum ruolo
    string telefono
    datetime data_registrazione
    int punti
    boolean bannato
}

CATEGORIA_SEGNALAZIONE {
    int id PK
    string nome 
    text descrizione
}

AREA {
    int id PK
    string nome_quartiere
    text descrizione
    geometry coordinate_poligono
    %%bho
}

CATEGORIA_SQUADRA {
    int id PK
    string nome 
    text descrizione
}

SEGNALAZIONE {
    int id PK
    int utente_id FK
    int categoria_id FK
    int area_id FK
    decimal latitudine
    decimal longitudine
    string indirizzo
    text descrizione
    enum stato
    datetime data_creazione
    datetime data_ultima_modifica
}

STORICO_STATO {
    int id PK
    int segnalazione_id FK
    datetime data
    int operatore_id FK
    text note
}

SQUADRA {
    int id PK
    int categoria_squadra_id FK
    int area_id FK
    string nome
    text descrizione
    boolean attiva
}


ASSEGNAZIONE {
    int id PK
    int segnalazione_id FK
    int squadra_id FK
    int operatore_assegnante_id FK
    datetime data_assegnazione
    datetime data_cessazione

}

FEEDBACK {
    int id PK
    int segnalazione_id FK, UK
    int utente_id FK
    int  voto
    %%??
    text commento
    datetime data
}

FOTO_SEGNALAZIONE {
    int id PK
    int segnalazione_id FK
    string url
    datetime data_upload
}

MESSAGGIO {
    int id PK
    int segnalazione_id FK
    int utente_id FK
    text testo
    datetime data_invio
}