Files
plm-lottery/roadmap.md
T

106 lines
14 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 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/<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.
- [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.
- [x] **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.
- [x] **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.
- [x] **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).
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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](BUGS.md), non qui.
**Ora (chiusura della Fase A)**
- [x] 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.
- [x] Creare un account staff (`createsuperuser`), provare `/ops/`, i tre comandi di pausa e `/admin/` (segnalazioni, utenti).
- [x] 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`.