Files
plm-lottery/docs/sito-e-app.md
T
davideandClaude Sonnet 5.5 0eba7bcfe6 A2: lottery models and database constraints (WEB-04, ADR-10, ADR-15, ADR-22, DAT-76..79, AUD-47)
LotteryConfig (single row, parameters and the three pause switches), Round
(single active round, own rules, split within the pool), Participation (one
bet per player and round, unique draw position), Movement (signed ledger,
idempotency key per player), ChainTransaction and an append-only AuditEntry
enforced by the model and by SQLite triggers. Every foreign key is PROTECT.
One test per constraint, each checked to hit the intended constraint.

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

134 lines
7.8 KiB
Markdown

# 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/<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](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.
- **[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](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.