Files
plm-lottery/roadmap.md
T

14 KiB
Raw Blame History

Roadmap — dal TODO al merge su main

Piano di lavoro commit per commit per completare il brief iniziale (la vecchia versione di TODO.md, commit 6441733) 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. Le cose da fare a mano o da decidere stanno in fondo, nella sezione «Da fare a mano»: è l'unico elenco di caselle del progetto.

Regole per ogni commit

Un commit è «fatto» solo se tutte queste condizioni sono vere:

  1. 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.
  2. Test verdi. python -m pytest passa per intero: i test già esistenti non si rompono, quelli nuovi coprono il requisito.
  3. Grafo aggiornato. graphify update . eseguito a fine commit.
  4. Documentazione allineata. Indici (docs/README.md, docs/adr/README.md), limiti-noti.md, CLAUDE.md e guide toccati dal cambiamento sono aggiornati.
  5. Navigabile in locale. Dopo ogni commit della Fase A in poi, docker compose up espone il sito su http://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/, app accounts, lottery, web, ops), modello utente personalizzato prima delle migrazioni, impostazioni da ambiente (SITE_ADDRESS, ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS), SQLite WAL con transaction_mode=IMMEDIATE, servizi web e worker nel compose dietro Caddy. Requisiti: WEB-01, WEB-07, ARC. Test: manage.py check, avvio e risposta 200 su /.
  • 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 in docs/); guida di avvio in locale in docs/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 per mainnet, 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. Il nodo (palladiumcore in -regtest) e Fulcrum sono quelli della cartella plm-regtest accanto al repository (docker compose up -d lì): non si duplicano nel compose del sito, ci si aggancia. plm_engine/regtest.py (client RPC con rifiuto di toccare una catena diversa da regtest), scripts/regtest.py (status, mine, fund) e le fixture di tests/integration/, che si saltano se il nodo o Fulcrum non rispondono. Test: tests/integration/test_regtest_smoke.py (blocco minato, indirizzi e genesis del profilo, tip di Fulcrum, fondi visti via Electrum).
  • 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. Eredità di B5 e B7: finestra degli ultimi header con rilevamento delle riorganizzazioni e pausa su quelle profonde (ELC-22…24), monete già accreditate che spariscono, spese altrove o reintegrate (DEP-06…08) e la seconda prova di abbandono di TX-17 (ingresso speso in un blocco da un'altra transazione). Requisiti: ARC-70…72, ADR-55.
  • B11 · Prova guidata del round su regtest. Script scripts/ che, su un database nuovo, crea giocatori con fondi, li fa puntare, fa scadere il round e mina i blocchi su regtest (B3) invece di aspettare il tempo; controlla chiusura, estrazione, pagamento e nuovo round, la conservazione dei fondi (vincita 70% più commissione 30% uguale al montepremi), l'ordine dell'audit e che la pagina pubblica /risultati/<id>/ ricalcoli il vincitore senza nomi utente. Casi: quattro giocatori, un solo giocatore, puntata rifiutata, riavvio del worker durante l'estrazione. Requisiti: RND, WEB-12, WEB-13. Test: lo script esce con errore se un controllo fallisce; la prova fatta a mano con la catena simulata (4 giocatori, 40 PLM, 28 al vincitore, 12 alla piattaforma) è il riferimento.

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; LIM del pilota chiuso.
  • C6 · Deploy e rollback (B-93). Immagini con tag per rilascio, stop_grace_period e arresto pulito del worker, SITE_ADDRESS obbligatorio in .env, procedura documentata di backup prima del deploy e di downgrade in docs/operativita.md. Test: il compose rifiuta di partire senza SITE_ADDRESS; un deploy con il worker a metà di un passo non lascia stato incoerente.
  • 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/ARC obsoleti 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 up da zero e percorso completo in localhost, merge.

Criteri per il merge su main

Si può fare il merge quando: A1–A10, B1–B11, 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

Da fare a mano

Cose che il codice non può fare da solo. I difetti trovati vanno in BUGS.md, non qui.

Ora (chiusura della Fase A)

  • Avviare da zero: cp .env.example .env, impostare DJANGO_SECRET_KEY, docker compose up -d --build, aprire https://localhost (setup.md).
  • Eseguire la checklist di verifica su telefono e su desktop; spuntare ogni voce lì e aprire un difetto in BUGS.md per ogni voce che non passa.
  • Creare un account staff (createsuperuser), provare /ops/, i tre comandi di pausa e /admin/ (segnalazioni, utenti).
  • Creare un secondo account staff non superutente con i soli permessi view_console e suspend_new_bets e verificare che gli altri due comandi siano negati.
  • Rileggere i commit di django-migration (A1–A10) prima di andare avanti; decidere se pubblicare il branch.

Decisioni da prendere

  • Dove vanno i difetti nuovi quando BUGS.md sparirà (D1/D2): una sezione «aperti» in docs/storico-bug.md o un file nuovo.
  • Quali server Electrum usare per la Fase B (almeno 2 per il quorum) e chi li gestisce.
  • Chi sono gli operatori della Fase C e chi tiene il backup della chiave di cifratura dei seed.

Fuori dal codice (Fase C)

  • Procurarsi PLM di prova e un indirizzo per la prova controllata con importi ridotti (C2).
  • Scegliere dominio e hosting per la messa online; impostare SITE_ADDRESS in .env.