# 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`. *Stato:* implementato (A5): sessione di 24 ore, cookie `Secure`/`HttpOnly`/`SameSite=Lax`, CSRF su ogni modulo con pagina di errore leggibile · *Codice:* `config/settings.py`, `apps/web/views.py:csrf_failure` · *Test:* `tests/django/test_accounts.py::test_the_session_cookie_is_httponly_secure_and_samesite`, `test_a_form_without_the_csrf_token_is_refused` - **[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. *Stato:* base implementata (A5): layout fluido da 400 px, foglio di stile unico con tema chiaro/scuro, collegamento «Vai al contenuto», focus sempre visibile, etichette su ogni campo, errori annunciati (`role="alert"`), nessuno script né stile inline, pagine d'errore in italiano; la verifica su telefono e desktop con le schermate finali è l'A10 · *Codice:* `apps/web/templates/web/base.html`, `apps/web/static/web/site.css` · *Test:* `tests/django/test_accounts.py::test_every_page_is_responsive_and_keyboard_friendly`, `test_every_input_has_its_label`, `test_pages_use_no_inline_scripts_or_styles` - **[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. *Stato:* il ritorno alla destinazione interna è implementato (A5, [WEB-52]); il pulsante con l'A6. - **[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). *Stato:* validazione e stati implementati nel ledger (A3: round, scadenza, quota del round, limiti, fondi, `round_closing`, `already_betting`, `round_full`, `bets_suspended`, `balance_pending_confirmation`, rifiuto ed esclusione); la schermata con l'A7 · *Codice:* `apps/lottery/ledger.py:SimulatedLedger.place_bet` · *Test:* `tests/django/test_ledger.py` - **[WEB-23]** Un doppio invio della stessa richiesta produce una sola operazione logica (chiave di idempotenza associata alla richiesta). *Stato:* implementato nel ledger (A3, [ARC-76]); il modulo di invio con l'A7 · *Test:* `tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet` - **[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. ## 7 · Accesso e account - **[WEB-50]** **Registrazione.** `/registrati/` crea un account con nome utente di 3–32 caratteri `[A-Za-z0-9_.-]`, unico **senza distinzione fra maiuscole e minuscole** e salvato come digitato ([ADR-38](adr/ADR-38-username-unico-spazio-nomi-senza-distinzione.md)), e password di 8–256 caratteri da ripetere due volte ([SEC-17]). Non si raccoglie alcuna email, quindi non esiste un recupero automatico ([ADR-37](adr/ADR-37-nessun-recupero-password-reset.md)). Alla fine l'utente è già connesso e la registrazione è nell'audit (`user_registered`). La password è salvata con Argon2 ([ADR-36](adr/ADR-36-password-argon2-sessioni-jwt-hs256-24.md)). *Stato:* implementato (A5) · *Codice:* `apps/accounts/views.py:register_view`, `apps/accounts/forms.py:RegisterForm`, `apps/accounts/validators.py` · *Test:* `tests/django/test_accounts.py::test_registering_creates_the_account_and_signs_in`, `test_a_name_that_differs_only_by_case_is_taken`, `test_password_length_limits` - **[WEB-51]** **Accesso.** `/accedi/` ammette il nome utente in qualunque combinazione di maiuscole e minuscole e risponde **allo stesso modo** a un nome inesistente e a una password sbagliata ([SEC-19]); al login la sessione riceve una chiave nuova; un account disattivato non entra; un utente già connesso che apre `/accedi/` o `/registrati/` è rimandato avanti. *Stato:* implementato (A5) · *Codice:* `apps/accounts/views.py:login_view`, `apps/accounts/backends.py:CaseInsensitiveBackend` · *Test:* `tests/django/test_accounts.py::test_unknown_name_and_wrong_password_look_the_same`, `test_signing_in_gives_a_fresh_session`, `test_login_ignores_the_case_of_the_name` - **[WEB-52]** **Destinazione dopo l'accesso.** `?next=` (e il campo nascosto che lo porta attraverso un errore o il passaggio alla registrazione) è rispettato **solo se è un percorso del sito**: un indirizzo esterno, `//host`, una barra rovesciata o uno schema (`javascript:`) ricadono su `/app/`, così la pagina di accesso non può mandare altrove. `/app/` e `/app/profilo/` senza sessione rimandano ad `/accedi/?next=…`. *Stato:* implementato (A5) · *Codice:* `apps/accounts/views.py:safe_next` · *Test:* `tests/django/test_accounts.py::test_an_open_redirect_is_refused`, `test_an_internal_destination_is_honoured`, `test_the_destination_survives_a_wrong_password_and_the_trip_to_registration` - **[WEB-53]** **Limiti ai tentativi, condivisi fra i processi.** Lo stato sta nel database (`ThrottleEvent`), non in memoria ([ARC-72]). *Accesso:* dopo 5 errori sullo stesso nome (20 sullo stesso indirizzo) ogni tentativo deve attendere `2 s · 2^(errori − soglia)`, fino a 300 s dall'ultimo errore; la serie finisce dopo 900 s di quiete; un accesso riuscito azzera il nome ma **non** l'indirizzo; durante l'attesa non si guarda nemmeno la password (risposta `429` con `Retry-After`). *Registrazione:* al massimo 5 account all'ora per indirizzo, contando gli account creati e non i tentativi. *Cambio password:* 5 errori sulla password attuale per utente, poi attesa ([SEC-54]). L'indirizzo del cliente è l'**ultimo** elemento di `X-Forwarded-For`, quello scritto dal nostro proxy ([B-54]). *Stato:* implementato (A5) · *Codice:* `apps/accounts/throttle.py`, `apps/accounts/client_ip.py` · *Test:* `tests/django/test_accounts.py::test_five_wrong_guesses_lock_the_name_for_a_while`, `test_the_wait_doubles_with_every_further_failure_and_is_capped`, `test_spraying_one_password_over_many_names_is_caught_by_the_address`, `test_one_address_can_register_five_accounts_an_hour`, `test_a_forged_forwarded_header_cannot_dodge_the_ip_controls` - **[WEB-54]** **Uscita e cambio password.** L'uscita è solo `POST` (con CSRF) e chiude la sessione. Il cambio password chiede la password attuale, chiude **tutte le altre sessioni** (una sessione è legata all'impronta della password con cui nasce, [B-34]), lascia connessa quella corrente e scrive `password_changed` nell'audit. `/app/profilo/` mostra solo i dati dell'utente connesso ([WEB-03]). *Stato:* implementato (A5); le segnalazioni del profilo non sono ancora previste · *Codice:* `apps/accounts/views.py:logout_view`, `apps/accounts/views.py:profile_view` · *Test:* `tests/django/test_accounts.py::test_a_password_change_signs_out_every_other_session`, `test_signing_out_ends_the_session_and_only_by_post`, `test_the_profile_shows_only_the_owner`