Files
plm-lottery/roadmap.md
T
davideandClaude Sonnet 5.5 eded058dbb A3: simulated ledger with idempotency (WEB-22, WEB-23, ADR-59, ARC-75..77, DAT-80)
One Ledger interface (deposit, bet, confirm, reject, exclude, payout) with a
simulated implementation chosen by LEDGER_BACKEND, refused on mainnet. Every
operation is a single write-locked transaction with its audit row; the same
request key is the same operation, a key reused for something else is an
error. The server validates round, deadline, the round's own quota, limits and
funds. The balance is derived from the ledger. Tests include six processes
racing on one SQLite file; the idempotency tests were checked to fail when
the replay is removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 13:23:29 +01:00

10 KiB
Raw Blame History

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:

  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; ogni comando registrato nell'audit. Requisiti: WEB-30…WEB-33, WEB-40…WEB-44. 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. 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. 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; LIM del 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/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–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