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

81 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Roadmap — dal TODO al merge su main
Piano di lavoro **commit per commit** per completare [TODO.md](TODO.md) sul branch
`django-migration` e arrivare al merge su `main`. Le scelte sono negli ADR
[54–60](docs/adr/README.md) e i requisiti in [docs/sito-e-app.md](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](docs/sito-e-app.md)).
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.
- [x] **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 `/`.
- [x] **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.
- [x] **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 |