93 lines
11 KiB
Markdown
93 lines
11 KiB
Markdown
# 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.
|