Files
plm-lottery/TODO.md
T
davideandClaude Sonnet 5.5 6441733160 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>
2026-11-16 11:46:05 +01:00

11 KiB
Raw Blame History

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

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 · Autenticazione · Django Admin · Transazioni ORM

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.