# Prenotazioni da amministrazione — revisione 3

Questa revisione corregge il 503 nel test HTTP 61T durante l'installazione. L'installer attivava correttamente la manutenzione, ma il test ne leggeva lo stato nella stessa cartella `storage` del progetto. I tre test dell'installer usano ora cartelle temporanee proprie anche per storage, stato di manutenzione e cache dei servizi. Il middleware reale rimane attivo ed è verificato esplicitamente: soltanto lo stato del test è separato da quello del progetto.

Sono incluse le precedenti correzioni del test 61D: colonna `external_paid_at` nel solo database temporaneo, gestione del reindirizzamento POST del preventivo e aspettativa CSV aggiornata per la colonna Origine. Non viene aggiunta una migration per `external_paid_at`.

## Funzione

In Gestione strutture → Prenotazioni compare **Nuova prenotazione** per gli amministratori autorizzati. Si sceglie struttura, tariffa, targa, inizio effettivo, fine, intestatario, email facoltativa, modalità e causale interna. La funzione non richiede un account del cittadino.

La gratuità è esplicita (`admin_free`), richiede una causale e permette un intervallo amministrativo indipendente dalla durata commerciale della tariffa. Contanti (`admin_cash`) e POS esterno (`admin_pos`) usano il preventivo del motore tariffario esistente: il periodo deve corrispondere alla validità del prodotto. Il prezzo non è modificabile manualmente. L’operatore deve confermare che l’intero importo è già stato incassato. Non sono create transazioni PayPal, Fabrick o wallet.

L’anteprima dura 20 minuti. Alla conferma il prezzo viene ricalcolato, l’area viene bloccata durante la transazione e prenotazione/sosta vengono create insieme. La ripetizione della stessa conferma restituisce lo stesso titolo. Inizio precedente all’emissione consentito; fine necessariamente futura.

Sono disponibili stampa/salvataggio PDF dal browser, invio email tramite il mailer già configurato e annullamento con motivazione. Causale, pratica e operatore rimangono nell’audit interno, esclusi da stampa, email e WS. L’annullamento conserva l’incasso registrato e non simula un rimborso.

## Permessi e configurazione

Nuovo permesso comunale `facilities.bookings.manage`, assegnato per impostazione predefinita al ruolo amministratore comunale. Per assegnazioni con elenco esplicito dei permessi è necessario abilitarlo nella gestione ruoli. Operatori e consultatori non lo ricevono automaticamente. Restano necessari accesso al comune, modulo strutture e permesso di monitoraggio. Il Gestore struttura resta escluso dall’amministrazione.

In `config/dpass_facilities.php`, `admin_booking_methods` permette di restringere le modalità per ID comune. Esempio: `[12 => ['free','pos'], 25 => []]`. Se non specificato sono disponibili gratuita, contanti e POS. Un array vuoto disabilita le nuove emissioni nel comune. L’aggiornamento richiede il normale rinnovo della cache di configurazione.

## Disponibilità e ingressi importati

La capienza `parking_spaces_count` deve essere configurata e positiva. Il controllo usa i periodi delle soste attive/future/importate e delle riserve online ancora valide. Le amministrative non consumano il limite giornaliero online, ma partecipano alla disponibilità stimata e ai monitoraggi. Il percorso online controlla anche la capienza complessiva quando il periodo è occupato da titoli amministrativi; una conferma provider tardiva senza spazio va in verifica pagamento.

Una targa con una sosta o prenotazione sovrapposta viene rifiutata, anche se importata da Mobility App. **Questa versione non associa un titolo a un ingresso importato esistente.** Serve verificarlo e gestirlo attraverso il flusso della fonte; non annullare o duplicare un ingresso reale per aggirare il controllo. I dati importati possono arrivare in ritardo e la disponibilità rimane una stima, non una rilevazione fisica.

## WS casse: schema 1.1

Lo stesso endpoint include i titoli amministrativi confermati, attivi o futuri, con sosta coerente. Annullati, terminati e revocati sono esclusi. Aggiunto per ogni titolo:

```json
{"regime":"gratuito_autorizzato","importo":"0.00"}
```

Per i titoli pagati: `regime: prepagato`. I precedenti titoli online conservano il comportamento economico preesistente. `schema_version` passa a `1.1`; il nuovo campo partecipa a `versione`. Il feed sintetico di collaudo usa anch’esso schema 1.1 con regime prepagato; per collaudare una gratuità amministrativa emettere un titolo gratuito nella copia di prova.

**Concordare e collaudare schema 1.1 con il software delle casse prima di usare gratuità amministrative in esercizio.** La cassa deve esentare l’intervallo coperto da `gratuito_autorizzato`, non limitarsi a sottrarre zero euro. Per le revoche deve applicare la riconciliazione dell’elenco completo già prevista: l’assenza da una scansione completa rimuove il titolo locale. Il WS non comanda la barriera.

## Incassi e tracciabilità

I report contabili distinguono contanti/POS usando il canale reale e l’origine Amministrazione; comprendono anche pagamenti relativi a titoli futuri. L’incasso rimane contabilizzato quando il titolo viene annullato. Le gratuità non generano movimenti finanziari. Il registro/CSV delle prenotazioni mostra l’origine. Le informazioni interne sono conservate nello snapshot della prenotazione.

## Installazione nella copia di sviluppo/collaudo

Il pacchetto contiene solo i file modificati e nuovi rispetto a `C:\aaa_deploy\dpass.zip`, con hash SHA-256 in `manifest.json`. Conservare un backup dei file e del database. Copiare il contenuto di `files/` nella radice Laravel conservando i percorsi; se i file locali differiscono dagli hash iniziali, riconciliare prima le differenze.

Con PHP >= 8.3 e le dipendenze del progetto già installate:

```sh
php artisan migrate --path=database/migrations/2026_10_13_180000_add_admin_origin_to_facility_bookings.php
php artisan optimize:clear
php tests/Support/DPass/AdminFacilityBookingsSmoke.php
php tests/Support/DPass/FacilityBookingsSmoke.php --database
php tests/Support/DPass/FacilityCashApiSmoke.php --database
```

La migration aggiunge `origin` con default `online`; le prenotazioni precedenti restano online. Non rimuove dati. È richiesta la migration ospiti preesistente del 21 settembre 2026 per il titolare senza account. I test usano esclusivamente SQLite in memoria e richiedono `pdo_sqlite`; non aprono il database configurato nel progetto.

Il rollback della nuova migration è intenzionalmente bloccato per preservare lo storico. Dopo emissioni amministrative evitare un semplice ripristino dei vecchi file: il vecchio codice non riconosce questi titoli e i loro incassi. Valutare un ripristino coordinato dal backup.

## Verifiche effettuate in questa consegna

Test applicativi eseguiti con PHP 8.3.6 di Ubuntu e `pdo_sqlite`, sulla copia isolata del progetto. Tutti i test usano database in memoria; i servizi esterni sono simulati.

| Test | Controlli superati |
|---|---:|
| Prenotazioni amministrative | 44 |
| Prenotazioni strutture esistenti (61D) | 92 |
| WS casse (61T) | 153 |
| Report incassi giornalieri (61Q) | 173 |
| Navigazione amministrativa e CSV (61P) | 159 |
| Pagamenti Fabrick (61N) | 168 |
| Prenotazioni ospite (61H) | 386 |
| Totale | 1.175 |

I controlli amministrativi includono l'emissione gratuita e a pagamento, il doppio clic, la capienza, l'annullamento con conservazione dell'incasso, il contenuto del WS e la riservatezza delle causali, un errore simulato durante la creazione della sosta con rollback completo, il modulo, l'anteprima, la conferma obbligatoria e il titolo stampabile. Il controllo in sola lettura sul progetto Ubuntu ha confermato la compatibilità dei file ripristinati dopo il precedente tentativo.

È stata inoltre provata l'intera sequenza dell'installer in una copia temporanea Ubuntu, senza copiare il file `.env` operativo e con un database SQLite fittizio. La revisione 2 riproduce il medesimo errore `[503,200]` e ripristina file e disponibilità, senza modificare il database. La revisione 3 completa test, migration e riapertura dell'applicazione, conservando una prenotazione precedente con origine `online`. Una seconda installazione lascia invariati dati e manutenzione già attiva. Durante ogni test sono confrontati gli hash del database e del file di manutenzione del progetto di prova: entrambi rimangono invariati. I log e il riepilogo sono nella cartella `verifiche` dello ZIP.

Non sono state eseguite migrazioni sul database reale, invii email reali, pubblicazioni o collaudi con casse fisiche. La prova della migration è su SQLite, non sul database operativo. Resta da verificare con il fornitore delle casse l'interpretazione del regime `gratuito_autorizzato`; il superamento dei test DPass non verifica il software esterno.

Questa versione usa intestatario manuale; non include ricerca utenti esistenti, variazione manuale del prezzo, rimborsi di contanti/POS o collegamento agli ingressi importati.
