# 🔧 Documentazione Tecnica Rinnovo Booking

## 📋 Indice
1. [Architettura del Sistema](#architettura-del-sistema)
2. [Struttura del Database](#struttura-del-database)
3. [Componenti Core](#componenti-core)
4. [API e Endpoints](#api-e-endpoints)
5. [Sistema di Prenotazione](#sistema-di-prenotazione)
6. [Gestione File e Documenti](#gestione-file-e-documenti)
7. [Sistema di Notifiche](#sistema-di-notifiche)
8. [Frontend JavaScript](#frontend-javascript)
9. [Sistema CSS e UI](#sistema-css-e-ui)
10. [Integrazione iPatente](#integrazione-ipatente)
11. [Sicurezza](#sicurezza)
12. [Performance e Ottimizzazione](#performance-e-ottimizzazione)
13. [Manutenzione e Debug](#manutenzione-e-debug)
14. [Testing e QA](#testing-e-qa)

## 🏗️ Architettura del Sistema

### 📊 Overview Architetturale
Il plugin Rinnovo Booking implementa un'architettura modulare basata su:
- **Design Pattern**: Singleton, Factory, Observer
- **Paradigma**: MVC (Model-View-Controller)
- **Principi**: SOLID, DRY, KISS
- **Standard**: PSR-4 Autoloading, WordPress Coding Standards

```
🎯 ARCHITETTURA PLUGIN
┌─────────────────────────────────────┐
│           WordPress Core            │
├─────────────────────────────────────┤
│         Plugin Router               │
│    (RinnovoBooking.php)            │
├─────────────────────────────────────┤
│  Controllers    │    Services       │
│  (Admin/Backend)│ (Core/EmailService│
├─────────────────┼───────────────────┤
│     Models      │     Views         │
│  (Database)     │ (HTML/Templates)  │
├─────────────────┼───────────────────┤
│        Assets (CSS/JS)              │
└─────────────────────────────────────┘
```

### 🔄 Flusso Richieste Dettagliato
```mermaid
sequenceDiagram
    participant U as User
    participant WP as WordPress
    participant R as Router
    participant C as Controller
    participant M as Model
    participant V as View
    participant DB as Database
    
    U->>WP: HTTP Request
    WP->>R: Route to Plugin
    R->>C: Load Controller
    C->>M: Get Data
    M->>DB: Query Database
    DB->>M: Return Data
    M->>C: Process Data
    C->>V: Render View
    V->>U: HTML Response
```

### 🎯 Componenti Principali
- **Router**: Gestione URL e parametri (`?tipo=`, `?idsede=`)
- **Controllers**: Logica business per admin/frontend
- **Services**: Servizi condivisi (email, licenze, API)
- **Models**: Interazione database e validazione
- **Views**: Template HTML e rendering
- **Assets**: CSS/JS ottimizzati per performance

## 🗄️ Struttura del Database

### 📊 Schema Completo Database
```sql
-- Prefisso dinamico: {wp_prefix}rinnovo_booking_

-- === TABELLE PRINCIPALI === --

-- Fasce orarie standard per sede
CREATE TABLE wp_rinnovo_booking_time_slots (
    id INT AUTO_INCREMENT PRIMARY KEY,
    idsede VARCHAR(50) NOT NULL,
    day_of_week VARCHAR(20) NOT NULL,        -- 'monday', 'tuesday', etc.
    start_time TIME NOT NULL,
    end_time TIME NOT NULL,
    minutes_slots INT DEFAULT 30,             -- Durata slot in minuti
    max_slots INT DEFAULT 10,                 -- Max slot generabili
    max_bookings INT DEFAULT 1,               -- Max prenotazioni per slot
    services TEXT,                            -- JSON array servizi disponibili
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_sede_day (idsede, day_of_week),
    INDEX idx_time_range (start_time, end_time)
);

-- Prenotazioni effettuate
CREATE TABLE wp_rinnovo_booking_bookings (
    id INT AUTO_INCREMENT PRIMARY KEY,
    idsede VARCHAR(50) NOT NULL,
    date DATE NOT NULL,
    time TIME NOT NULL,
    nome VARCHAR(100) NOT NULL,
    cognome VARCHAR(100) NOT NULL,
    email VARCHAR(100) NOT NULL,
    telefono VARCHAR(20),
    npatente VARCHAR(50),
    tipo_visita VARCHAR(50) NOT NULL,
    stato ENUM('pending','confirmed','completed','cancelled','no_show') DEFAULT 'pending',
    origine VARCHAR(20) DEFAULT 'web',        -- 'web', 'admin', 'api', 'ipatente'
    note TEXT,
    qr_code VARCHAR(255),                     -- Hash QR Code
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_sede_date (idsede, date),
    INDEX idx_date_time (date, time),
    INDEX idx_email (email),
    INDEX idx_stato (stato)
);

-- Giorni di apertura/chiusura straordinari
CREATE TABLE wp_rinnovo_booking_slots_except (
    id INT AUTO_INCREMENT PRIMARY KEY,
    idsede VARCHAR(50) NOT NULL,
    day_of_week DATE NOT NULL,               -- Data specifica YYYY-MM-DD
    start_time TIME,
    end_time TIME,
    stato ENUM('aperto','chiuso') NOT NULL,
    minutes_slots INT DEFAULT 30,
    max_bookings INT DEFAULT 1,
    services TEXT,                           -- JSON array servizi
    note VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_sede_date (idsede, day_of_week)
);

-- === TABELLE SUPPORTO === --

-- Sedi autoscuole
CREATE TABLE wp_rinnovo_booking_sedi (
    idsede VARCHAR(50) PRIMARY KEY,
    nome VARCHAR(100) NOT NULL,
    indirizzo TEXT,
    telefono VARCHAR(20),
    email VARCHAR(100),
    attiva BOOLEAN DEFAULT TRUE,
    configurazione JSON,                      -- Configurazioni specifiche sede
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indirizzi consegna documenti
CREATE TABLE wp_rinnovo_booking_indirizzi (
    id INT AUTO_INCREMENT PRIMARY KEY,
    id_booking INT NOT NULL,
    dove ENUM('autoscuola','casa') DEFAULT 'autoscuola',
    indirizzo_residenza TEXT,
    indirizzo_destinazione TEXT,
    note TEXT,
    FOREIGN KEY (id_booking) REFERENCES wp_rinnovo_booking_bookings(id) ON DELETE CASCADE
);

-- Origini prenotazioni (tracking)
CREATE TABLE wp_rinnovo_booking_booking_origins (
    id INT AUTO_INCREMENT PRIMARY KEY,
    id_booking INT NOT NULL,
    sede_provenienza VARCHAR(50),
    user_agent TEXT,
    ip_address VARCHAR(45),
    referrer TEXT,
    utm_source VARCHAR(100),
    utm_medium VARCHAR(100),
    utm_campaign VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (id_booking) REFERENCES wp_rinnovo_booking_bookings(id) ON DELETE CASCADE
);

-- Log sistema per audit
CREATE TABLE wp_rinnovo_booking_logs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    level ENUM('info','warning','error','debug') DEFAULT 'info',
    message TEXT NOT NULL,
    context JSON,                            -- Dati contestuali
    user_id INT,
    ip_address VARCHAR(45),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_level_date (level, created_at),
    INDEX idx_user (user_id)
);
```

### 🔍 Indici e Ottimizzazioni
```sql
-- Indici compositi per query frequenti
CREATE INDEX idx_booking_search ON wp_rinnovo_booking_bookings (idsede, date, stato);
CREATE INDEX idx_availability_check ON wp_rinnovo_booking_time_slots (idsede, day_of_week, start_time);
CREATE INDEX idx_exception_lookup ON wp_rinnovo_booking_slots_except (idsede, day_of_week, stato);

-- Indici full-text per ricerche
ALTER TABLE wp_rinnovo_booking_bookings ADD FULLTEXT(nome, cognome, email);
```

### 📈 Relazioni e Vincoli
```mermaid
erDiagram
    SEDI ||--o{ TIME_SLOTS : has
    SEDI ||--o{ BOOKINGS : manages
    SEDI ||--o{ SLOTS_EXCEPT : configures
    BOOKINGS ||--|| INDIRIZZI : has
    BOOKINGS ||--|| BOOKING_ORIGINS : tracks
    BOOKINGS ||--o{ LOGS : generates
```

## 🎯 Componenti Core

### 🏗️ RinnovoBooking.php - Controller Principale
```php
<?php
namespace RinnovoBooking\Core;

/**
 * Classe principale del plugin - Singleton Pattern
 * Gestisce routing, inizializzazione e coordinamento componenti
 */
class RinnovoBooking {
    private static $instance = null;
    private $user_data = [];
    private $current_sede = null;
    
    // === SINGLETON PATTERN === //
    public static function get_instance() {
        if (null === self::$instance) {
            self::$instance = new self();
        }
        return self::$instance;
    }
    
    // === INIZIALIZZAZIONE === //
    public function init() {
        $this->setup_hooks();
        $this->register_shortcode();
        $this->init_services();
        $this->load_user_session();
    }
    
    // === ROUTING SYSTEM === //
    public function handle_request() {
        $tipo = sanitize_text_field($_GET['tipo'] ?? '');
        $idsede = sanitize_text_field($_GET['idsede'] ?? '');
        
        // Verifica accesso e permessi
        if (!$this->verify_access($idsede)) {
            return $this->handle_access_denied();
        }
        
        // Route verso controller appropriato
        switch($tipo) {
            case 'prenotazioni':
                return $this->handle_prenotazioni();
            case 'nuova_prenotazione':
                return $this->handle_nuova_prenotazione();
            case 'modifica_prenotazione':
                return $this->handle_modifica_prenotazione();
            case 'impostazioni':
                return $this->handle_impostazioni();
            default:
                return $this->handle_default();
        }
    }
    
    // === GESTIONE SESSIONI === //
    private function load_user_session() {
        $this->user_data = [
            'user_logged_in' => $this->check_user_login(),
            'user_role' => $this->get_user_role(),
            'user_sede' => $this->get_user_sede(),
            'permissions' => $this->get_user_permissions()
        ];
    }
}
```

### 📧 EmailService.php - Sistema Email Avanzato
```php
<?php
namespace RinnovoBooking\Core;

/**
 * Servizio email con template engine e queue system
 */
class EmailService {
    private $smtp_config = [];
    private $template_cache = [];
    private $queue = [];
    
    // === CONFIGURAZIONE SMTP === //
    public function configure_smtp($config) {
        $this->smtp_config = array_merge([
            'host' => 'localhost',
            'port' => 587,
            'secure' => 'tls',
            'auth' => true,
            'username' => '',
            'password' => ''
        ], $config);
    }
    
    // === TEMPLATE ENGINE === //
    public function process_template($template_name, $variables) {
        $template = $this->load_template($template_name);
        
        // Sostituisci variabili dinamiche
        foreach ($variables as $key => $value) {
            $template = str_replace("__{$key}__", $value, $template);
        }
        
        // Processa conditional blocks
        $template = $this->process_conditionals($template, $variables);
        
        return $template;
    }
    
    // === INVIO EMAIL === //
    public function send_confirmation($booking_data) {
        $variables = $this->prepare_email_variables($booking_data);
        $html_content = $this->process_template('confirmationEmail', $variables);
        
        $email_data = [
            'to' => $booking_data['email'],
            'subject' => 'Conferma Prenotazione - ' . $variables['__SEDE__'],
            'body' => $html_content,
            'headers' => $this->get_email_headers(),
            'attachments' => $this->prepare_attachments($booking_data)
        ];
        
        return $this->queue_email($email_data);
    }
    
    // === QUEUE SYSTEM === //
    private function queue_email($email_data) {
        $this->queue[] = $email_data;
        
        // Invio immediato o differito
        if ($this->should_send_immediate()) {
            return $this->process_queue();
        }
        
        // Schedula per invio differito
        wp_schedule_single_event(time() + 60, 'rinnovo_booking_process_email_queue');
        return true;
    }
}
```

### 🔌 RinnovoBookingService.php - Business Logic Layer
```php
<?php
namespace RinnovoBooking\Core;

/**
 * Servizio principale per operazioni business
 * Gestisce validazione, integrazione API, cache
 */
class RinnovoBookingService {
    private $cache;
    private $validator;
    private $api_clients = [];
    
    // === GESTIONE PRENOTAZIONI === //
    public function create_booking($data) {
        // 1. Validazione dati
        $validated_data = $this->validator->validate_booking_data($data);
        if (!$validated_data['valid']) {
            throw new ValidationException($validated_data['errors']);
        }
        
        // 2. Verifica disponibilità slot
        if (!$this->is_slot_available($data['date'], $data['time'], $data['sede'])) {
            throw new SlotUnavailableException('Slot non disponibile');
        }
        
        // 3. Salvataggio database con transazione
        return $this->db_transaction(function() use ($data) {
            $booking_id = $this->save_booking($data);
            $this->save_booking_address($booking_id, $data);
            $this->save_booking_origin($booking_id, $data);
            
            // 4. Invalidazione cache
            $this->cache->delete("availability_{$data['sede']}_{$data['date']}");
            
            return $booking_id;
        });
    }
    
    // === ALGORITMO DISPONIBILITÀ === //
    public function calculate_availability($sede, $date) {
        $cache_key = "availability_{$sede}_{$date}";
        
        if ($cached = $this->cache->get($cache_key)) {
            return $cached;
        }
        
        // Ottieni configurazione fasce orarie
        $time_slots = $this->get_time_slots_for_date($sede, $date);
        $bookings = $this->get_bookings_for_date($sede, $date);
        $exceptions = $this->get_exceptions_for_date($sede, $date);
        
        // Calcola slot disponibili
        $availability = $this->compute_slot_availability(
            $time_slots, 
            $bookings, 
            $exceptions
        );
        
        // Cache per 5 minuti
        $this->cache->set($cache_key, $availability, 300);
        
        return $availability;
    }
}
```

## API e Endpoints

### Endpoints Principali

#### Prenotazioni
```php
// Nuova prenotazione
POST /wp-json/rinnovo-booking/v1/bookings
{
    "date": "YYYY-MM-DD",
    "time": "HH:mm",
    "nome": "string",
    "cognome": "string",
    "email": "string",
    "telefono": "string",
    "npatente": "string",
    "tipo_visita": "string",
    "sede": "string"
}

// Modifica prenotazione
PUT /wp-json/rinnovo-booking/v1/bookings/{id}
{
    // Stessi campi di sopra
}

// Cancellazione prenotazione
DELETE /wp-json/rinnovo-booking/v1/bookings/{id}
```

#### Disponibilità
```php
// Recupera disponibilità
GET /wp-json/rinnovo-booking/v1/availability
{
    "sede": "string",
    "date": "YYYY-MM-DD"
}
```

## Sistema di Prenotazione

### Flusso Prenotazione
1. Verifica disponibilità slot
2. Validazione dati utente
3. Creazione prenotazione
4. Invio email conferma
5. Aggiornamento calendario

### Gestione Slot Temporali
```php
function get_available_slots($date, $sede) {
    // Recupera slot disponibili
    // Verifica prenotazioni esistenti
    // Calcola slot liberi
    return $available_slots;
}
```

## Gestione File e Documenti

### Upload Documenti
- Foto tessera
- Firma digitale
- Documenti aggiuntivi

### Integrazione Cloud
```php
class CloudHandler {
    public function upload_file($file, $type) {
        // Logica upload file
    }
    
    public function get_file_url($file_id) {
        // Recupera URL file
    }
}
```

## Sistema di Notifiche

### Tipi di Notifiche
1. Email di conferma
2. Email di modifica
3. Email di cancellazione
4. Notifiche admin

### Template Email
```php
// Struttura template
email/
├── conferma.php
├── modifica.php
└── cancellazione.php
```

## Sicurezza

### Validazione Input
```php
function sanitize_booking_data($data) {
    return array_map('sanitize_text_field', $data);
}
```

### Protezione API
```php
// Verifica nonce
if (!wp_verify_nonce($_POST['nonce'], 'rinnovo_booking_nonce')) {
    wp_send_json_error('Invalid nonce');
}
```

### Gestione Permessi
```php
// Verifica permessi utente
if (!current_user_can('manage_options')) {
    wp_die('Unauthorized access');
}
```

## Manutenzione e Debug

### Logging
```php
function log_booking_activity($action, $data) {
    error_log(sprintf(
        '[Rinnovo Booking] %s: %s',
        $action,
        json_encode($data)
    ));
}
```

### Debug Mode
```php
if (defined('WP_DEBUG') && WP_DEBUG) {
    // Attiva logging dettagliato
    // Mostra errori
}
```

### Backup
- Backup database prenotazioni
- Backup configurazioni
- Backup file uploadati

## Guide per Sviluppatori

### Aggiungere Nuova Funzionalità
1. Creare nuovo file in directory appropriata
2. Registrare hook in `RinnovoBooking.php`
3. Aggiungere eventuali endpoint API
4. Aggiornare documentazione

### Modificare Template
1. Localizzare template in `html/`
2. Modificare mantenendo struttura esistente
3. Testare in ambiente di sviluppo
4. Aggiornare CSS se necessario

### Aggiungere Nuovo Endpoint API
```php
add_action('rest_api_init', function () {
    register_rest_route('rinnovo-booking/v1', '/nuovo-endpoint', [
        'methods' => 'GET',
        'callback' => 'nuova_funzione',
        'permission_callback' => 'verifica_permessi'
    ]);
});
```

## Troubleshooting

### Problemi Comuni
1. Prenotazioni non salvate
   - Verificare permessi database
   - Controllare log errori
   - Verificare validazione dati

2. Email non inviate
   - Verificare configurazione SMTP
   - Controllare template email
   - Verificare log errori

3. Calendario non aggiornato
   - Verificare cache browser
   - Controllare JavaScript console
   - Verificare endpoint API

### Strumenti di Debug
- WP_DEBUG_LOG
- Chrome DevTools
- Query Monitor
- Debug Bar

## ⚡ Frontend JavaScript

### 🎯 Architettura Modulare
Il sistema JavaScript è organizzato in moduli specializzati:
- **CalendarModule**: Gestione calendario interattivo
- **SlotModule**: Gestione slot temporali
- **FormModule**: Validazione e invio form
- **CacheModule**: Cache locale per performance

### 📱 Responsive e Mobile-First
- Design responsive con breakpoint ottimizzati
- Touch-friendly per dispositivi mobile
- Performance ottimizzata per connessioni lente

## 🎨 Sistema CSS e UI

### 🖌️ Design System Unificato
- Variabili CSS per consistenza colori
- Componenti riutilizzabili con classe `.rb-*`
- Sistema di griglia responsive
- Animazioni fluide e accessibili

## 🔗 Integrazione iPatente

### 🌐 API Wrapper Completo
- Sincronizzazione bidirezionale dati
- Cache intelligente per ridurre chiamate API
- Fallback automatico in caso di errori
- Mapping automatico formati dati

## 🔒 Sicurezza Avanzata

### 🛡️ Protezioni Multi-Livello
- Sanitizzazione completa input
- Rate limiting per prevenire abuse
- Nonce verification per CSRF protection
- Validazione business logic robusta

## ⚡ Performance e Ottimizzazione

### 🚀 Cache Multi-Livello
- Object Cache (Redis/Memcached)
- WordPress Transients
- File Cache per persistenza
- Query database ottimizzate

## 🧪 Testing e Quality Assurance

### 📋 Suite Test Completa
- Unit test con PHPUnit
- Integration test per API
- End-to-end test con Cypress
- Performance test automatizzati

## 🚀 Deployment

### 🔄 CI/CD Pipeline
- Automated testing su ogni commit
- Deployment automatico staging/production
- Versionamento semantico automatico
- Rollback automatico in caso di errori

---

**© 2024 ThinkNow.it - Documentazione Tecnica v2.1.1**