# PrenotaInBase - Specifica Tecnica

## 1. Obiettivo

Realizzare una webapp `PWA`, mobile-first, che digitalizzi il modulo cartaceo presente in `modulo.pdf`, raccolga i dati necessari, acquisisca la firma dell'utente, generi un nuovo PDF visivamente aderente al template originale e lo invii via email all'indirizzo configurato.

L'applicazione deve essere progettata con approccio `privacy-first`:

- nessun dato sensibile del modulo deve essere persistito nel database;
- nessun modulo compilato deve essere recuperabile dopo l'invio;
- nessuna firma deve essere conservata in modo persistente;
- lo storico utente deve mostrare solo metadati tecnici degli invii.

## 2. Vincoli Funzionali

### 2.1 Requisiti principali

- Interfaccia `PWA` installabile su smartphone.
- UI mobile-first con compilazione guidata.
- Supporto autenticazione con:
  - Google Sign-In;
  - registrazione/login locale rapido con username e password.
- Compilazione di tutti i campi richiesti dal modulo.
- Gestione fino a 5 ospiti/familiari.
- Selezione servizi richiesti tramite checkbox.
- Firma acquisibile:
  - tramite fotocamera smartphone;
  - tramite upload PNG;
  - opzionalmente tramite canvas touch.
- Generazione PDF finale usando `modulo.pdf` come template grafico.
- Invio PDF via email con SMTP configurabile.
- Storico invii disponibile all'utente senza accesso al contenuto dei moduli precedenti.

### 2.2 Requisiti privacy e sicurezza

- Nessun dato anagrafico, recapito, targa, grado, reparto, nominativo ospiti o firma deve essere salvato nel DB.
- I dati sensibili devono vivere solo in memoria o in area temporanea volatile per il tempo strettamente necessario.
- I file temporanei devono essere eliminati subito dopo generazione PDF e invio email.
- I log applicativi non devono mai contenere payload del modulo.
- L'identità utente deve essere pseudonimizzata quando possibile.

## 3. Analisi Del Template PDF

Il file `modulo.pdf`:

- e un PDF statico A4;
- non contiene campi `AcroForm` compilabili;
- richiede un approccio a overlay su coordinate;
- e composto da 1 pagina;
- contiene:
  - dati richiedente;
  - recapiti e residenza;
  - stato servizio;
  - dati veicolo;
  - elenco di 5 ospiti;
  - selezione servizi;
  - data e firma.

### 3.1 Implicazione tecnica

Non va ricostruito da HTML. Il backend deve:

1. caricare il PDF originale come sfondo;
2. scrivere sopra testi, spunte e firma nelle coordinate corrette;
3. produrre un nuovo PDF appiattito;
4. inviarlo via email;
5. cancellare gli artefatti temporanei.

## 4. Architettura Applicativa

### 4.1 Stack

- Frontend: `HTML`, `CSS`, `JavaScript` vanilla
- Backend: `PHP 8.3`
- Server web: `Apache`
- Database: `MariaDB`
- Reverse proxy: `Traefik` gia presente sul VPS
- PDF: `setasign/fpdi` + `tecnickcom/tcpdf`
- Email: `PHPMailer`
- Elaborazione firma: `Imagick`
- PWA: `manifest.webmanifest` + `service worker`

### 4.2 Motivazioni

- `Apache` mantiene coerenza operativa con le altre app del VPS.
- `FPDI` consente di importare il PDF originale come template grafico.
- `Imagick` e la scelta migliore per trasformare una foto della firma in un PNG trasparente pulito.
- `MariaDB` consente di mantenere soltanto log tecnici e utenti locali.

## 5. Architettura Privacy-First

### 5.1 Dati che non devono essere persistiti

- nome e cognome;
- codice fiscale;
- reparto, grado, qualifica;
- cellulare, email, telefono ufficio;
- indirizzo e residenza;
- dati dei familiari/ospiti;
- targa e tipo veicolo;
- immagine originale della firma;
- PNG finale della firma;
- PDF compilato;
- payload raw della request.

### 5.2 Dati che possono essere persistiti

- utenza locale minima:
  - username;
  - password hash;
  - timestamp di accesso;
- oppure identita Google pseudonimizzata:
  - hash dell'identificativo provider;
- log tecnico invio:
  - submission UUID;
  - utente proprietario;
  - stato invio;
  - timestamp;
  - hash PDF;
  - codici errore tecnici sintetici.

### 5.3 Strategia di trattamento

- I dati del modulo vengono ricevuti dal backend e validati.
- La firma viene ripulita in una directory temporanea montata in `tmpfs`.
- Il PDF viene generato in area temporanea volatile.
- Il PDF viene inviato tramite SMTP.
- Alla fine del flusso:
  - si cancella la firma temporanea;
  - si cancella il PDF temporaneo;
  - si registra solo il log invio.

## 6. Flussi Utente

### 6.1 Registrazione/Login

Due modalita:

- `Google Sign-In`
- `Account locale`

#### Login Google

- Il frontend riceve il token Google.
- Il backend valida il token.
- Si ricava `sub` del provider.
- Si salva solo un identificativo pseudonimo:
  - `provider_subject_hash = HMAC_SHA256(sub, APP_KEY)`

#### Registrazione locale

- L'utente sceglie uno `username` non necessariamente riconducibile alla sua identita reale.
- Inserisce password.
- La password viene hashata con `PASSWORD_ARGON2ID`.
- Il sistema salva solo dati minimi di autenticazione.

### 6.2 Compilazione modulo

- Form multi-step mobile-first.
- Salvataggio temporaneo solo lato client durante la sessione.
- Invio finale tramite `POST /api/submissions`.

### 6.3 Storico invii

L'utente autenticato puo vedere:

- data e ora invio;
- stato invio;
- identificativo invio;
- hash tecnico del PDF opzionale.

Non puo:

- riaprire PDF gia inviati;
- visualizzare dati inseriti in passato;
- scaricare firme o allegati storici.

## 7. Gestione Firma

### 7.1 Modalita supportate

- foto da fotocamera smartphone;
- upload PNG;
- canvas touch opzionale.

### 7.2 Pipeline di pulizia

1. acquisizione immagine;
2. correzione orientamento EXIF;
3. crop/anteprima;
4. conversione in scala di grigi;
5. aumento contrasto;
6. threshold del bianco;
7. creazione canale alpha;
8. export in PNG trasparente;
9. ritaglio automatico dell'area utile.

### 7.3 Risultato atteso

- firma leggibile;
- sfondo trasparente;
- bordo minimo;
- dimensione adattabile al box firma nel PDF.

## 8. Generazione PDF

### 8.1 Strategia

- Caricare `modulo.pdf` come template.
- Definire una mappa coordinate dei campi.
- Scrivere testi e spunte sulle coordinate.
- Inserire la firma PNG trasparente nel box firma.
- Salvare PDF solo in area temporanea volatile.

### 8.2 Mappatura coordinate

Serve un file dedicato, ad esempio `config/pdf_fields.php`, contenente:

- nome campo;
- pagina;
- coordinata `x`;
- coordinata `y`;
- larghezza massima;
- dimensione font;
- tipo rendering:
  - `text`
  - `checkbox`
  - `image`

## 9. Invio Email

### 9.1 Requisiti

- invio SMTP autenticato;
- destinatario configurabile;
- supporto TLS;
- oggetto e corpo email configurabili;
- allegato PDF generato al momento.

### 9.2 Configurazione

La configurazione va salvata in `.env` o in file PHP non versionato.

Chiavi minime:

- `APP_ENV`
- `APP_KEY`
- `APP_URL`
- `DB_*`
- `SMTP_HOST`
- `SMTP_PORT`
- `SMTP_USER`
- `SMTP_PASS`
- `SMTP_ENCRYPTION`
- `MAIL_TO`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`

## 10. Database

### 10.1 Tabelle consigliate

#### `users`

- `id`
- `auth_type` (`local` o `google`)
- `username` nullable, unico
- `password_hash` nullable
- `provider_subject_hash` nullable, unico
- `created_at`
- `last_login_at`

#### `submission_logs`

- `id`
- `submission_uuid`
- `user_id`
- `status` (`processing`, `sent`, `failed`)
- `created_at`
- `sent_at`
- `failed_at`
- `error_code`
- `error_message_short`
- `pdf_sha256`
- `request_duration_ms`

### 10.2 Dati esclusi dal DB

Nessuna tabella deve contenere dati del modulo o firme.

## 11. API Applicative

### 11.1 Endpoint pubblici

- `GET /`
- `GET /login`
- `POST /auth/login`
- `POST /auth/register`
- `POST /auth/google`
- `POST /auth/logout`

### 11.2 Endpoint autenticati

- `GET /dashboard`
- `GET /api/history`
- `POST /api/submissions`

### 11.3 Comportamento `POST /api/submissions`

1. valida sessione utente;
2. valida input modulo;
3. riceve firma;
4. produce PNG trasparente;
5. genera PDF temporaneo;
6. invia email;
7. calcola hash PDF;
8. elimina temporanei;
9. salva log invio;
10. restituisce esito.

## 12. Docker E Deploy Su VPS

### 12.1 Vincoli

- Stack interamente containerizzato.
- Traefik gia presente come reverse proxy.
- Apache mantenuto come web server applicativo.

### 12.2 Container previsti

- `app`: Apache + PHP 8.3
- `db`: MariaDB
- `pma`: opzionale, da non esporre in produzione

### 12.3 Requisiti container `app`

- estensione `pdo_mysql`
- estensione `gd`
- estensione `imagick`
- `mod_rewrite`
- composer
- healthcheck semplice

### 12.4 Hardening consigliato

- `tmpfs` montata su `/tmp/prenotainbase`
- `read_only: true` dove possibile
- utente non root se compatibile con immagine finale
- variabili sensibili fuori dal repository
- database su rete interna soltanto
- niente `phpMyAdmin` esposto pubblicamente in produzione

## 13. Struttura Progetto Consigliata

```text
prenotainbase/
  config/
  docker/
    apache/
    mariadb/
    php/
  docs/
  public/
    assets/
  src/
    Controllers/
    Core/
    Middleware/
    Repositories/
    Services/
    Support/
  storage/
    app/
    logs/
    tmp/
  composer.json
  docker-compose.yml
  modulo.pdf
```

## 14. PWA

### 14.1 Componenti

- `manifest.webmanifest`
- `service-worker.js`
- icone app
- cache statica degli asset

### 14.2 Strategia

- `offline` solo per shell applicativa e pagina informativa;
- invio modulo disponibile solo online;
- se necessario, in fase successiva si puo aggiungere bozza locale in `localStorage` o `IndexedDB`.

## 15. Sicurezza Applicativa

### 15.1 Obbligatorie

- HTTPS forzato lato Traefik
- cookie sessione `Secure`, `HttpOnly`, `SameSite`
- protezione CSRF sui form
- validazione server-side completa
- rate limiting
- sanitizzazione output
- nessun log di `$_POST` o file upload

### 15.2 Raccomandate

- Content Security Policy
- X-Frame-Options
- X-Content-Type-Options
- Referrer-Policy
- backup solo del DB log tecnico
- rotazione credenziali SMTP

## 16. Roadmap Di Sviluppo

### Fase 1

- scaffolding progetto;
- configurazione Docker;
- bootstrap PHP;
- schema database.

### Fase 2

- autenticazione locale;
- integrazione Google login;
- dashboard base.

### Fase 3

- form modulo multi-step mobile-first;
- gestione ospiti e servizi;
- validazioni.

### Fase 4

- acquisizione firma;
- pipeline `Imagick` per PNG trasparente.

### Fase 5

- mappa coordinate PDF;
- generazione PDF;
- invio email.

### Fase 6

- storico invii;
- logging tecnico;
- rifiniture PWA.

### Fase 7

- test reali su smartphone;
- hardening deploy VPS;
- tuning UX e gestione errori.

## 17. Decisioni Architetturali Confermate

- `Apache` invece di `nginx`
- `MariaDB` per utenti e log
- nessun salvataggio persistente di moduli o firme
- storico consultabile ma non apribile
- login Google + login locale
- deploy in Docker dietro Traefik
- elaborazione firma con sfondo trasparente

## 18. Rischi Residui

- Il PDF finale inviato via email esiste comunque nella mailbox del destinatario.
- Una foto firma scattata male puo produrre risultati non ottimali anche con pulizia automatica.
- La sicurezza totale non esiste: l'obiettivo realistico e minimizzare la superficie di attacco e limitare il valore dei dati persistiti.

## 19. Deliverable Minimo Della Prima Versione

- autenticazione locale e Google;
- dashboard con storico invii;
- form mobile-first;
- acquisizione firma;
- generazione PDF da template;
- invio email SMTP;
- cancellazione immediata dei temporanei;
- deploy Docker compatibile con Traefik.