# 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](docs/adr/README.md) e i requisiti in [docs/sito-e-app.md](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](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. - [x] **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. - [x] **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. - [x] **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. - [x] **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. - [x] **A8 · Pagine pubbliche di risultato e guida.** `/risultati/`, `/risultati//` 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. - [x] **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. - [x] **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.** 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. - [ ] **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–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 | ## Da fare a mano Cose che il codice non può fare da solo. I difetti trovati vanno in [BUGS.md](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](docs/setup.md)). - [ ] Eseguire la [checklist di verifica](docs/checklist-verifica-sito.md) 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`.