10 KiB
Roadmap — dal TODO al merge su main
Piano di lavoro commit per commit per completare TODO.md sul branch
django-migration e arrivare al merge su main. Le scelte sono negli ADR
54–60 e i requisiti in docs/sito-e-app.md.
Il file è scritto in italiano come il TODO.
Regole per ogni commit
Un commit è «fatto» solo se tutte queste condizioni sono vere:
- Docs-first. Spec (requisiti
PREFISSO-NN) e, se serve, ADR sono nello stesso commit del codice; il messaggio e la docstring dei test citano gli ID. - Test verdi.
python -m pytestpassa per intero: i test già esistenti non si rompono, quelli nuovi coprono il requisito. - Grafo aggiornato.
graphify update .eseguito a fine commit. - Documentazione allineata. Indici (
docs/README.md,docs/adr/README.md),limiti-noti.md,CLAUDE.mde guide toccati dal cambiamento sono aggiornati. - Navigabile in locale. Dopo ogni commit della Fase A in poi,
docker compose upespone il sito suhttp://localhost(WEB-07).
Convenzioni: il vecchio backend FastAPI e i suoi test restano nel repo, fuori dal compose, fino al commit D1; da lì in poi si rimuovono insieme. Il lavoro prosegue in un solo branch, senza convivenza di servizi.
Fase A — Fondamenta e primo round simulato
Uscita: un giocatore completa il round dimostrativo in localhost, l'operatore lo segue e lo mette in pausa, un visitatore verifica l'esito.
- A1 · Scheletro Django. Progetto Django 5.2 (
config/, appaccounts,lottery,web,ops), modello utente personalizzato prima delle migrazioni, impostazioni da ambiente (SITE_ADDRESS,ALLOWED_HOSTS,CSRF_TRUSTED_ORIGINS), SQLite WAL contransaction_mode=IMMEDIATE, serviziwebeworkernel compose dietro Caddy. Requisiti: WEB-01, WEB-07, ARC. Test:manage.py check, avvio e risposta200su/. - A2 · Modelli e vincoli. Account, Round (parametri fotografati all'apertura), Partecipazione, Movimento, Transazione, Audit (solo aggiunta). Importi interi in unità minime; un solo round attivo e una sola puntata per utente e round come vincoli del database. Requisiti: WEB-04, DAT. Test: violazione di ogni vincolo.
- A3 · Ledger simulato. Interfaccia dei servizi (deposito, puntata, pagamento) con implementazione simulata e chiave di idempotenza: un doppio invio produce una sola operazione. Requisiti: WEB-23, ADR-59. Test: doppio invio, saldo insufficiente, importi al limite.
- A4 · Ciclo del round e worker. Apertura, chiusura, estrazione e pagamento 70/30 nel worker (
manage.py run_worker), con l'estrazione commit-reveal dello stesso algoritmo del motore. Requisiti: RND esistenti riletti sul modello nuovo. Test: round completo deterministico, ripresa dopo riavvio del worker. - A5 · Autenticazione e base grafica.
/registrati/,/accedi/,/app/profilo/(password, logout), CSRF, cookie di sessione, ritorno alla destinazione interna (next) solo se interna, template base e CSS responsivo. Requisiti: WEB-02, WEB-06. Test: redirect aperto rifiutato, cookie, throttling dei tentativi. - A6 · Home pubblica.
/con quota, montepremi confermato, chiusura (ora server) e i sei stati, «Partecipa», aggiornamento a polling. Requisiti: WEB-05, WEB-10, WEB-11. Test: un test per stato, polling dell'endpoint. - A7 · Area giocatore.
/app/(puntata con conferma esplicita),/app/portafoglio/(saldo spendibile e in conferma, deposito simulato solo fuori da mainnet),/app/movimenti/. Requisiti: WEB-03, WEB-20, WEB-21, WEB-22. Test: isolamento tra utenti (404 su dati altrui), stato salvato dopo ricarica. - A8 · Pagine pubbliche di risultato e guida.
/risultati/,/risultati/<id>/con prova riproducibile senza dati dell'account,/guida/,/regole/con gli stessi termini dell'app. Requisiti: WEB-12, WEB-13. Test: la prova ricalcola il vincitore; nessuno username nelle pagine. - A9 · Console operativa e audit.
/ops/con stato del round, scadenza, salute del worker, operazioni in ritardo; i tre comandi di pausa con conferma e motivazione;/admin/per utenti e segnalazioni con record di gioco in sola lettura; segnalazioni: modello, sezione nel profilo del giocatore (invio e stato delle proprie) e gestione da/admin/; ogni comando registrato nell'audit. Requisiti: WEB-30…WEB-33, WEB-40…WEB-44, WEB-55. Test: giocatore e staff senza permesso non eseguono i comandi; la pausa si riflette sul sito. - A10 · Percorso completo e chiusura di fase. Test end-to-end
home → login → deposito → puntata → estrazione → risultato pubblico; verifica su telefono e desktop, tastiera, stati di errore, attesa e conferma (checklist indocs/); guida di avvio in locale indocs/setup.md. Requisiti: WEB-06.
Fase B — Integrazione del motore PLM
Uscita: flusso completo su regtest; un riavvio durante il broadcast, due richieste concorrenti e una riorganizzazione simulata lasciano dati e fondi riconciliabili.
- B1 · Pacchetto
plm_engine(le primitive dell'estrazione sono già state spostate in A4). Spostamento dei moduli senza database (derivazione HD,psbt_builder, client Electrum,merkle,draw) e dei loro test, senza cambiare il comportamento. Requisiti: ADR-59. Test: i test esistenti dei moduli passano invariati. - B2 · Profilo di rete.
PLM_NETWORK=regtest|mainnet(hrp, prefissi, genesis, powLimit), conferma esplicita permainnet, validazione degli indirizzi con l'hrp del profilo. Requisiti: ADR-58, ELC-30. Test: indirizzi e genesis per ciascun profilo. - B3 · Ambiente regtest e fixture. Compose con nodo e Fulcrum regtest (profilo
regtest), script che genera blocchi e fondi, fixture di integrazione che si salta se il regtest non c'è. Test: smoke di connessione e generazione di un blocco. - B4 · Modelli di catena. UTXO, transazioni con tutte le versioni TXID, depositi, assegnazione dell'indice HD; la chiave di firma è accessibile solo al processo worker. Requisiti: DAT, TX. Test: vincoli, derivazione identica a parità di input.
- B5 · Listener e depositi reali. Listener Electrum sull'ORM con rotazione, header validati, quorum e soglie di conferma al posto del deposito simulato. Requisiti: DEP, ELC. Test: unit con server finto + integrazione su regtest.
- B6 · Prenotazione UTXO e puntata reale. Prenotazione atomica degli UTXO nel database, identificativo idempotente, «salva operazione e transazione firmata prima del broadcast», verdetto del broadcast (accettato, rifiutato, incerto). Requisiti: BET, TX-26. Test: due richieste concorrenti non spendono gli stessi input; timeout ambiguo riconciliato.
- B7 · Conferme, riconciliazione e RBF. Poller, riconciliatore e bumper sull'ORM con tutte le versioni TXID e adozione della versione confermata. Requisiti: TX. Test: conferma di una versione RBF precedente, ripresa dopo riavvio.
- B8 · Estrazione e pagamento reali. Commit-reveal con blocco a quorum, verifica del montepremi, pagamento 70/30 con riserva per l'RBF, pausa automatica sui casi bloccanti. Requisiti: RND. Test: round completo su regtest, riorganizzazione simulata.
- B9 · Prelievi e storico. Prelievo con indirizzo, importo, commissione e netto previsti; storico con stato dell'operazione e TXID corrente con link all'explorer. Requisiti: WDR, WEB-24. Test: prelievo su regtest, sospensione dei prelievi.
- B10 · Robustezza e chiusura di fase. Test di riavvio durante il broadcast, richieste concorrenti web/worker, riorganizzazione; sostituzione definitiva dei blocchi in memoria. Requisiti: ARC-70…72, ADR-55.
Fase C — Verifiche prima dell'uso pubblico
Non blocca il merge su main (la rete mainnet resta bloccata dall'ADR-58) ma blocca ogni accettazione di fondi reali.
- C1 · Integrazione Electrum automatizzata. Indisponibilità, riconnessione, broadcast ambiguo, versione RBF precedente confermata, ripresa dopo riavvio, su regtest.
- 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.
- 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;
LIMdel pilota chiuso. - 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
- D1 · Rimozione del vecchio backend. FastAPI, SQLAlchemy, Alembic, SPA statiche e relativi test; gli ADR 13, 36, 40, 46, 48, 49, 50 passano a «Sostituita da»; i requisiti
API/ARCobsoleti diventano~~ID~~ Rimosso: …. - D2 · Documentazione e grafo finali.
CLAUDE.md,README.md, guide (setup,running-the-server,guida-utente,guida-admin),limiti-noti.md(inclusi i limiti del pilota: SQLite, solo italiano, senza MFA),BUGS.md;graphify update .. - D3 · Merge su main. Rebase su
main, suite completa verde,docker compose upda zero e percorso completo inlocalhost, merge.
Criteri per il merge su main
Si può fare il merge quando: A1–A10, B1–B10, C1, C3, D1 e D2 sono completati; la suite è verde; il sito parte da zero su localhost; la documentazione e il grafo sono allineati; e nulla si può avviare su mainnet senza la conferma esplicita dell'ADR-58.
Restano fuori dal merge ma dentro l'uscita verso il pubblico: C2 (prova con fondi reali), C4 (MFA) e C5 (legale).
Rischi principali
| Rischio | Dove | Mitigazione |
|---|---|---|
| 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 |
| Prelievo e RBF mai provati con rete reale | B9, C2 | regtest in B, prova controllata in C2 |