Narrow B-93 to the Django stack, add roadmap C6, merge TODO.md into roadmap.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 15:10:10 +01:00
1 parent 6509cedd7c
commit 530c740300
5 files changed
+48 -137

No files matched your search

+20 -40
View File
@@ -1,48 +1,28 @@
# BUGS.md — open findings # BUGS.md — open findings
Only the 2026-09-28 specification review (B-73 … B-100) still has open entries One finding is still open (B-93), narrowed to what applies to the Django stack. A finding is
(B-93). A finding is removed from this file once it is fixed, and removed from this file once it is fixed, and `git log --all --grep 'B-nn'` is the record of how it
`git log --all --grep 'B-nn'` is the record of how it was closed. Per CLAUDE.md's was closed. Each entry gets its own commit with its own regression test, and the `B-nn` marker
convention each entry gets its own commit with its own regression test, and the `B-nn` goes in a comment next to the fix. The full history of every B-nn is in
marker goes in a comment next to the fix. [docs/storico-bug.md](docs/storico-bug.md); the owner of this one in the plan is roadmap step C6.
# 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.
## Medium ## Medium
### B-93 — Deploys and rollbacks ### B-93 — Deploys and rollbacks
A deploy with an open SSE stream never shuts down gracefully (uvicorn waits, Docker On the Django stack (`docker-compose.yml`):
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`.
Fix: close SSE streams on shutdown, `stop_grace_period: 30s`, await task - every image is tagged `plm-lottery-web:local`, so there is no per-release tag and an older image
cancellation; tag images per release; `SITE_ADDRESS` in `.env` with `${SITE_ADDRESS:?}`; cannot be put back;
documented pre-deploy backup and downgrade procedure. - 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).
-93
View File
@@ -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/<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 -1
View File
@@ -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) ## 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*. implementata, quelli che sostituisce passano a *Sostituita da*.
| ADR | Decisione | | ADR | Decisione |
+1 -1
View File
@@ -1,6 +1,6 @@
# Sito, web app e console operativa # 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) (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), (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). [ADR-60](adr/ADR-60-pilota-solo-italiano.md) (lingua).
+26 -2
View File
@@ -1,9 +1,9 @@
# Roadmap — dal TODO al merge su main # 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 `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). [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 ## 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/`. - [ ] **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. - [ ] **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. - [ ] **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/`. - [ ] **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 ## 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 | | 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 | | 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 | | 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`.