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>
This commit is contained in:
1 parent
9b8a331bba
commit
6441733160
11 files changed
+489
-1
No files matched your search
@@ -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/<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.
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
+17
-1
@@ -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
|
||||
|
||||
|
||||
@@ -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/<round_id>/` | 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.
|
||||
Reference in new issue
Block a user