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,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
|
||||
|
||||
|
||||
Reference in new issue
Block a user