Files
plm-lottery/docs/sito-e-app.md
T
davideandClaude Sonnet 5.5 eded058dbb A3: simulated ledger with idempotency (WEB-22, WEB-23, ADR-59, ARC-75..77, DAT-80)
One Ledger interface (deposit, bet, confirm, reject, exclude, payout) with a
simulated implementation chosen by LEDGER_BACKEND, refused on mainnet. Every
operation is a single write-locked transaction with its audit row; the same
request key is the same operation, a key reused for something else is an
error. The server validates round, deadline, the round's own quota, limits and
funds. The balance is derived from the ledger. Tests include six processes
racing on one SQLite file; the idempotency tests were checked to fail when
the replay is removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 13:23:29 +01:00

8.3 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, 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); 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.

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