From 530c740300182223d12863e18c97a9d7d2c962c9 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Mon, 16 Nov 2026 15:10:10 +0100 Subject: [PATCH] Narrow B-93 to the Django stack, add roadmap C6, merge TODO.md into roadmap.md Co-Authored-By: Claude Sonnet 5.5 --- BUGS.md | 60 ++++++++++-------------------- TODO.md | 93 ---------------------------------------------- docs/adr/README.md | 2 +- docs/sito-e-app.md | 2 +- roadmap.md | 28 +++++++++++++- 5 files changed, 48 insertions(+), 137 deletions(-) delete mode 100644 TODO.md diff --git a/BUGS.md b/BUGS.md index bae66a0..9551acf 100644 --- a/BUGS.md +++ b/BUGS.md @@ -1,48 +1,28 @@ # BUGS.md — open findings -Only the 2026-09-28 specification review (B-73 … B-100) still has open entries -(B-93). A finding is removed from this file once it is fixed, and -`git log --all --grep 'B-nn'` is the record of how it was closed. Per CLAUDE.md's -convention each entry gets its own commit with its own regression test, and the `B-nn` -marker goes in a comment next to the fix. - -# Audit of 2026-09-28 — specification review (B-73 … B-98) - -Fourth audit, run against the new specification in `docs/` rather than the code -alone: four independent reviews (coin/chain mechanics, money state machine, -DevOps, spec cross-validation), with the critical claims re-verified in code. -The target behaviour of every entry below is now written into `docs/` as -requirements marked `*Stato:* da implementare (B-nn)`; the Italian overview, the -design decisions and the implementation order are in -[docs/piano-correzioni.md](docs/piano-correzioni.md). The code has **not** been -changed yet. Same convention as above: one commit per entry, with its own -regression test, spec + code + test together. - -Design decisions taken with the owner on 2026-09-28 (they change existing -decisions, see `docs/limiti-noti.md`): - -- **Draw by commit-reveal.** The winner must not be computable by anyone who - controls block production, since PLM's hashrate (~22 TH/s) is rentable. -- **Never release funds on doubt.** A money-moving row is rolled back only on proof - (an explicit rejection, or its inputs confirmed-spent elsewhere), never on a - timeout or on one server's silence. -- **One pool address per round**, so a round's money, history and payout are - isolated from every other round's. -- **Deposits need 6 confirmations** (configurable), everything else keeps 1: the - deposit is the only input a user can double-spend. -- **Contain reorgs instead of pretending they don't happen:** detect them, pause - on deep ones, and pay out only what is verifiably on chain. +One finding is still open (B-93), narrowed to what applies to the Django stack. A finding is +removed from this file once it is fixed, and `git log --all --grep 'B-nn'` is the record of how it +was closed. Each entry gets its own commit with its own regression test, and the `B-nn` marker +goes in a comment next to the fix. The full history of every B-nn is in +[docs/storico-bug.md](docs/storico-bug.md); the owner of this one in the plan is roadmap step C6. ## Medium - ### B-93 — Deploys and rollbacks -A deploy with an open SSE stream never shuts down gracefully (uvicorn waits, Docker -kills after 10s); an older image cannot start on a newer DB; images are untagged; -`SITE_ADDRESS` passed per command reverts to `localhost` on the next plain -`docker compose up`. +On the Django stack (`docker-compose.yml`): -Fix: close SSE streams on shutdown, `stop_grace_period: 30s`, await task -cancellation; tag images per release; `SITE_ADDRESS` in `.env` with `${SITE_ADDRESS:?}`; -documented pre-deploy backup and downgrade procedure. +- every image is tagged `plm-lottery-web:local`, so there is no per-release tag and an older image + cannot be put back; +- no `stop_grace_period`: a worker stopped in the middle of a step gets Docker's default timeout; +- `SITE_ADDRESS` passed on the command line reverts to `localhost` on the next plain + `docker compose up`; +- there is no documented pre-deploy backup and no downgrade procedure, and an older image cannot + start on a database already migrated forward. + +(The old stack's part — SSE streams blocking a graceful shutdown, task cancellation — goes away +with roadmap D1.) + +Fix: tag images per release; `stop_grace_period: 30s` and let the worker finish its step on +SIGTERM; `SITE_ADDRESS` in `.env` read as `${SITE_ADDRESS:?}`; document the backup before a deploy +and the downgrade (restore the backup, start the previous tag). diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 04385a0..0000000 --- a/TODO.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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/adr/README.md b/docs/adr/README.md index bd98142..b9d84ea 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -102,7 +102,7 @@ Gli identificativi `ADR-NN` sono stabili e non si riusano (i primi 52 coincidono ## Migrazione a Django (accettate, implementazione da completare) -Origine: [../../TODO.md](../../TODO.md). Quando un ADR diventa *Accettata* e +Origine: il brief iniziale (`git show 6441733:TODO.md`). Quando un ADR diventa *Accettata* e implementata, quelli che sostituisce passano a *Sostituita da*. | ADR | Decisione | diff --git a/docs/sito-e-app.md b/docs/sito-e-app.md index 6094102..902afe2 100644 --- a/docs/sito-e-app.md +++ b/docs/sito-e-app.md @@ -1,6 +1,6 @@ # 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) +Prefisso: `WEB`. Origine: il brief iniziale (`git show 6441733: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). diff --git a/roadmap.md b/roadmap.md index 5e66aa8..177e321 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,9 +1,9 @@ # Roadmap — dal TODO al merge su main -Piano di lavoro **commit per commit** per completare [TODO.md](TODO.md) sul branch +Piano di lavoro **commit per commit** per completare il brief iniziale (la vecchia versione di `TODO.md`, commit `6441733`) sul branch `django-migration` e arrivare al merge su `main`. Le scelte sono negli ADR [54–60](docs/adr/README.md) e i requisiti in [docs/sito-e-app.md](docs/sito-e-app.md). -Il file è scritto in italiano come il TODO. +Il file è scritto in italiano. Le cose da fare a mano o da decidere stanno in fondo, nella sezione «Da fare a mano»: è l'unico elenco di caselle del progetto. ## Regole per ogni commit @@ -58,6 +58,7 @@ Non blocca il merge su `main` (la rete `mainnet` resta bloccata dall'ADR-58) ma - [ ] **C2 · Prova controllata con importi ridotti.** Ciclo completo su rete reale con importi minimi, includendo il **primo prelievo e RBF reali**; esito in `docs/`. - [ ] **C3 · Sicurezza e recupero.** Isolamento dei dati tra account, permessi staff, azioni di manutenzione, audit, ripristino da backup e riconciliazione dopo il ripristino. - [ ] **C4 · MFA TOTP e recupero dell'accesso.** Requisito di uscita dell'ADR-56 per lo staff, con codici di emergenza e verifica nelle viste e nelle azioni; `LIM` del pilota chiuso. +- [ ] **C6 · Deploy e rollback (B-93).** Immagini con tag per rilascio, `stop_grace_period` e arresto pulito del worker, `SITE_ADDRESS` obbligatorio in `.env`, procedura documentata di backup prima del deploy e di downgrade in `docs/operativita.md`. *Test:* il compose rifiuta di partire senza `SITE_ADDRESS`; un deploy con il worker a metà di un passo non lascia stato incoerente. - [ ] **C5 · Inquadramento legale.** Verifica della lotteria e della custodia di PLM nei mercati previsti: attività esterna al codice, con esito registrato in `docs/`. ## Fase D — Dismissione e merge @@ -78,3 +79,26 @@ Si può fare il merge quando: A1–A10, B1–B10, C1, C3, D1 e D2 sono completat | Due processi su un solo SQLite al posto dei blocchi in memoria | B6, B10 | vincoli nel database, `IMMEDIATE`, test di concorrenza; PostgreSQL pronto come passo successivo | | Perdere regole già corrette (B-nn) nella riscrittura sull'ORM | B4–B9 | la logica non cambia; i test esistenti diventano i test di equivalenza | | Prelievo e RBF mai provati con rete reale | B9, C2 | regtest in B, prova controllata in C2 | + +## Da fare a mano + +Cose che il codice non può fare da solo. I difetti trovati vanno in [BUGS.md](BUGS.md), non qui. + +**Ora (chiusura della Fase A)** + +- [ ] Avviare da zero: `cp .env.example .env`, impostare `DJANGO_SECRET_KEY`, `docker compose up -d --build`, aprire `https://localhost` ([setup.md](docs/setup.md)). +- [ ] Eseguire la [checklist di verifica](docs/checklist-verifica-sito.md) su telefono e su desktop; spuntare ogni voce lì e aprire un difetto in `BUGS.md` per ogni voce che non passa. +- [ ] Creare un account staff (`createsuperuser`), provare `/ops/`, i tre comandi di pausa e `/admin/` (segnalazioni, utenti). +- [ ] Creare un secondo account staff **non** superutente con i soli permessi `view_console` e `suspend_new_bets` e verificare che gli altri due comandi siano negati. +- [ ] Rileggere i commit di `django-migration` (A1–A10) prima di andare avanti; decidere se pubblicare il branch. + +**Decisioni da prendere** + +- [ ] Dove vanno i difetti nuovi quando `BUGS.md` sparirà (D1/D2): una sezione «aperti» in `docs/storico-bug.md` o un file nuovo. +- [ ] Quali server Electrum usare per la Fase B (almeno 2 per il quorum) e chi li gestisce. +- [ ] Chi sono gli operatori della Fase C e chi tiene il backup della chiave di cifratura dei seed. + +**Fuori dal codice (Fase C)** + +- [ ] Procurarsi PLM di prova e un indirizzo per la prova controllata con importi ridotti (C2). +- [ ] Scegliere dominio e hosting per la messa online; impostare `SITE_ADDRESS` in `.env`.