CFLM QR Ticket System

📋 Descrizione

Sistema di gestione biglietti per eventi gasanti CFLM basato su QR Code, realizzato con Java Spring Boot e H2 Database (configurabile per PostgreSQL). Offre funzionalità complete per la generazione, visualizzazione e verifica dei biglietti, rendendolo ideale per eventi, conferenze o qualsiasi scenario che richieda un sistema di ingresso con validazione.

✨ Caratteristiche Principali

• ✅ Generazione Biglietti Unici con ID UUID
• 🔲 QR Code Dinamici per ogni biglietto
• 📱 Scanner QR Code via webcam per la reception
• ✔️ Validazione Biglietti con prevenzione duplicati
• 📊 API REST documentate con OpenAPI/Swagger
• 🔒 Validazione Input con Bean Validation
• 🚨 Gestione Errori Centralizzata
• 📝 Logging Strutturato
• 🧪 Test Coverage Completo - 66 test con JUnit 5, Mockito e AssertJ
• 🎨 UI Responsive con Thymeleaf e poster SVG personalizzato
• 🎯 Architettura Pulita con pattern DTO, Mapper e Service Layer

🏗️ Architettura

Il progetto segue un'architettura a livelli ben strutturata:

📦 qr-ticket-system
├── 🎯 controller/          # REST Controllers & Web Controllers
├── 🔧 service/             # Business Logic Layer
├── 💾 repository/          # Data Access Layer (Spring Data JPA)
├── 📋 model/               # JPA Entities
├── 📤 dto/                 # Data Transfer Objects
├── ⚠️ exception/           # Custom Exceptions & Global Handler
├── ⚙️ config/              # Configuration Classes
└── 🛠️ util/                # Utility Classes

🛠️ Tecnologie Utilizzate

Backend:

• Java 21
• Spring Boot 3.5.7
  • Spring Web
  • Spring Data JPA
  • Spring Validation
  • Spring Security
• Lombok - Riduzione boilerplate
• ZXing - Generazione QR Code
• H2 Database - Database in memoria (dev)
• BCrypt - Password encoding

Frontend:

• Thymeleaf - Template engine
• HTML5/CSS3 - Struttura e stile
• JavaScript - Interattività
• HTML5-QRCode - Scanner QR lato browser

Testing & Documentation:

• JUnit 5 Jupiter - Testing framework
• Mockito - Mocking framework con @MockBean
• AssertJ - Fluent assertions
• Spring Boot Test - Testing utilities (@WebMvcTest, @DataJpaTest)
• Spring Security Test - @AutoConfigureMockMvc(addFilters = false) per test senza filtri security
• Jakarta Bean Validation - DTO validation testing
• SpringDoc OpenAPI - Documentazione API automatica

⚙️ Prerequisiti

• Java Development Kit (JDK): versione 17 o superiore
• Apache Maven: 3.6+ per la gestione delle dipendenze
• Un IDE: (IntelliJ IDEA, Eclipse, VS Code con estensioni Java)

� Installazione e Avvio

1. Clona il Repository

git clone https://github.com/alfdagos/CFLM_QRTicketSystem.git
cd CFLM_QRTicketSystem

2. Compila il Progetto

mvn clean install

3. Esegui i Test

mvn test

4. Avvia l'Applicazione

mvn spring-boot:run

L'applicazione sarà disponibile su http://localhost:8080

🧑‍💻 Sviluppo — Spring Boot DevTools

Questa repository include spring-boot-devtools come dipendenza di sviluppo (scope runtime, optional=true) per abilitare il riavvio automatico dell'applicazione e funzionalità di live reload durante lo sviluppo.

Come usarlo in locale:

• Avvia l'app usando il wrapper Maven generato nel progetto (consigliato):

.\mvnw.cmd spring-boot:run

• Oppure avvia con Maven installato globalmente:

mvn spring-boot:run

Comportamento utile offerto da DevTools:

• Riavvio automatico dell'app al salvataggio delle classi Java o delle risorse (classpath restart).
• Livereload opzionale del browser (se installi un client LiveReload o estensione browser).
• Caricamento delle proprietà di sviluppo separate (se presenti).

Proprietà utili (es. in src/main/resources/application.yml o application.properties):

# Disabilita il restart se vuoi (default=true)
spring.devtools.restart.enabled=true

# Abilita LiveReload server integrato (browser extension necessaria per ricaricare automaticamente)
spring.devtools.livereload.enabled=true

# Esempio: disabilitare cache template Thymeleaf in sviluppo
spring.thymeleaf.cache=false

Note importanti:

• DevTools è pensato SOLO per lo sviluppo: rimane in runtime e con optional=true nel pom.xml, quindi non sarà incluso come dipendenza transitiva in ambienti di produzione.
• Se usi un IDE (IntelliJ/VS Code/Eclipse), salva i file per innescare il riavvio; alcuni IDE richiedono la compilazione automatica abilitata.
• Se non vuoi che il restart venga eseguito (ad es. durante debug approfondito), puoi disabilitarlo tramite la proprietà spring.devtools.restart.enabled=false.

Per ulteriori dettagli vedi la documentazione ufficiale: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-devtools

📚 Utilizzo

🎫 Creazione Biglietto

1. Vai su http://localhost:8080/
2. Compila il form con:
   • Nome Evento
   • Nome Partecipante
   • Email
3. Clicca su "Genera Biglietto"
4. Visualizza il biglietto con il QR Code generato

📱 Verifica Biglietti (Reception)

Nota: L'accesso alla reception ora richiede autenticazione.

1. Vai su http://localhost:8080/reception
2. Effettua il login con:
   • Username: reception (o admin)
   • Password: reception123 (o admin123)
3. Autorizza l'accesso alla webcam
4. Scansiona il QR Code del biglietto
5. Visualizza il risultato della validazione
6. Usa il pulsante "🔓 Logout" per uscire

🔌 API REST

Crea Biglietto

POST /api/tickets
Content-Type: application/json

{
  "eventName": "CFLM 2025 Party",
  "userName": "Mario Rossi",
  "userEmail": "mario.rossi@example.com"
}

Nota: Quando si effettuano richieste tramite JavaScript fetch o AJAX, è necessario includere il token CSRF negli header:

fetch('/api/tickets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-TOKEN': csrfToken  // Token ottenuto da Thymeleaf
  },
  body: JSON.stringify(ticketData)
});

Verifica Biglietto

POST /reception/verify/{ticketId}
X-CSRF-TOKEN: <token>

Ottieni QR Code

GET /qrcode/{ticketId}

📖 Documentazione API

Accedi alla documentazione Swagger: http://localhost:8080/swagger-ui.html

💾 Console H2 Database

Per visualizzare il database in memoria:

• URL: http://localhost:8080/h2-console
• JDBC URL: jdbc:h2:mem:testdb
• Username: sa
• Password: (lascia vuoto)

🧪 Testing

Il progetto include una suite completa di 66 test che coprono tutti i livelli dell'applicazione.

Esegui tutti i test:

mvn test

Test Coverage per Layer:

1️⃣ Controller Layer (11 test - TicketControllerTest)

• ✅ Rendering pagina index
• ✅ Creazione biglietto (form e API REST)
• ✅ Visualizzazione dettaglio biglietto
• ✅ Download immagine QR Code
• ✅ Pagina scanner reception
• ✅ Verifica biglietto (valido, già usato, non trovato)
• ✅ Validazione input (errori 400)

2️⃣ Service Layer (6 test - TicketServiceTest)

• ✅ Creazione biglietto con generazione QR Code
• ✅ Recupero biglietto per ID
• ✅ Validazione biglietto valido
• ✅ Gestione biglietto già utilizzato
• ✅ Gestione biglietto non trovato

3️⃣ Repository Layer (11 test - TicketRepositoryTest)

• ✅ Operazioni CRUD complete (save, findById, update, delete)
• ✅ Query personalizzate (findByQrCodeData)
• ✅ Generazione UUID automatica
• ✅ Persistenza immagini QR Code (BLOB)
• ✅ Case sensitivity nelle ricerche

4️⃣ Mapper Utility (7 test - TicketMapperTest)

• ✅ Conversione DTO → Entity
• ✅ Conversione Entity → DTO
• ✅ Gestione valori null
• ✅ Round-trip conversion (integrità dati)

5️⃣ Model Layer (10 test - TicketTest)

• ✅ Valori di default corretti
• ✅ Getters e Setters
• ✅ Gestione null values
• ✅ Toggle stato validità
• ✅ Array byte per QR Code (fino a 1000 bytes)
• ✅ Formattazione UUID
• ✅ LocalDateTime precision
• ✅ Limiti VARCHAR(255)
• ✅ Email con caratteri speciali

6️⃣ DTO Validation (11 test - TicketDTOValidationTest)

• ✅ Validazione @NotBlank per tutti i campi
• ✅ Validazione @Email per userEmail
• ✅ Validazione @Size per lunghezze min/max
• ✅ Gestione campi null
• ✅ Gestione whitespace-only
• ✅ Email complesse (subdomain, plus addressing)
• ✅ Supporto caratteri Unicode

7️⃣ Exception Handler (6 test - GlobalExceptionHandlerTest)

• ✅ TicketNotFoundException → 404
• ✅ TicketAlreadyUsedException → 409
• ✅ QRCodeGenerationException → 500
• ✅ Validation errors → 400 con dettagli
• ✅ Generic exceptions → 500

8️⃣ Configuration (3 test - QRCodeConfigTest)

• ✅ Caricamento proprietà QR Code (width, height, format)
• ✅ Validazione valori positivi
• ✅ Spring Boot context loading

9️⃣ Integration Test (1 test - QrticketsystemApplicationTests)

• ✅ Application context loads successfully

Test Statistics:

✅ Total Tests: 66
✅ Failures: 0
✅ Errors: 0
✅ Skipped: 0
✅ Success Rate: 100%

Esegui test specifici:

# Solo test del controller
mvn test -Dtest=TicketControllerTest

# Solo test del service
mvn test -Dtest=TicketServiceTest

# Solo test di validazione
mvn test -Dtest=TicketDTOValidationTest

📁 Struttura del Progetto

src/
├── main/
│   ├── java/it/cflm/qrticketsystem/
│   │   ├── QrTicketSystemApplication.java
│   │   ├── config/
│   │   │   ├── OpenApiConfig.java
│   │   │   ├── QRCodeConfig.java
│   │   │   └── SecurityConfig.java         # Spring Security Configuration
│   │   ├── controller/
│   │   │   └── TicketController.java
│   │   ├── dto/
│   │   │   ├── TicketRequestDTO.java
│   │   │   ├── TicketResponseDTO.java
│   │   │   └── TicketValidationResponseDTO.java
│   │   ├── exception/
│   │   │   ├── GlobalExceptionHandler.java
│   │   │   ├── QRCodeGenerationException.java
│   │   │   ├── TicketAlreadyUsedException.java
│   │   │   └── TicketNotFoundException.java
│   │   ├── model/
│   │   │   └── Ticket.java
│   │   ├── repository/
│   │   │   └── TicketRepository.java
│   │   ├── service/
│   │   │   └── TicketService.java
│   │   └── util/
│   │       └── TicketMapper.java
│   └── resources/
│       ├── application.properties
│       ├── static/
│       │   ├── css/
│       │   │   └── style.css
│       │   ├── js/
│       │   │   └── scanner.js
│       │   └── img/
│       │       └── poster.svg         # Poster evento personalizzato
│       └── templates/
│           ├── index.html
│           ├── login.html                  # Pagina login Spring Security
│           ├── reception_scanner.html
│           ├── ticket_detail.html
│           └── ticket_not_found.html
└── test/
    └── java/it/cflm/qrticketsystem/
        ├── config/
        │   └── QRCodeConfigTest.java
        ├── controller/
        │   └── TicketControllerTest.java
        ├── dto/
        │   └── TicketDTOValidationTest.java
        ├── exception/
        │   └── GlobalExceptionHandlerTest.java
        ├── model/
        │   └── TicketTest.java
        ├── repository/
        │   └── TicketRepositoryTest.java
        ├── service/
        │   └── TicketServiceTest.java
        ├── util/
        │   └── TicketMapperTest.java
        └── QrticketsystemApplicationTests.java

� Configurazione

application.properties

# Database H2
spring.datasource.url=jdbc:h2:mem:testdb
spring.jpa.hibernate.ddl-auto=update

# QR Code Settings
qrcode.width=300
qrcode.height=300
qrcode.format=PNG

# Logging
logging.level.it.cflm.qrticketsystem=DEBUG

Per usare PostgreSQL:

1. Decommenta la dipendenza PostgreSQL in pom.xml
2. Aggiorna application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/qr_ticket_db
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

🔒 Sicurezza

Implementazioni Attuali:

• 🔐 Spring Security per autenticazione/autorizzazione
• 👥 Role-Based Access Control (ADMIN, RECEPTION, USER)
• 🔑 BCrypt Password Encoding
• 🔒 Form-Based Login con sessioni sicure
• ✅ Validazione input con Bean Validation
• 🚨 Gestione sicura delle eccezioni
• 📝 Logging degli accessi
• 🛡️ Protezione SQL Injection (JPA)
• 🔐 CSRF Protection per form

Credenziali di Test:

• Admin: admin / admin123 (accesso completo)
• Reception: reception / reception123 (solo verifica biglietti)
• User: user / user123 (funzionalità limitate)

� Vedi SECURITY.md per dettagli completi sulla configurazione di sicurezza.

Miglioramenti Suggeriti per Produzione:

• 🔑 JWT per l'API REST
• � Database Users (al posto di in-memory)
• 📧 Email Verification
• 🔒 HTTPS obbligatorio
• 🚦 Rate Limiting
• 🔐 2FA (Two-Factor Authentication)
• 🔒 Password Reset via email

📈 Miglioramenti Implementati

Highlights Recenti:

🧪 Testing Completo

• 66 test che coprono tutti i livelli dell'applicazione
• Test di integrazione con @WebMvcTest e @DataJpaTest
• Copertura completa di controller, service, repository, mapper, model, DTOs
• Test di validazione Jakarta Bean Validation
• Test di gestione eccezioni centralizzata

🎨 UI/UX Migliorata

• Banner orizzontale ottimizzato (1200x400px) per visualizzazione web
• Design moderno con gradiente arcobaleno e effetti neon
• Animazioni sulle stelle pulsanti
• Poster SVG personalizzato con tema party (cocktail, note musicali, icone emoji)
• Layout responsive con object-fit: contain per visualizzazione completa
• Effetti spotlight radiali per maggiore profondità
• Decorazioni bilanciate su entrambi i lati

🏗️ Architettura

• 🎯 DTO Pattern per separazione API/Model
• 🚨 Global Exception Handler centralizzato
• ✔️ Bean Validation su tutti gli input
• 📝 Logging SLF4J strutturato
• 💉 Constructor Injection con Lombok
• 🔄 @Transactional per consistenza dati
• 🧰 Mapper Utility per conversioni DTO/Entity
• 📖 OpenAPI/Swagger documentation
• 🔐 Spring Security per autenticazione/autorizzazione

🔒 Sicurezza

• Role-Based Access Control (RBAC)
• BCrypt password encoding
• Form-based login con sessioni sicure
• CSRF protection su tutti i form e richieste POST
• Token CSRF automaticamente incluso nelle richieste via Thymeleaf
• Protezione endpoint sensibili
• Test disabilitano filtri Spring Security con @AutoConfigureMockMvc(addFilters = false)

Test Patterns Utilizzati:

• AAA Pattern (Arrange-Act-Assert)
• Given-When-Then per BDD-style tests
• MockBean per isolation testing
• TestEntityManager per JPA testing
• MockMvc per integration testing
• Fluent Assertions con AssertJ