Gioca: the round, the player's funds and their bet; the bet is two steps (a confirmation screen that sends nothing, then an explicit confirm) with a fresh idempotency key per screen, and the server re-checks everything. Portafoglio: spendable apart from in-confirmation, deposit address with a QR of the player's own address, copy button, simulated test deposits. Movimenti: the player's own ledger, paged, stacked as cards on a phone. GET /app/stato/ feeds the page and its polling. Every view takes the user from the session only. Checked end to end in a real browser (Playwright): status moves from pending to confirmed without a reload, a double click is one bet. Mutation checks: cross-account leak, non-idempotent POST and unrestricted test-deposit amounts are all caught. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
21 KiB
Sito, web app e console operativa
Prefisso: WEB. Origine: ../TODO.md. Scelte: ADR-54
(framework e aree), ADR-56
(staff), ADR-57 (pause),
ADR-60 (lingua).
I requisiti sono *Stato:* da implementare salvo dove indicato diversamente; la
sequenza è in ../roadmap.md. Il vecchio sito è index.html con
backend FastAPI (vedi 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/<round_id>/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,HttpOnlyeSameSite. Stato: implementato (A5): sessione di 24 ore, cookieSecure/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; nessuna vista prende un utente dalla richiesta: un parametro
usercostruito a mano non cambia nulla. Stato: implementato per l'area giocatore (A7) · Test:tests/django/test_player.py::test_a_player_never_sees_another_players_data,test_user_ids_in_the_request_are_ignored,test_every_player_page_needs_a_session -
[WEB-04] Importi e saldi si rappresentano in unità minime intere (ADR-35); i parametri economici e temporali del round sono fissati alla sua apertura (ADR-10). 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. Stato: implementato per la home (A6, [WEB-14]) e per l'area giocatore (A7, [WEB-27]).
-
[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(stessodocker-compose.ymldi sempre,SITE_ADDRESSnon 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 cookieSecurevalgono 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. Gli stati: nessun round (fra due round, con l'orario di apertura quando è noto), puntate aperte (quota, chiusura e conto alla rovescia), in chiusura (anche oltre la scadenza se lo scheduler è in ritardo, ADR-23), estrazione in corso, pagamento in attesa, manutenzione (nessun round si aprirà, oppure puntate sospese; ADR-57). Un round in corso con la «pausa dopo il round» resta «puntate aperte» e avvisa che poi la lotteria si ferma. Il montepremi confermato è la quota del vincitore (70%) di ciò che è già confermato: mai più di ciò che sarà pagato; le puntate in volo si indicano a parte («+N in conferma»). La quota è quella del round, non quella corrente della configurazione. La pagina è renderizzata dal server, quindi funziona anche senza JavaScript. Stato: implementato (A6); il collegamento a «dove controllare il risultato» arriva con l'A8 · Codice:apps/lottery/status.py:public_state,apps/web/views.py:home,apps/web/templates/web/home.html· Test:tests/django/test_home.py(un test per stato, il montepremi confermato, la quota del round) - [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: implementato (A5, [WEB-52], e A6): «Partecipa» compare solo quando le puntate sono aperte e porta a/app/· Test:tests/django/test_home.py::test_participate_leads_to_the_player_area,test_participate_is_hidden_when_betting_is_not_possible - [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.
- [WEB-14] Aggiornamento della home.
GET /stato/restituisce, pubblico e mai in cache, lo stesso stato che la pagina mostra (una sola funzione li alimenta: non possono raccontare cose diverse), senza dati di account né del segreto del round; porta l'ora del server.home.js(esterno, senza dipendenze) fa scorrere il conto alla rovescia sull'ora del server, non su quella del visitatore; interroga/stato/ogni 5 secondi mentre la pagina è visibile, subito quando torna visibile o quando il conto arriva a zero, e più di rado dopo errori (fino a 30 s), mostrando «Connessione persa». Il testo del conto alla rovescia è lo stesso con e senza JavaScript. Stato: implementato (A6) · Codice:apps/web/views.py:state,apps/web/static/web/home.js· Test:tests/django/test_home.py::test_the_endpoint_and_the_page_tell_the_same_story,test_the_endpoint_exposes_no_account_data,test_the_script_is_valid_and_its_clock_arithmetic_is_right,test_the_server_and_the_script_write_the_countdown_the_same_way
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. Il menu segna la sezione corrente (
aria-current). Stato: implementato (A7) · Codice:apps/web/player_views.py:play,apps/web/templates/web/app_home.html· Test:tests/django/test_player.py::test_the_play_screen_shows_the_round_the_funds_and_the_bet_button,test_the_bet_button_is_hidden_without_funds_and_says_why - [WEB-21] Saldo spendibile e fondi in conferma sono distinti. Il deposito
mostra rete, indirizzo, QR, copia e stato delle conferme.
Il QR è sempre quello dell'indirizzo del giocatore (mai un indirizzo preso dalla richiesta); «Copia» è un pulsante che compare solo con
JavaScript, e senza di esso l'indirizzo resta un campo di sola lettura da selezionare. Il saldo mostrato include i fondi in conferma
ma la puntata usa solo il saldo spendibile ([BET-07], ADR-34). Il prelievo arriva con la Fase B (B9).
Stato: implementato (A7; indirizzo simulato fino alla B4) ·
Codice:
apps/web/player_views.py:wallet,wallet_qr,apps/web/static/web/wallet.js· Test:tests/django/test_player.py::test_the_wallet_separates_spendable_funds_from_funds_in_confirmation,test_the_wallet_shows_network_address_qr_and_a_copy_control,test_the_qr_takes_no_address_from_the_request - [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); anche la schermata (A7): la puntata è in due passi — la schermata di conferma mostra round e importo e non invia nulla; l'invio avviene solo con «Conferma e punta», e il server ricontrolla tutto (una pagina rimasta aperta mentre il round cambiava è rifiutata con un messaggio chiaro). Dopo l'invio la pagina mostra lo stato reale e un aggiornamento della pagina, anche da un altro browser, lo ritrova · Codice:apps/lottery/ledger.py:SimulatedLedger.place_bet,apps/web/player_views.py:bet· Test:tests/django/test_ledger.py,tests/django/test_player.py::test_the_confirmation_screen_shows_round_amount_and_funds_and_sends_nothing,test_a_stale_confirmation_is_refused_by_the_server_with_a_clear_message,test_a_page_reload_recovers_the_saved_state - [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]) e nel modulo di invio (A7): ogni schermata di conferma porta una chiave nuova, e inviarla due volte
è una sola puntata; la stessa conferma aperta in due schede è rifiutata come «hai già una puntata» ·
Test:
tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet,tests/django/test_player.py::test_sending_the_same_confirmation_twice_makes_one_bet,test_the_same_confirmation_opened_in_two_tabs_makes_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.
- [WEB-25] Movimenti.
/app/movimenti/elenca depositi, puntate, vincite, rimborsi e prelievi del solo giocatore, dal più recente, a pagine di 25, con data (UTC), operazione, stato (in conferma, confermato, non riuscito), importo con segno e transazione: il TXID abbreviato, collegato all'explorer seEXPLORER_TX_URLè configurato, e marcato «simulata» sul ledger simulato. Da telefono le righe diventano schede, così l'importo non esce mai dallo schermo; la tabella ha didascalia e intestazioni di colonna. Stato: implementato (A7) · Codice:apps/web/player_views.py:movements,apps/web/templates/web/movements.html· Test:tests/django/test_player.py::test_the_movements_are_listed_newest_first_with_sign_and_status,test_movements_are_paged,test_the_txid_links_to_the_explorer_when_one_is_configured - [WEB-26] Fondi di prova. Con il ledger simulato il portafoglio offre un deposito di prova da 10, 50 o 100 PLM che arriva «in conferma» e il worker conferma
pochi secondi dopo ([RND-42]); un importo diverso da quelli offerti non dà nulla, il doppio invio è un solo deposito, e con un ledger reale l'indirizzo non esiste (404)
e il modulo non compare.
Stato: implementato (A7) ·
Codice:
apps/web/player_views.py:simulated_deposit· Test:tests/django/test_player.py::test_a_test_deposit_arrives_in_confirmation_and_becomes_spendable,test_only_the_offered_amounts_are_accepted,test_test_deposits_exist_only_on_the_simulated_ledger - [WEB-27] Stato del giocatore.
GET /app/stato/(solo con sessione, mai in cache) è lo stato pubblico ([WEB-14]) più un bloccomecon i soli dati del giocatore: saldo spendibile e in conferma, la sua puntata nel round (stato e testo), se può puntare e perché no, e come è finito il suo ultimo round («hai vinto 21 PLM», «non hai vinto»). Una sola funzione (player_state) alimenta la pagina e l'endpoint;home.jsaggiorna lo stato della puntata e i saldi senza ricaricare. Stato: implementato (A7); verificato in un browser reale: dalla conferma «In attesa» a «Confermata» in circa 9 secondi senza ricaricare · Codice:apps/lottery/player.py:player_state,apps/web/player_views.py:player_state_json,apps/web/static/web/home.js· Test:tests/django/test_player.py::test_the_page_and_the_endpoint_tell_the_same_story,test_the_player_is_told_how_their_round_ended
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).
Il token
ADMIN_TOKENsparisce 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):
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), 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). Alla fine l'utente è già connesso e la registrazione è nell'audit (user_registered). La password è salvata con Argon2 (ADR-36). 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 attendere2 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 (risposta429conRetry-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 diX-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 scrivepassword_changednell'audit./app/profilo/mostra solo i dati dell'utente connesso ([WEB-03]). Stato: implementato (A5); le segnalazioni del profilo sono in [WEB-55] · 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 - [WEB-55] Segnalazioni. Dal profilo (
/app/profilo/) l'utente invia una segnalazione di un problema e vede lo stato delle proprie (aperta, letta, risolta); lo staff le gestisce da/admin/([WEB-32]) cambiandone lo stato, e ogni cambio è nell'audit. Il testo ha una lunghezza massima e l'invio è limitato per utente ([SEC-55]). Un utente vede solo le proprie segnalazioni ([WEB-03]). Stato: da implementare (A9: modello, sezione del profilo e gestione in/admin/).