Coding Standards¶

Convenzioni di Naming¶

Package¶

Il progetto usa due tradizioni di naming che coesistono:

Tradizione	Pattern	Moduli
Legacy	`com.mdatasystem.geco.*`	GeCo.Alfa, GecoService
Legacy	`it.mdatasystem.elaborazione.*`	ElaborazioneService
Legacy	`it.mdatasystem.connessioni.*`	ConnessioneService
Legacy	`it.mdatasystem.mlib.*`	MLib
Nuova	`it.soes.sgv2.*`	REST (Quarkus)
Nuova	`it.soes.otticoservice.*`	OtticoService

Entita JPA¶

Le entita seguono il pattern a prefisso (vedi Modello Dati):

Vv* - Tabelle dati operativi (verbali, notifiche, pagamenti)
Vf* - Tabelle di riferimento/lookup (comuni, violazioni, leggi)
Vp* - Tabelle parametri/configurazione
Vg* - Tabelle globali multi-tenant
Vs* - Tabelle impostazioni

Le tabelle database usano snake_case: classe VvVerbale -> tabella vv_verbale.

Classi e Interfacce¶

Tipo	Pattern	Esempio
View (interfaccia)	`*View`	`RicercaVerbaleView`
View (implementazione)	`*ViewImpl`	`RicercaVerbaleViewImpl`
Presenter	`*Presenter`	`RicercaVerbalePresenter`
Controller	`Controller` / `ControllerImpl`	`VerbaleController`
DAO	`*Dao`	`VerbaleDao`
REST Resource (Quarkus)	`*Resource`	`VerbaleResource`
Business Object (Quarkus)	`*BO`	`VerbaleBO`
REST Service (JAX-RS)	`*RestService`	`VerbaliRestService`
SOAP Service	`*Service`	`DocFlyService`
DTO Mobile	`*Pj`	`VerbalePj`
Response Mobile	`PjsResponse*`	`PjsResponseVerbale`

Pattern Architetturali¶

MVP (GeCo.Alfa - Vaadin 7)¶

View (interfaccia)
  └── ViewImpl (componenti Vaadin)
        └── Presenter (logica presentazione)
              └── Controller / ControllerImpl (business logic)
                    └── Dao (accesso dati JPA)

Ogni schermata segue questo pattern. La View definisce l'interfaccia, ViewImpl contiene i componenti Vaadin (Table, Form, Button), il Presenter gestisce eventi UI e logica di presentazione.

Resource-BO-DAO (REST Quarkus)¶

Resource (endpoint JAX-RS, @Path)
  └── BO (Business Object, logica business)
        └── DAO (accesso dati, @Inject EntityManager)

Il modulo REST usa CDI (@Inject) per dependency injection.

JAX-RS Service (WildFly modules)¶

RestService (@Path, endpoint)
  └── Controller (logica business)
        └── DAO / EntityManager (accesso dati)

Usato in ConnessioneService, ElaborazioneService.

Regole di Codifica¶

Java¶

Java version: 1.8 per tutti i moduli legacy, 11 per REST Quarkus
Encoding: UTF-8
Indentazione: 4 spazi (no tab)
Import: Evitare wildcard imports (import java.util.*)
Nullable: Documentare con @Nullable / @NonNull quando possibile

JPA / Database¶

Usare named queries (@NamedQuery) per query frequenti
Usare JPQL preferito a native SQL (prevenzione SQL injection)
Se native SQL necessario: usare parametri posizionali (?1) o named parameters (:param)
Paginazione: Sempre setFirstResult / setMaxResults per query su tabelle grandi (>10k record)
Aggiungere nuove entita: registrare manualmente in persistence.xml

REST API¶

Usare codici HTTP standard (200, 201, 400, 401, 403, 404, 500)
Content-Type: application/json (REST), text/xml (SOAP)
Input validation a livello endpoint
Non esporre stacktrace in risposte di errore

Logging¶

Usare MLogger2 (framework logging del progetto)
MAI loggare: password, token, CF completo, dati pagamento
SEMPRE loggare: azioni utente, risultati API, eventi autenticazione
Livelli: ERROR per errori, WARN per anomalie, INFO per eventi business, DEBUG per sviluppo

Sicurezza¶

Validare tutti gli input utente (SQL injection, XSS)
Verificare autorizzazione su ogni endpoint REST
Non hardcodare credenziali nel codice
Non committare certificati, chiavi private, file .env