A2: lottery models and database constraints (WEB-04, ADR-10, ADR-15, ADR-22, DAT-76..79, AUD-47)

LotteryConfig (single row, parameters and the three pause switches), Round
(single active round, own rules, split within the pool), Participation (one
bet per player and round, unique draw position), Movement (signed ledger,
idempotency key per player), ChainTransaction and an append-only AuditEntry
enforced by the model and by SQLite triggers. Every foreign key is PROTECT.
One test per constraint, each checked to hit the intended constraint.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 12:13:10 +01:00
1 parent fc23a75c9b
commit 0eba7bcfe6
12 files changed
+1139 -4

No files matched your search

+13
View File
@@ -685,3 +685,16 @@ nome tra parentesi quadre nel log è il modulo (`app.rounds.scheduler`, ecc.).
| ERROR | `app.tx.reconcile` | `round N payout tx … vanished — round needs operator attention` | Pagamento abbandonato; il nuovo tentativo automatico parte da solo |
| ERROR | `app.auth.security` | `stored password hash is unparseable …` | Hash di password corrotto nel database: quell'utente non può accedere |
| ERROR (con traccia) | `app.main` | `Unhandled error on …` | Errore 500 su una richiesta ([AUD-35]) |
## Registro di audit del sito Django
- **[AUD-47]** **Registro in sola aggiunta, scritto da un solo punto.** `AuditEntry` registra data, attore
(l'utente, e il suo nome di allora, oppure `system`), azione, motivo, esito (`ok`, `denied`, `error`),
oggetto e dati. Si scrive solo con `apps/lottery/audit.py:record`, **nella stessa transazione** del
cambiamento che registra ([ADR-53](adr/ADR-53-registro-audit-solo-aggiunta-stessa-transazione.md)): se il cambiamento
si annulla, si annulla anche la riga. Il modello rifiuta modifiche e cancellazioni (`save` su riga esistente,
`delete`, `QuerySet.update`/`delete`) e **il database le rifiuta a sua volta** con trigger SQLite
(`BEFORE UPDATE`/`BEFORE DELETE`), quindi nemmeno un `UPDATE` SQL diretto riscrive la storia.
*Stato:* implementato (A2) ·
*Codice:* `apps/lottery/audit.py:record`, `apps/lottery/models.py:AuditEntry`, `apps/lottery/migrations/0002_audit_append_only_triggers.py` ·
*Test:* `tests/django/test_models.py::test_an_audit_row_cannot_be_changed_with_raw_sql_either`, `test_the_audit_is_written_in_the_same_transaction_as_the_change`
+38
View File
@@ -1487,3 +1487,41 @@ scrive la stringa vuota).
- **Portabilità.** I pragma sono limitati al dialetto `sqlite` e l'indice del
round attivo è dichiarato anche per PostgreSQL. Un `DATABASE_URL` PostgreSQL
non è però mai stato provato, e il database supportato resta SQLite.
## Modello Django (migrazione in corso)
Lo schema del sito Django (`apps/lottery/models.py`, `apps/accounts/models.py`) sostituisce quello
SQLAlchemy descritto sopra (roadmap A2–D1); fino ad allora il resto del documento è lo stato storico.
Le regole che devono valere comunque sono **vincoli del database**, non convenzioni ([ARC-72]).
Le tabelle di catena (UTXO, versioni delle transazioni, depositi, indici HD) arrivano con la Fase B (B4).
- **[DAT-76]** **Il denaro non si cancella.** Ogni chiave esterna delle tabelle `lottery_*` verso utenti, round,
partecipazioni e transazioni è `PROTECT`: un utente, un round o una transazione con righe collegate non
si elimina. Ogni importo è un intero in unità minime ([DAT-01]) e ogni timestamp è in UTC con fuso ([DAT-02]).
*Stato:* implementato (A2) · *Codice:* `apps/lottery/models.py` · *Test:* `tests/django/test_models.py::test_rows_that_carry_money_cannot_be_deleted_with_their_owner`
- **[DAT-77]** **Parametri e pause: `LotteryConfig`.** Una sola riga (`id = 1`, vincolo) con quota (10 PLM),
durata (600 s), pausa fra round (30 s), conferme del blocco di estrazione (1–20, default 3), tetto del
montepremi (0 = nessuno) e i tre interruttori di [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md):
`pause_after_round`, `new_bets_suspended`, `withdrawals_suspended`. Valori non positivi o fuori intervallo
sono rifiutati dal database. I parametri si **copiano su `Round` all'apertura** ([DAT-61]); la copia la fa il
servizio (A4), le colonne del round sono già proprie.
*Stato:* tabella implementata (A2), copia all'apertura da implementare (A4) ·
*Codice:* `apps/lottery/models.py:LotteryConfig` · *Test:* `tests/django/test_models.py::test_config_is_a_single_row`, `test_a_round_keeps_its_own_rules`
- **[DAT-78]** **Round, partecipazioni, movimenti, transazioni.**
- `Round`: stati `open`, `closing`, `drawing`, `paying_out`, `closed`; **al più un round attivo**
(indice unico parziale `lottery_round_single_active`, [ADR-22](adr/ADR-22-piu-round-attivo-come-invariante-database.md));
un round chiuso ha `closed_at`; la ripartizione non supera il montepremi (`vincitore + commissioni ≤ montepremi`).
- `Participation`: una sola scommessa per giocatore e round ([ADR-15](adr/ADR-15-biglietto-prezzo-fisso-scommessa-utente-round.md));
`draw_position` unica nel round e solo per partecipanti `confirmed` ([DAT-66]); `confirmed` richiede `confirmed_at`.
- `Movement`: riga del libro mastro del giocatore; **il segno segue il tipo** (`deposit`, `win`, `refund` positivi;
`bet`, `withdrawal` negativi; mai zero); `bet`, `win`, `refund` appartengono a un round; **`(user, request_id)` è unico**
quando la chiave c'è ([WEB-23]). Il saldo si **deriva** dai movimenti, non si memorizza accanto.
- `ChainTransaction`: stati `building`, `pending`, `confirmed`, `failed`; `current_txid` unico se presente; un
fallimento ha sempre data e motivo ([ADR-51](adr/ADR-51-dubbio-liberano-mai-fondi.md)); scommesse e prelievi hanno un
giocatore, i pagamenti un round.
*Stato:* implementato (A2) · *Codice:* `apps/lottery/models.py` ·
*Test:* `tests/django/test_models.py` (un caso per ogni vincolo)
- **[DAT-79]** **`accounts.User`.** Modello utente personalizzato, unico per giocatori e staff (lo staff è un ruolo,
[ADR-56](adr/ADR-56-staff-account-individuali-permessi-mfa-dopo-pilota.md)); username unico senza distinzione fra
maiuscole ([DAT-06]), memorizzato come digitato.
*Stato:* implementato (A1) · *Codice:* `apps/accounts/models.py` · *Test:* `tests/django/test_scaffold.py::test_usernames_are_unique_ignoring_case`
+2
View File
@@ -37,6 +37,8 @@ backend FastAPI (vedi [architettura.md](architettura.md)).
- **[WEB-04]** Importi e saldi si rappresentano in unità minime intere
([ADR-35](adr/ADR-35-aritmetica-satoshi-interi.md)); i parametri economici e
temporali del round sono fissati alla sua apertura ([ADR-10](adr/ADR-10-parametri-round-fotografati-all-apertura.md)).
*Stato:* colonne e vincoli implementati (A2, [DAT-76]…[DAT-78]); la copia all'apertura con A4 ·
*Test:* `tests/django/test_models.py::test_amounts_are_integers_only`
- **[WEB-05]** I dati che cambiano (stato del round, saldo, esito) si
aggiornano con richieste periodiche mirate e si recuperano al rientro nella
pagina; ricaricare non perde lo stato salvato.