# Sito, web app e console operativa Prefisso: `WEB`. Origine: [../TODO.md](../TODO.md). Scelte: [ADR-54](adr/ADR-54-django-unico-framework-web-tre-aree.md) (framework e aree), [ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md) (staff), [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md) (pause), [ADR-60](adr/ADR-60-pilota-solo-italiano.md) (lingua). I requisiti sono `*Stato:* da implementare` salvo dove indicato diversamente; la sequenza è in [../roadmap.md](../roadmap.md). Il vecchio sito è `index.html` con backend FastAPI (vedi [architettura.md](architettura.md)). ## 1 · Struttura - **[WEB-01]** Un solo dominio e un solo progetto Django servono tre aree: pubblica, giocatore e staff, con uno stile condiviso: | Percorso | Accesso | Funzione | |---|---|---| | `/` | pubblico | stato del round, quota, montepremi confermato, chiusura, «Partecipa» | | `/guida/`, `/regole/` | pubblico | funzionamento, custodia, conferme, commissioni, vincita, prelievo | | `/risultati/`, `/risultati//` | pubblico | archivio estrazioni, esito, prova, stato del pagamento | | `/accedi/`, `/registrati/` | pubblico | accesso e registrazione, con ritorno alla destinazione interna | | `/app/` | giocatore | round corrente, disponibilità, propria partecipazione | | `/app/portafoglio/` | giocatore | saldo spendibile, fondi in conferma, indirizzo con QR, prelievo | | `/app/movimenti/` | giocatore | storico di depositi, puntate, vincite, prelievi | | `/app/profilo/` | giocatore | impostazioni, password, segnalazioni, logout | | `/ops/` | staff | supervisione e azioni operative autorizzate | | `/admin/` | staff con permessi sui modelli | utenti e segnalazioni; record di gioco in sola lettura | *Stato:* scheletro (A1): progetto Django, `/` segnaposto, `/admin/` · *Codice:* `config/urls.py`, `apps/web/urls.py` · *Test:* `tests/django/test_scaffold.py::test_home_answers_on_localhost` - **[WEB-02]** L'autenticazione usa le sessioni Django; ogni scrittura è protetta da CSRF e il cookie di sessione ha gli attributi `Secure`, `HttpOnly` e `SameSite`. - **[WEB-03]** Ogni richiesta dell'area giocatore legge o modifica soltanto i dati dell'utente autenticato; un identificativo di un altro utente dà 404. - **[WEB-04]** Importi e saldi si rappresentano in unità minime intere ([ADR-35](adr/ADR-35-aritmetica-satoshi-interi.md)); i parametri economici e temporali del round sono fissati alla sua apertura ([ADR-10](adr/ADR-10-parametri-round-fotografati-all-apertura.md)). *Stato:* colonne e vincoli implementati (A2, [DAT-76]…[DAT-78]); la copia all'apertura con A4 · *Test:* `tests/django/test_models.py::test_amounts_are_integers_only` - **[WEB-05]** I dati che cambiano (stato del round, saldo, esito) si aggiornano con richieste periodiche mirate e si recuperano al rientro nella pagina; ricaricare non perde lo stato salvato. - **[WEB-06]** Le pagine sono utilizzabili da smartphone e da desktop e navigabili da tastiera, con stati distinti di errore, attesa e conferma. - **[WEB-07]** Il sito si avvia e si naviga in locale su `http://localhost` (stesso `docker-compose.yml` di sempre, `SITE_ADDRESS` non impostato) con regtest e ledger simulato, senza dominio né configurazioni esterne. Il dominio definitivo si aggiunge solo con la configurazione (`SITE_ADDRESS`, `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), senza modifiche al codice, e i cookie `Secure` valgono solo dove c'è HTTPS ([WEB-02]). *Stato:* implementato (A1) · *Codice:* `config/settings.py`, `docker-compose.yml`, `Caddyfile` · *Test:* `tests/django/test_scaffold.py::test_domain_comes_from_configuration_only`, `test_unknown_host_is_refused` ## 2 · Area pubblica - **[WEB-10]** `/` mostra quota, montepremi **confermato** e chiusura, con l'ora del server come riferimento, e uno fra gli stati: nessun round, puntate aperte, in chiusura, estrazione in corso, pagamento in attesa, manutenzione. - **[WEB-11]** «Partecipa» porta a `/app/`; se serve il login, dopo l'accesso riporta alla schermata di gioco. Il pulsante apre il flusso: la puntata richiede una conferma esplicita. - **[WEB-12]** `/risultati/` pubblica esito e prova dell'estrazione, riproducibile con i dati del protocollo ([RND-14]…[RND-20]), senza username né dati dell'account. Il pagamento risulta confermato solo quando lo è. - **[WEB-13]** Guida e regole usano gli stessi termini dell'area giocatore (quota, ripartizione 70/30, commissioni, attesa delle conferme) e non promettono l'accredito immediato. ## 3 · Area giocatore - **[WEB-20]** «Gioca», «Portafoglio» e «Movimenti» sono schermate separate; nel flusso principale hanno priorità quota, stato del round e puntata dell'utente. - **[WEB-21]** Saldo spendibile e fondi in conferma sono distinti. Il deposito mostra rete, indirizzo, QR, copia e stato delle conferme. - **[WEB-22]** Prima di inviare una puntata si mostrano round e importo; il server valida disponibilità, quota, limiti e stato del round. Dopo l'invio si mostra lo stato effettivo (attesa, conferma, rifiuto o esclusione). - **[WEB-23]** Un doppio invio della stessa richiesta produce una sola operazione logica (chiave di idempotenza associata alla richiesta). - **[WEB-24]** Il prelievo mostra, prima della conferma, indirizzo, importo richiesto, commissione e importo netto previsto. Lo storico distingue lo stato dell'operazione dal TXID corrente e lo collega all'explorer quando disponibile. ## 4 · Console operativa - **[WEB-30]** Ogni operatore ha un account staff individuale; `/ops/` e `/admin/` richiedono i permessi espliciti, verificati nelle viste e nelle azioni. - **[WEB-31]** `/ops/` mostra round in corso, prossima scadenza, salute di Electrum e del worker, operazioni in ritardo, ultima riconciliazione e il motivo di eventuali pause. - **[WEB-32]** Django Admin gestisce utenti e segnalazioni; round chiusi, transazioni e audit sono in sola lettura. Le azioni operative passano dai servizi della lotteria e registrano attore, data, azione, motivo ed esito. - **[WEB-33]** Il recupero delle chiavi non è esposto dal pannello web: è una procedura dedicata fuori dal web. - **[WEB-34]** La MFA TOTP e il recupero dell'accesso sono requisiti di uscita della Fase C, non del pilota ([ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md)). Il token `ADMIN_TOKEN` sparisce al passaggio alla nuova area. ## 5 · Pause - **[WEB-40]** «Pausa dopo il round in corso»: il round attivo continua fino al pagamento, il successivo resta sospeso. - **[WEB-41]** «Sospendi nuove puntate»: comando distinto per gli incidenti; nessuna nuova puntata, ma le operazioni già inviate restano monitorate. - **[WEB-42]** La sospensione dei prelievi è un comando separato dalle altre due. - **[WEB-43]** Pausa, ripresa e modifiche critiche richiedono conferma e motivazione; la console mostra quali operazioni continuano e quali verifiche servono prima della ripresa. Le pause automatiche si riesaminano dal servizio applicativo. - **[WEB-44]** Ogni comando operativo è negato a un giocatore e a uno staff senza il permesso specifico, si riflette sul sito con l'effetto previsto e compare nell'audit. ## 6 · Avvio in locale Per navigare il sito su `https://localhost` (certificato autofirmato: l'avviso del browser alla prima visita è atteso): ```bash mkdir -p data/db cp .env.example .env # poi impostare DJANGO_SECRET_KEY (almeno 50 caratteri): python3 -c "import secrets; print(secrets.token_urlsafe(64))" docker compose up -d --build ``` Servizi: `web` (Django + gunicorn, applica le migrazioni), `worker` ([ARC-71]) e `caddy`. Con un dominio reale basta `SITE_ADDRESS=lottery.example.com docker compose up -d` ([WEB-07]). Il vecchio `docs/setup.md` e `docs/running-the-server.md` descrivono lo stack FastAPI, che non è più nel compose.