From 64417331609c36365ea12fc956c195869d48682c Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Mon, 16 Nov 2026 11:46:05 +0100 Subject: [PATCH] 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 --- TODO.md | 93 +++++++++++++++ docs/README.md | 1 + ...-54-django-unico-framework-web-tre-aree.md | 42 +++++++ ...sqlite-wal-web-worker-processi-separati.md | 46 ++++++++ ...nt-individuali-permessi-mfa-dopo-pilota.md | 36 ++++++ ...e-pause-distinte-dopo-round-e-incidente.md | 38 ++++++ ...u-regtest-profilo-di-rete-configurabile.md | 37 ++++++ ...cchetto-senza-framework-ledger-simulato.md | 40 +++++++ docs/adr/ADR-60-pilota-solo-italiano.md | 29 +++++ docs/adr/README.md | 18 ++- docs/sito-e-app.md | 110 ++++++++++++++++++ 11 files changed, 489 insertions(+), 1 deletion(-) create mode 100644 TODO.md create mode 100644 docs/adr/ADR-54-django-unico-framework-web-tre-aree.md create mode 100644 docs/adr/ADR-55-sqlite-wal-web-worker-processi-separati.md create mode 100644 docs/adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md create mode 100644 docs/adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md create mode 100644 docs/adr/ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md create mode 100644 docs/adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md create mode 100644 docs/adr/ADR-60-pilota-solo-italiano.md create mode 100644 docs/sito-e-app.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..04385a0 --- /dev/null +++ b/TODO.md @@ -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//` | 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. diff --git a/docs/README.md b/docs/README.md index 6fcc8db..9c99d8e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | diff --git a/docs/adr/ADR-54-django-unico-framework-web-tre-aree.md b/docs/adr/ADR-54-django-unico-framework-web-tre-aree.md new file mode 100644 index 0000000..9129527 --- /dev/null +++ b/docs/adr/ADR-54-django-unico-framework-web-tre-aree.md @@ -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 diff --git a/docs/adr/ADR-55-sqlite-wal-web-worker-processi-separati.md b/docs/adr/ADR-55-sqlite-wal-web-worker-processi-separati.md new file mode 100644 index 0000000..69f0d90 --- /dev/null +++ b/docs/adr/ADR-55-sqlite-wal-web-worker-processi-separati.md @@ -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 diff --git a/docs/adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md b/docs/adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md new file mode 100644 index 0000000..d0fcb1a --- /dev/null +++ b/docs/adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md @@ -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 diff --git a/docs/adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md b/docs/adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md new file mode 100644 index 0000000..f2d5b9f --- /dev/null +++ b/docs/adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md @@ -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 diff --git a/docs/adr/ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md b/docs/adr/ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md new file mode 100644 index 0000000..3ebd943 --- /dev/null +++ b/docs/adr/ADR-58-alfa-su-regtest-profilo-di-rete-configurabile.md @@ -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 diff --git a/docs/adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md b/docs/adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md new file mode 100644 index 0000000..b529dcf --- /dev/null +++ b/docs/adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md @@ -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 diff --git a/docs/adr/ADR-60-pilota-solo-italiano.md b/docs/adr/ADR-60-pilota-solo-italiano.md new file mode 100644 index 0000000..fc934f3 --- /dev/null +++ b/docs/adr/ADR-60-pilota-solo-italiano.md @@ -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 diff --git a/docs/adr/README.md b/docs/adr/README.md index 4f43375..bd98142 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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 diff --git a/docs/sito-e-app.md b/docs/sito-e-app.md new file mode 100644 index 0000000..953d086 --- /dev/null +++ b/docs/sito-e-app.md @@ -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//` | 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.