Files
plm-lottery/docs/sito-e-app.md
T
davideandClaude Sonnet 5.5 939c113043 A6: public home with the six states, confirmed prize, countdown and polling (WEB-05, WEB-10, WEB-11, WEB-14; LIM-24, WEB-55)
public_state() feeds both the server-rendered home (works without JavaScript)
and GET /stato/, so they cannot disagree: none, open, closing, drawing, paying
and maintenance, the round's own quota, the winner's 70% of the *confirmed*
pool, bets in flight apart, and the closing time on the server's clock. home.js
counts down against the server clock and polls every 5 s while visible. Checked
in headless Chromium on mobile and desktop widths. Also records the profile
reports (WEB-55, roadmap A9) and the name-lock trade-off (LIM-24).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 14:19:56 +01:00

17 KiB
Raw Blame History

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, 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); 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]); per l'area giocatore con l'A7.

  • [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. 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.
  • [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). 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):

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 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 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/).