Calendario disponibilità + slot

Modulo «Calendario disponibilità + slot»: motore fondazionale per esporre disponibilità prenotabile su calendario con slot orari/giornalieri/multi-giorno e regole di apertura configurabili per risorsa, servizio, operatore, sede o stagione. È la base tecnica e UX su cui poggiano tutti gli altri moduli booking (#8324 prenotazione con caparra Stripe, #8325 sync Google/Outlook, area cliente #8326). Modello dati core: tabella `risorse` (nome, categoria, capacità massima simultanea, durata default slot in minuti, buffer pre/post slot in minuti, sede/location, tag, attivo bool, immagine, ordine), tabella `availability_rules` (risorsa_id, tipo regola `weekly`/`date_range`/`one_off`, giorno_settimana 0-6 per weekly, data_inizio/data_fine per range, ora_inizio/ora_fine per finestra giornaliera, slot_duration_min override, capacità override, priorità per stratificare regole, attiva bool, note), tabella `availability_exceptions` (risorsa_id, data, tipo `closed`/`open`/`reduced_capacity`/`custom_hours`, ora_inizio/ora_fine se custom, capacità override, motivo testuale, ricorrente bool per festività annuali), tabella `slots_generated` (risorsa_id, data, ora_inizio, ora_fine, capacità_residua, stato `available`/`fully_booked`/`partially_booked`/`closed`/`held`, hash regola di origine per invalidazione cache), tabella `slot_holds` (slot_id, sessione_id/booking_draft_id, scadenza timestamp, motivo) per riservare slot temporaneamente in fase di checkout senza ancora confermare. Regole orarie: configurazione via UI admin con interfaccia tipo Google Calendar settings (es. «lunedì-venerdì 9:00-13:00 e 14:00-18:00 con slot 30 min, capacità 1; sabato 10:00-13:00 slot 60 min, capacità 2; domenica chiuso»), supporto multi-fascia stesso giorno (mattina+pomeriggio con pausa pranzo non prenotabile), regole per periodo specifico (es. «orario estivo dal 15 giugno al 15 settembre 8:00-20:00»), regole one-off per evento singolo (es. «sabato 5 luglio aperto extra 21:00-23:00 per evento serale»), override eccezioni con priorità (regola weekly base + range stagionale + exception giornaliera vince in cascata), supporto fuso orario configurabile per risorsa (utile per noleggi multi-sede o servizi internazionali) con conversione automatica per cliente in browser TZ. Tipi di slot: `time_slot` (fascia oraria es. 9:00-9:30 per visita medica/lezione/sala riunioni), `day_slot` (giornata intera con check-in/check-out es. noleggio camper, casa vacanza), `multi_day_range` (range continuo es. soggiorno hotel 3 notti, noleggio settimanale), `open_slot` (durata variabile selezionata da cliente con durata min/max configurate es. sala riunioni da 1 a 4 ore in 30 min step). Capacità e concorrenza: ciascuno slot ha capacità (1 per risorse esclusive come camera/auto/sala; N per risorse condivise come palestra, corso gruppo, ristorante con coperti); pannello mostra in real-time `capacità_residua = capacità - booking confermati - hold attivi`; quando capacità_residua=0 lo slot diventa `fully_booked` e non più selezionabile; gestione race condition su prenotazione simultanea con transazione DB + lock pessimistico/ottimistico (`SELECT ... FOR UPDATE` o version column) per evitare overbooking. Buffer tempi: configurazione buffer pre e post slot (es. pulizia camera 30min prima e dopo, setup attrezzatura 15min, viaggio operatore tra appuntamenti); il buffer riduce slot disponibili adiacenti automaticamente senza essere visibile al cliente come slot dedicato; supporto buffer differenziato per tipo servizio (visita standard 0 buffer, visita complessa 15 min). Lead time e advance booking: `min_lead_time` (preavviso minimo prenotazione, es. «non prima di 2h da adesso» o «non oggi, solo da domani»), `max_advance_window` (limite massimo nel futuro, es. «prenotabile fino a 90 giorni avanti»), `cutoff_time` (deadline giornaliera oltre cui non si prenota per il giorno stesso, es. «entro le 18:00 per slot di domani»), `blackout_periods` (manutenzione, ferie con date range). Generazione slot e cache: job artisan `php artisan calendar:generate-slots {risorsa?} {--from=} {--to=}` che materializza slot per finestra futura (default 90 giorni) applicando regole+eccezioni in cascata, esegue ogni notte + on-demand su modifica regola tramite event listener; cache slot per risorsa+data in Redis con TTL e invalidazione su update; endpoint pubblico `GET /api/calendar/{risorsa}/availability?from=&to=` paginato per FullCalendar con payload ottimizzato (solo dati necessari render). UI calendario admin: vista mensile/settimanale/giornaliera/lista basata su FullCalendar (`@fullcalendar/core` + plugin `daygrid`/`timegrid`/`list`/`resource-timegrid` per risorsa multipla affiancate, con `resource-timeline` per timeline orizzontale stile Gantt utile per noleggio veicoli, sale, operatori), drag&drop per spostare booking tra slot con validazione regole, click su slot vuoto crea booking, click su booking apre dettaglio modal, colori slot per stato (verde libero, giallo parziale, rosso pieno, grigio chiuso, blu hold), filtro per risorsa/categoria/operatore, ricerca rapida, export agenda PDF/iCal, sync visivo evidenza eccezioni e blackout. UI calendario pubblico: widget embeddabile (blade component `<x-availability-calendar :risorsa="$id" />` oppure JS standalone con tag `<script src="https://app.tld/widget/calendar.js" data-resource="123">`), responsive mobile-first con vista mensile compatta per scelta data + lista slot orari per giorno selezionato (pattern Calendly/Bookings), localizzazione it/en/es/fr/de con `Intl.DateTimeFormat`, evidenza primo slot disponibile in evidenza, badge «posti residui N» se capacità>1 con soglia configurabile mostra/nascondi, fallback grafico se nessuno slot disponibile nel mese con CTA «vai al prossimo mese con disponibilità» calcolato server-side. Integrazione con booking: API REST/Livewire per (1) `query` slot disponibili con filtri, (2) `hold` slot per N minuti durante checkout con generazione `slot_hold_id` da passare al modulo prenotazione (es. #8324 caparra Stripe consuma hold), (3) `release` hold su abbandono/timeout/cancel, (4) `confirm` hold trasformandolo in booking definitivo decrementando `capacità_residua`, (5) `move` booking tra slot con ricalcolo, (6) `cancel` booking restituendo capacità. Multi-risorsa e dipendenze: supporto «risorsa aggregata» (es. servizio richiede simultaneamente operatore + sala + attrezzatura → slot disponibile solo se tutte le sub-risorse libere stesso slot, calcolato come intersezione disponibilità), supporto allocazione automatica risorsa libera (es. cliente prenota «taglio capelli», sistema sceglie primo parrucchiere libero in quella fascia secondo round-robin o preferenza cliente), gestione operatore con calendario personale (regole orarie individuali per dipendente, ferie singole, turni). Festività e ricorrenze: tabella `holidays` precaricata con festività nazionali italiane (1gen, 6gen, Pasquetta variabile, 25apr, 1mag, 2giu, 15ago, 1nov, 8dic, 25dic, 26dic) + festività regionali/locali configurabili (es. patrono cittadino), opzione apertura forzata anche in festività per risorsa specifica, calcolo Pasqua via algoritmo Gauss per Pasquetta annuale, eccezioni ricorrenti annuali (es. chiuso ogni 15 agosto). Conflitti e validazione: quando admin modifica regola che invaliderebbe booking esistenti (es. riduce orario apertura, abbassa capacità, chiude giorno con prenotazioni), il sistema mostra lista booking impattati e propone azioni (sposta a slot vicino libero, contatta cliente per riprenotazione con template email da #8331, cancella con rimborso automatico se applicabile da #8324), conferma esplicita richiesta prima di applicare. Modifiche batch: tool admin per modifica massiva (es. «applica orario estivo a tutte le risorse categoria X dal Y al Z», «chiudi tutti i giorni festivi 2026 per sede Milano»), preview impact prima di salvare. Performance e scala: indici DB su (risorsa_id, data, ora_inizio), partitioning tabella `slots_generated` per anno se >1M record, query disponibilità ottimizzata con materialized view o tabella aggregata `availability_summary` (risorsa, mese, primo_slot_libero, totale_slot_liberi) per dashboard rapide; benchmark target <100ms per query disponibilità singolo giorno, <300ms per mese. Sync e webhook: eventi Laravel emessi su mutazione (`SlotCreated`, `SlotBlocked`, `SlotReleased`, `RuleUpdated`) consumabili da listener interni (cache invalidation, audit log #8330) e da webhook esterni configurabili per partner/integratori; integrazione bidirezionale con #8325 calendar sync (slot creati in Footility appaiono in Google/Outlook agenda operatore, eventi creati direttamente in Google/Outlook bloccano slot Footility per evitare doppia prenotazione). Audit e storico: log immutabile in #8330 audit log azioni utente con `actor`+`action`+`before`+`after`+`timestamp`+`ip` per ogni modifica regola/eccezione/forzatura admin, utile per troubleshooting «perché lo slot è bloccato» con risposta motivata. UX patterns ricorrenti: «mostra prossimi N slot disponibili» (caso d'uso lista compatta tipo Doctolib), «scegli operatore preferito poi slot» vs «scegli slot poi sistema assegna operatore» (toggle configurabile), «proposta multi-slot pacchetto» (es. corso 10 lezioni → calendario propone 10 slot ricorrenti settimanali), «liste d'attesa» su slot esauriti con notifica auto se si libera per cancellazione (tabella `waiting_list`+notifica via #8331/#8332). Comandi artisan e job: `php artisan calendar:generate-slots --days=120` (rigenera finestra), `php artisan calendar:cleanup-stale-holds` (rilascia hold scaduti, scheduler ogni minuto), `php artisan calendar:notify-waiting-list` (alert su liberazione slot), `php artisan calendar:health-check` (verifica integrità: zero overbooking, zero slot orfani senza regola, copertura finestra futura). API e integrazioni esterne: endpoint pubblico documentato OpenAPI per partner (B2B revenue management, channel manager hotel come Octorate/Smoobu/Booking.com via mapping iCal export per blocchi slot), import iCal/CalDAV come fonte autoritativa esterna (es. Airbnb blocca date → import bloccato in Footility), export iCal feed sottoscrivibile per ogni risorsa (`/calendar/{risorsa}.ics`) per visualizzazione esterna read-only. Sicurezza: regole accesso slot via Laravel policies (admin vede tutto, operatore vede solo proprie risorse, cliente vede solo disponibilità pubblica senza dati interni capacità), rate limit su query availability per prevenire scraping, signed URL per widget embed cross-domain con whitelist domini cliente. Casi d'uso: noleggi (Holiday Self Drive: ogni veicolo è risorsa con capacità 1, slot day_slot, blackout per manutenzione/revisione, sync iCal con calendario operativo officina), studi medici e professionali (operatore=risorsa, slot 15/30/60 min secondo prestazione, capacità 1, regole settimanali con pause pranzo, ferie estive blackout), palestre e centri fitness (corso=risorsa con capacità N partecipanti, slot orari ricorrenti settimanali, lista d'attesa, integrazione lezioni a tema), hotel e case vacanza (camera=risorsa, slot multi_day_range con check-in/check-out specifici, regole stagionalità prezzi+disponibilità), ristoranti (tavolo=risorsa con capacità coperti, slot orari per turno cena/pranzo, buffer pulizia 30min tra turni), saloni di bellezza (operatore+poltrona+attrezzatura come risorse aggregate), sale riunioni e coworking (sala=risorsa con slot open_slot durata variabile, capacità persone, buffer pulizia, integrazione card access). Differenza da semplice prenotazione manuale operatore (rischio doppia prenotazione, agenda cartacea/Excel): qui automation + multi-canale + zero overbooking garantito. Differenza da Google Calendar/Outlook puri (no regole orarie strutturate, no capacità multi, no slot generation, no UI cliente self-service): questi sono sistemi agenda non motori booking; il modulo li affianca via #8325 sync senza sostituirli. Differenza da SaaS booking esterni (Calendly, SimplyBook, Bookings.com): qui controllo dati, brand, UX integrata sito, no fee per booking, regole italiane (festività, IVA, GDPR) native. Estensioni future: AI-powered demand forecasting (predice slot ad alta domanda per dynamic pricing), suggerimento automatico nuovi orari basato su demand pattern, A/B test su capacità/orari per ottimizzare conversion, integrazione mappa geo (#8342) per scelta sede più vicina con disponibilità, smart routing operatore con bilanciamento carico, mobile app operatore per gestione slot on-the-go con notifiche push (#8334). Costo: 2-3 giorni modello dati + migration + seeder regole base, 2 giorni motore generazione slot + cache + invalidation + job scheduler, 2-3 giorni UI admin calendario con FullCalendar multi-vista + drag&drop + gestione regole/eccezioni, 2 giorni widget pubblico embed + API availability + hold/release/confirm, 1-2 giorni eccezioni/festività/blackout + UI batch modifiche, 1-2 giorni integrazione policies + audit + multi-risorsa aggregata + waiting list, 1-2 giorni iCal import/export + sync con #8325, 1-2 giorni testing concorrenza + performance + carico. Dipendenze: nessuna obbligatoria (modulo foundational), abilita #8324 prenotazione con caparra Stripe (consuma hold/slot), #8325 sync Google/Outlook (estende slot con eventi esterni), #8326 area cliente (mostra prenotazioni cliente con relativi slot), #8331 mail per notifiche modifica/cancellazione, #8332 SMS / #8334 push per alert real-time slot liberato a lista attesa.