Files
plm-lottery/docs/sito-e-app.md
T
davideandClaude Sonnet 5.5 fc23a75c9b A1: Django skeleton with web and worker processes (ADR-54, ADR-55, WEB-01, WEB-07, ARC-70..74)
Django 5.2 project (config/, apps/accounts with a custom User and
case-insensitive usernames, apps/lottery with the run_worker command,
apps/web with a placeholder home and /health/live, apps/ops), SQLite in WAL
with IMMEDIATE transactions, secrets and hosts from the environment. The
compose stack is now web + worker + caddy and serves https://localhost; the
old FastAPI service is out of the stack until roadmap D1. The three old
infrastructure tests follow the new Dockerfile and compose.

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

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

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