Spec the Django migration: ADR-54..60 and docs/sito-e-app.md (WEB-01..WEB-44)

Docs-first step for the move to Django per TODO.md: framework and areas
(ADR-54, WEB-01..07), SQLite WAL with separate web/worker processes
(ADR-55), individual staff accounts with MFA deferred to phase C (ADR-56),
distinct pause commands (ADR-57), regtest alpha with a network profile
(ADR-58), framework-free PLM engine with a simulated ledger in phase A
(ADR-59), Italian-only pilot (ADR-60). The site must be browsable on
localhost before a domain exists (WEB-07).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 11:46:05 +01:00
1 parent 9b8a331bba
commit 6441733160
11 files changed
+489 -1

No files matched your search

+93
View File
@@ -0,0 +1,93 @@
# TODO — PLM Lottery con Django
**Obiettivo.** Realizzare un unico sito responsive con una home pubblica, una web app per giocare in PLM e una console riservata all’operatore. La prima milestone è un round completo con fondi simulati, verificabile dal browser.
**Base di partenza.** La revisione del commit `575f1a5` ha rilevato che la home, il login e la dashboard condividono l’attuale `index.html`. Il backend FastAPI contiene già il motore della lotteria, il collegamento a Electrum e la riconciliazione delle transazioni. Il pannello esistente usa un token condiviso. [Codice di riferimento](https://santantonio.sytes.net/davide/plm-lottery/src/commit/575f1a535482f19d97e27de9497382c02d8ae6a1)
## 1. Specifiche del sito e della web app
Un solo dominio, un unico progetto Django e uno stile condiviso. La parte pubblica porta il visitatore all’accesso. La web app mostra dati e operazioni dell’account. La console operativa e Django Admin richiedono un account staff con permessi espliciti.
| Percorso proposto | Accesso | Funzione |
| --- | --- | --- |
| `/` | Pubblico | Stato del round, quota, montepremi confermato, chiusura e pulsante «Partecipa». |
| `/guida/` e `/regole/` | Pubblico | Funzionamento del gioco, custodia dei PLM, conferme, commissioni, vincita e prelievo. |
| `/risultati/` e `/risultati/<round_id>/` | Pubblico | Archivio delle estrazioni, esito, prova verificabile e stato del pagamento. |
| `/accedi/` e `/registrati/` | Pubblico | Login e registrazione con ritorno alla destinazione interna prevista. |
| `/app/` | Giocatore autenticato | Round corrente, disponibilità e stato della propria partecipazione. |
| `/app/portafoglio/` | Giocatore autenticato | Saldo spendibile, fondi in conferma, indirizzo di deposito con QR, richiesta di prelievo. |
| `/app/movimenti/` | Giocatore autenticato | Storico di depositi, puntate, vincite e prelievi. |
| `/app/profilo/` | Giocatore autenticato | Impostazioni, cambio password, segnalazioni e logout. |
| `/ops/` | Staff con MFA | Supervisione della lotteria e azioni operative autorizzate. |
| `/admin/` | Staff con MFA e permessi sui modelli | Gestione interna di utenti e segnalazioni, consultazione dei record di gioco. |
### Area pubblica
- [ ] Mostrare quota, montepremi **confermato** e chiusura, usando l’ora server come riferimento. Prevedere gli stati «nessun round», «puntate aperte», «in chiusura», «estrazione in corso», «pagamento in attesa» e «manutenzione».
- [ ] Collegare «Partecipa» a `/app/`. Se serve il login, riportare il visitatore alla schermata di gioco dopo l’accesso. Il pulsante apre il flusso, mentre l’invio della puntata richiede conferma esplicita.
- [ ] Pubblicare risultati e prova dell’estrazione. Rendere riproducibile il calcolo con i dati previsti dal protocollo, senza esporre username o dati dell’account. La prova può contenere identificativi on-chain richiesti dall’algoritmo. Mostrare il pagamento come confermato solo quando lo è.
- [ ] Completare guida e regole. Spiegare quota, ripartizione 70/30, commissioni e attesa delle conferme con gli stessi termini usati nell’area giocatore. Sostituire la promessa attuale di accredito immediato.
**Verifica.** Da smartphone, un visitatore capisce quanto costa partecipare, quando chiude il round e dove controllare il risultato senza autenticarsi.
### Area giocatore
- [ ] Separare «Gioca», «Portafoglio» e «Movimenti». Nel flusso principale dare priorità alla quota, allo stato del round e alla puntata dell’utente.
- [ ] Distinguere saldo spendibile e fondi in conferma. Per il deposito mostrare rete PLM, indirizzo, QR, copia e stato delle conferme.
- [ ] Prima di inviare una puntata mostrare round e importo. Far validare al server disponibilità, quota, limiti e stato del round. Dopo l’invio mostrare lo stato effettivo, compresi attesa, conferma ed eventuale rifiuto o esclusione. Un aggiornamento della pagina recupera lo stato salvato.
- [ ] Per il prelievo mostrare indirizzo, importo richiesto, commissione e importo netto previsto prima della conferma. Nello storico distinguere lo stato dell’operazione dal TXID corrente e collegarlo all’explorer PLM quando disponibile.
- [ ] Verificare che ogni richiesta legga o modifichi soltanto i dati dell’utente autorizzato. Usare sessioni Django, protezione CSRF per le scritture e cookie di sessione con attributi adeguati.
**Verifica.** Il giocatore può depositare, puntare, uscire e rientrare per ritrovare saldo e operazioni. Un doppio invio della stessa richiesta produce una sola operazione logica.
### Area operatore
- [ ] Creare un account staff individuale con MFA e recupero dell’accesso. Verificare l’MFA e i permessi sia nelle viste sia nelle azioni su `/ops/` e `/admin/`. Sostituire il token admin condiviso al passaggio alla nuova area.
- [ ] Mostrare su `/ops/` round in corso, prossima scadenza, salute di Electrum e del worker, operazioni in ritardo, ultima riconciliazione e motivo di eventuali pause.
- [ ] Implementare **«Pausa dopo il round in corso»**. Il round attivo continua fino al pagamento e il successivo resta sospeso. Implementare **«Sospendi nuove puntate»** come comando distinto per gli incidenti, mantenendo il monitoraggio delle operazioni già inviate. Gestire separatamente qualsiasi sospensione dei prelievi.
- [ ] Richiedere conferma e motivazione per pausa, ripresa e modifiche critiche. Mostrare quali operazioni continuano e quali verifiche servono prima della ripresa. Per le pause automatiche, far riesaminare la causa attraverso il servizio applicativo.
- [ ] Usare Django Admin per utenti e segnalazioni. Mostrare round chiusi, transazioni e audit in sola lettura. Eseguire le azioni operative tramite i servizi della lotteria e registrare attore, data, azione, motivo ed esito. Riservare il recupero delle chiavi a una procedura dedicata fuori dal pannello web.
**Verifica.** Un giocatore e uno staff senza il permesso specifico non possono eseguire un comando operativo. Una pausa autorizzata si riflette sul sito con l’effetto previsto e compare nell’audit.
## 2. Architettura di partenza
| Componente | Scelta |
| --- | --- |
| Applicazione web | Django 5.2 LTS, URL distinti per le tre aree, autenticazione e sessioni Django. Definire il modello utente prima delle prime migrazioni. |
| Interfaccia | Template Django, CSS responsive e JavaScript mirato per timer e aggiornamenti. Per la prima versione, aggiornare i dati con richieste periodiche mirate e recupero dello stato al rientro. Rivalutare SSE se serve una latenza inferiore. |
| Persistenza | Django ORM e migrazioni Django. PostgreSQL proposto appena web e worker iniziano a scrivere sugli stessi dati. Validare i lock e i vincoli sul database effettivo. |
| Motore PLM | Riutilizzare derivazione degli indirizzi, costruzione delle transazioni, client Electrum e calcolo dell’estrazione dopo aver verificato le dipendenze. Adattare i servizi oggi legati a SQLAlchemy, SQLite e FastAPI. |
| Processi in background | Worker Python per listener Electrum, conferme, avanzamento round, invio, riconciliazione e RBF. Stato persistito nel database e accesso alle chiavi di firma riservato al processo autorizzato. |
Riferimenti ufficiali · [Django e versioni supportate](https://www.djangoproject.com/download/) · [Autenticazione](https://docs.djangoproject.com/en/5.2/topics/auth/default/) · [Django Admin](https://docs.djangoproject.com/en/5.2/ref/contrib/admin/) · [Transazioni ORM](https://docs.djangoproject.com/en/5.2/topics/db/transactions/)
## 3. Sequenza di sviluppo
### Fase A — Fondamenta e primo round simulato
- [ ] Creare un branch dedicato. Aggiungere il progetto Django e mappare le funzionalità esistenti verso le nuove pagine, servizi e processi in background.
- [ ] Definire modelli e vincoli per account, round, partecipazioni, movimenti, transazioni e audit. Fissare i parametri economici e temporali del round alla sua apertura. Rappresentare gli importi in unità minime intere.
- [ ] Costruire le tre aree essenziali. Collegare autenticazione staff, audit e pausa. Usare dati e fondi simulati per completare il percorso **home → login → deposito → puntata → estrazione → risultato pubblico**.
- [ ] Testare il percorso su telefono e desktop, con navigazione da tastiera e stati di errore, attesa e conferma.
**Uscita dalla fase.** Un giocatore completa il round dimostrativo, l’operatore può seguirlo e metterlo in pausa per il round successivo, e un visitatore può verificarne l’esito.
### Fase B — Integrazione del motore PLM
- [ ] Portare i test di riferimento per indirizzi HD, costruzione delle transazioni e prova dell’estrazione. A parità di input, verificare gli stessi indirizzi, importi, output e risultato.
- [ ] Sostituire i lock in memoria con una garanzia condivisa tra web e worker. Prenotare atomicamente gli UTXO, impedire che puntata e prelievo spendano gli stessi input e mantenere il vincolo di un solo round attivo.
- [ ] Salvare l’operazione e la transazione firmata prima del broadcast. Associare un identificativo idempotente alla richiesta. In caso di timeout, riconciliare con la catena prima di liberare gli input o creare una nuova spesa. Mantenere la relazione con tutti i TXID di eventuali sostituzioni RBF.
- [ ] Collegare deposito, puntata, estrazione verificabile, pagamento 70/30, prelievo e storico. Conservare le regole attuali su conferme, quorum Electrum e riorganizzazioni quando si migra la logica.
- [ ] Se ci sono utenti o fondi da migrare, provare l’importazione su una copia. Verificare indirizzi, indici HD, importi, UTXO, round, versioni TXID e operazioni pendenti. Definire come mantenere l’accesso agli account esistenti. In fase di passaggio, mantenere un solo sistema autorizzato a firmare e inviare.
**Uscita dalla fase.** Il flusso è completo nell’ambiente di prova. Un riavvio durante il broadcast, due richieste concorrenti e una riorganizzazione simulata lasciano dati e fondi riconciliabili.
### Fase C — Verifiche prima dell’uso pubblico
- [ ] Automatizzare i casi critici di integrazione Electrum, compresi indisponibilità, riconnessione, broadcast ambiguo, conferma di una versione RBF precedente e ripresa dopo un riavvio.
- [ ] Eseguire una prova controllata con importi ridotti per il ciclo completo, includendo prelievo e RBF, indicati nella revisione del repository come percorsi ancora da verificare con un invio reale.
- [ ] Verificare isolamento dei dati tra account, MFA e permessi staff, azioni di manutenzione, audit, recupero da backup e riconciliazione dopo il ripristino.
- [ ] Verificare l’inquadramento della lotteria e della custodia di PLM nei mercati previsti prima di accettare fondi dal pubblico.
**Primo traguardo da implementare.** Una home pubblica con il round corrente e un pulsante «Partecipa» che conduce all’area autenticata. Collegare la stessa partita simulata alla console staff e pubblicare il risultato al termine.
+1
View File
@@ -45,6 +45,7 @@ Punto d'ingresso narrativo: [come-funziona.md](come-funziona.md).
| [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | `TX` | Ciclo di vita delle transazioni, RBF, riconciliazione |
| [connessione-electrum.md](connessione-electrum.md) | `ELC` | Accesso alla rete PLM e difese |
| [architettura.md](architettura.md) | `ARC` | Struttura del codice, processi, frontend, test |
| [sito-e-app.md](sito-e-app.md) | `WEB` | Sito pubblico, web app del giocatore, console operativa, pause (migrazione a Django, da implementare) |
| [modello-dati.md](modello-dati.md) | `DAT` | Tabelle, campi, stati, vincoli |
| [api.md](api.md) | `API` | Endpoint, risposte, codici di errore |
| [sicurezza.md](sicurezza.md) | `SEC` | Fiducia, chiavi, autenticazione, limiti sui tentativi |
@@ -0,0 +1,42 @@
# ADR-54 — Django è l'unico framework web, con tre aree distinte sullo stesso dominio
- **Stato:** Accettata — implementazione da completare
- **Area:** Interfacce e lingue
- **Funzionalità:** WEB
- **Sostituisce (quando implementata):** [ADR-36](ADR-36-password-argon2-sessioni-jwt-hs256-24.md) per le sessioni, [ADR-50](ADR-50-frontend-statici-senza-framework-ne-build.md), [ADR-46](ADR-46-canale-sse-aggiunta-polling-sostituto.md)
## Contesto
Oggi `index.html` serve insieme home, login e dashboard, con un backend
FastAPI e un pannello admin a token condiviso. Il sito deve avere una parte
pubblica, una web app per il giocatore e una console per l'operatore, con
stile condiviso e permessi separati.
## Decisione
**Un solo progetto Django 5.2 LTS** serve le tre aree con template lato server,
autenticazione e sessioni Django, protezione CSRF e un solo foglio di stile.
Aree e percorsi sono in [sito-e-app.md](../sito-e-app.md) (`WEB-01`). Il
modello utente è definito prima della prima migrazione. I dati in tempo
reale si aggiornano con richieste periodiche mirate (polling) e con il
recupero dello stato al rientro; SSE si rivaluta solo se serve una latenza
inferiore.
## Alternative scartate
- Restare su FastAPI e aggiungere pagine — richiede di riscrivere a mano
sessioni, CSRF, permessi e amministrazione che Django fornisce.
- SPA con API JSON separata — build e doppio stato in più, senza beneficio per
un sito di poche schermate.
- Convivenza FastAPI + Django — la piattaforma non è ancora in uso, quindi
non c'è nulla da proteggere con una migrazione graduale: si lavora su un
branch e si rimuove FastAPI quando Django copre gli stessi requisiti.
## Conseguenze
- I vecchi requisiti `API` e i frontend statici restano in vigore finché non
sono sostituiti; ogni requisito rimosso lo è con la regola `~~ID~~`.
- Il pilota si prova in locale su `localhost` prima che esista il dominio ([WEB-07]).
- Requisiti che la attuano: `WEB-01` … `WEB-07` ([sito-e-app.md](../sito-e-app.md)).
*Codice:* da implementare · *Test:* da implementare
@@ -0,0 +1,46 @@
# ADR-55 — SQLite in WAL condiviso da due processi: web e worker
- **Stato:** Accettata — implementazione da completare
- **Area:** Configurazione e ambiente
- **Funzionalità:** ARC, DAT
- **Sostituisce (quando implementata):** [ADR-13](ADR-13-processo-file-sqlite.md)
## Contesto
I compiti di fondo (listener Electrum, conferme, avanzamento dei round,
invio, riconciliazione, RBF) devono continuare anche se il processo web si
riavvia o si blocca. Oggi vivono nello stesso processo del web, e i blocchi
per-utente e il canale SSE sono in memoria: non funzionano fra due processi.
## Decisione
**Il web e il worker sono due processi separati che scrivono nello stesso
file SQLite in modalità WAL**, con `synchronous=FULL` e transazioni di
scrittura aperte in modo `IMMEDIATE` (opzione `transaction_mode` del backend
SQLite di Django). Il worker è un management command (`manage.py run_worker`)
con un servizio dedicato in `docker-compose.yml`. La coordinazione non usa
memoria condivisa: si basa su vincoli e indici del database ([ADR-22](ADR-22-piu-round-attivo-come-invariante-database.md)),
su transazioni brevi e sulla prenotazione degli UTXO nel database. Gli importi
restano interi in unità minime ([ADR-35](ADR-35-aritmetica-satoshi-interi.md)).
**PostgreSQL è rinviato** a dopo il pilota: si introduce quando la
concorrenza lo richiede. L'accesso passa dall'ORM e da una sola funzione per
le transazioni di scrittura, così il passaggio tocca pochi punti.
## Alternative scartate
- PostgreSQL subito — per un pilota con un solo operatore e pochi
giocatori aggiunge un servizio da gestire senza risolvere un problema
presente.
- Un solo processo con thread di fondo — un riavvio del web interrompe i
round, e con più worker del server web i compiti di fondo si duplicano.
- Redis per i blocchi — dipendenza in più; i vincoli del database bastano.
## Conseguenze
- I blocchi per-utente in memoria (`tx/locks.py`) e il limitatore in memoria
vanno sostituiti da garanzie nel database ([LIM-18] cade per la parte web/worker).
- Un solo scrittore alla volta: accettato per la scala del pilota.
- Requisiti: `ARC-70` … `ARC-72` ([architettura.md](../architettura.md)), da scrivere con l'implementazione.
*Codice:* da implementare · *Test:* da implementare
@@ -0,0 +1,36 @@
# ADR-56 — L'operatore usa account individuali con permessi espliciti; la MFA arriva prima dell'uso pubblico
- **Stato:** Accettata — implementazione da completare
- **Area:** Sicurezza
- **Funzionalità:** WEB, SEC, AUD
- **Sostituisce (quando implementata):** [ADR-40](ADR-40-l-amministrazione-usa-unico-token-condiviso.md)
## Contesto
L'amministrazione oggi usa un token condiviso (`ADMIN_TOKEN`): nessuna
identità per persona, nessun permesso distinto, e una fuga ha un impatto
enorme (esportazione di chiavi, reset delle password).
## Decisione
**Ogni operatore ha un account staff individuale con permessi Django espliciti
per modello e per comando**, verificati sia nelle viste sia nelle azioni di
`/ops/` e `/admin/`; l'audit registra attore, data, azione, motivo ed esito.
Il token condiviso sparisce al passaggio alla nuova area.
**La MFA (TOTP) non è nel pilota/MVP ma è un requisito di uscita della Fase C**:
senza di lei non si accettano fondi dal pubblico. Il recupero delle chiavi
resta una procedura dedicata fuori dal pannello web ([ADR-39](ADR-39-l-esportazione-chiave-privata-wif-utente.md) va rivista in quella sede).
## Alternative scartate
- MFA subito — rallenta il pilota su regtest, dove non c'è denaro reale.
- Mantenere il token — nessuna identità e blast radius alto.
## Conseguenze
- Nel pilota l'accesso staff è protetto solo da password: l'ambiente deve
restare privato (regtest, rete non pubblica). Il limite è registrato come `LIM` all'implementazione.
- Requisiti: `WEB-30` … `WEB-34` ([sito-e-app.md](../sito-e-app.md)).
*Codice:* da implementare · *Test:* da implementare
@@ -0,0 +1,38 @@
# ADR-57 — Due pause distinte: «dopo il round in corso» e «sospendi nuove puntate»
- **Stato:** Accettata — implementazione da completare
- **Area:** Round ed estrazione
- **Funzionalità:** RND, WEB
- **Collegata a:** [ADR-28](ADR-28-pausa-manutenzione-ferma-round-successivo.md), [ADR-29](ADR-29-senza-fee-address-apre-nessun-round.md)
## Contesto
La pausa di manutenzione esistente ferma solo l'apertura del round
successivo. Un incidente richiede invece di fermare subito le nuove puntate,
continuando però a seguire le operazioni già inviate. I prelievi sono un'altra
cosa ancora.
## Decisione
**Esistono tre comandi operativi distinti, ciascuno con conferma, motivazione
e voce di audit**:
1. **«Pausa dopo il round in corso»** — il round attivo prosegue fino al
pagamento, il successivo non si apre (è il comportamento di [ADR-28](ADR-28-pausa-manutenzione-ferma-round-successivo.md)).
2. **«Sospendi nuove puntate»** — per gli incidenti: nessuna nuova puntata
subito; le operazioni già inviate restano monitorate e riconciliate.
3. **Sospensione dei prelievi** — separata dalle altre due.
Le pause automatiche (`paused_reason`) si riesaminano passando dal servizio
applicativo. Le azioni staff usano i servizi della lotteria, mai modifiche
dirette ai dati dal pannello.
## Alternative scartate
- Un solo interruttore — non distingue manutenzione programmata e incidente.
## Conseguenze
- Requisiti: `WEB-40` … `WEB-44` ([sito-e-app.md](../sito-e-app.md)); `RND` e `DAT` da aggiornare con l'implementazione.
*Codice:* da implementare · *Test:* da implementare
@@ -0,0 +1,37 @@
# ADR-58 — L'alfa gira su regtest; la rete è un profilo di configurazione
- **Stato:** Accettata — implementazione da completare
- **Area:** Custodia, chiavi e indirizzi
- **Funzionalità:** ELC, REG, ARC
- **Collegata a:** [ADR-04](ADR-04-accesso-rete-via-protocollo-electrum.md), [ADR-05](ADR-05-indirizzi-bech32-plm-plm1-come-destinazione.md)
## Contesto
Per i test alfa non si usa denaro reale. L'ambiente `plm-regtest` fornisce
un nodo Palladium in regtest e un server Fulcrum, dove i blocchi si generano a
richiesta, così un round completo si prova in pochi minuti e le
riorganizzazioni si simulano. I parametri vengono da `palladiumcore`
(`chainparams.cpp`): hrp `rplm`, genesis `0f9188f1…2206`, powLimit
`7fff…ff`, porta P2P 28444, prefissi base58 e chiavi estese come testnet.
## Decisione
**La rete è un profilo selezionato dalla configurazione (`PLM_NETWORK` =
`regtest` | `mainnet`)**, che fissa hrp, prefissi, genesis atteso dall'handshake
([ELC-30]), powLimit e coin type. Il pilota usa `regtest`. Il profilo `mainnet`
resta vietato finché le verifiche della Fase C non sono chiuse: l'avvio con
`mainnet` richiede una conferma esplicita in configurazione.
## Alternative scartate
- Testnet pubblica — blocchi non controllabili, lenta per i test dei round.
- Fondi simulati ovunque — non prova nulla del motore PLM (vedi [ADR-59](ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md) per la sola Fase A).
## Conseguenze
- Gli indirizzi dell'alfa iniziano con `rplm1…`: la validazione dei prelievi
([ADR-05](ADR-05-indirizzi-bech32-plm-plm1-come-destinazione.md)) usa l'hrp del profilo.
- I test di integrazione automatici possono usare il regtest locale.
- Requisiti: `ELC` e `REG` da aggiornare con l'implementazione.
*Codice:* da implementare · *Test:* da implementare
@@ -0,0 +1,40 @@
# ADR-59 — Il motore PLM è un pacchetto senza framework; la Fase A usa un ledger simulato
- **Stato:** Accettata — implementazione da completare
- **Area:** Architettura
- **Funzionalità:** ARC, TX, RND
- **Collegata a:** [ADR-54](ADR-54-django-unico-framework-web-tre-aree.md), [ADR-55](ADR-55-sqlite-wal-web-worker-processi-separati.md)
## Contesto
Derivazione degli indirizzi, costruzione e firma delle transazioni, client
Electrum, validazione degli header e calcolo dell'estrazione non dipendono dal
database né da FastAPI. I servizi di puntata, prelievo, deposito, scheduler e
riconciliazione sì (SQLAlchemy). Il TODO vuole un round completo verificabile
dal browser prima di integrare il motore.
## Decisione
**I moduli senza database passano così come sono in un pacchetto separato
(`plm_engine`), senza dipendere da Django; i servizi che toccano il database
vengono riscritti sull'ORM Django con la stessa logica.** I 758 test del
motore puro restano e sono la prova di equivalenza (stessi indirizzi, importi,
output e risultato a parità di input).
**Nella Fase A i movimenti di denaro passano da un ledger simulato** dietro la
stessa interfaccia dei servizi (deposito, puntata, pagamento). Nella Fase B
l'implementazione simulata si sostituisce con quella che usa Electrum, senza
cambiare viste né modelli.
## Alternative scartate
- Riscrivere tutto da zero — perde 758 test e anni di correzioni (B-nn).
- Integrare subito il motore — il sito sarebbe verificabile solo con la
catena disponibile; il ledger simulato isola i problemi.
## Conseguenze
- Il ledger simulato non esiste in produzione: è escluso dal profilo `mainnet`.
- Requisiti: `ARC` da aggiornare con l'implementazione.
*Codice:* da implementare · *Test:* da implementare
+29
View File
@@ -0,0 +1,29 @@
# ADR-60 — Il pilota è solo in italiano
- **Stato:** Accettata — implementazione da completare
- **Area:** Interfacce e lingue
- **Funzionalità:** WEB
- **Sostituisce (quando implementata):** parzialmente [ADR-48](ADR-48-pagine-l-utente-report-bug-7.md) e [ADR-49](ADR-49-pannello-admin-pagina-guida-tradotti.md)
## Contesto
Le pagine attuali hanno 7 lingue mantenute a mano in `i18n.js`. Il nuovo sito
riscrive tutte le schermate e i testi cambiano ancora molto.
## Decisione
**Il pilota ha testi solo in italiano**, scritti nei template Django con i
meccanismi di traduzione di Django (`gettext`) già predisposti, così le altre
lingue si aggiungono dopo senza toccare i template. Il contratto d'errore
dell'API (`code` stabile, messaggio, `params`) resta come criterio per
mappare i messaggi.
## Alternative scartate
- Mantenere le 7 lingue — raddoppia il lavoro mentre i testi cambiano.
## Conseguenze
- Le lingue straniere escono dal pilota, non dal progetto: si registra come `LIM`.
*Codice:* da implementare · *Test:* da implementare
+17 -1
View File
@@ -100,6 +100,21 @@ Gli identificativi `ADR-NN` sono stabili e non si riusano (i primi 52 coincidono
| [ADR-49](ADR-49-pannello-admin-pagina-guida-tradotti.md) | Il pannello `/admin` e la pagina `/guida` non sono tradotti |
| [ADR-50](ADR-50-frontend-statici-senza-framework-ne-build.md) | Frontend statici, senza framework né build |
## Migrazione a Django (accettate, implementazione da completare)
Origine: [../../TODO.md](../../TODO.md). Quando un ADR diventa *Accettata* e
implementata, quelli che sostituisce passano a *Sostituita da*.
| ADR | Decisione |
|---|---|
| [ADR-54](ADR-54-django-unico-framework-web-tre-aree.md) | Django è l'unico framework web, con tre aree distinte sullo stesso dominio |
| [ADR-55](ADR-55-sqlite-wal-web-worker-processi-separati.md) | SQLite in WAL condiviso da due processi: web e worker (PostgreSQL rinviato) |
| [ADR-56](ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md) | Account staff individuali con permessi espliciti; MFA prima dell'uso pubblico |
| [ADR-57](ADR-57-due-pause-distinte-dopo-round-e-incidente.md) | Due pause distinte: dopo il round in corso e sospensione delle nuove puntate |
| [ADR-58](ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md) | L'alfa gira su regtest; la rete è un profilo di configurazione |
| [ADR-59](ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md) | Il motore PLM è un pacchetto senza framework; la Fase A usa un ledger simulato |
| [ADR-60](ADR-60-pilota-solo-italiano.md) | Il pilota è solo in italiano |
## Funzionalità → ADR
Per ogni funzionalità, gli ADR da leggere prima di toccarla.
@@ -119,7 +134,8 @@ Per ogni funzionalità, gli ADR da leggere prima di toccarla.
| Segnalazioni di bug | `API` | [api.md](../api.md) | 45 |
| Tempo reale (SSE) | `ARC` | [architettura.md](../architettura.md) | 46 |
| Interfacce e lingue | `ARC`, `API` | [architettura.md](../architettura.md) | 47, 48, 49, 50 |
| Configurazione e ambiente | `ARC`, `OPS` | [architettura.md](../architettura.md), [operativita.md](../operativita.md) | 08, 09, 10, 11, 12, 13 |
| Configurazione e ambiente | `ARC`, `OPS` | [architettura.md](../architettura.md), [operativita.md](../operativita.md) | 08, 09, 10, 11, 12, 13, 55, 58 |
| Sito, web app, console operativa | `WEB` | [sito-e-app.md](../sito-e-app.md) | 54, 56, 57, 59, 60 |
## Le decisioni del 2026-09-28
+110
View File
@@ -0,0 +1,110 @@
# 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).
Tutti i requisiti di questo documento sono `*Stato:* da implementare`: oggi
il 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 |
*Codice:* da implementare · *Test:* da implementare
- **[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)).
- **[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]).
## 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.