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>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 13:23:29 +01:00
1 parent 0eba7bcfe6
commit eded058dbb
12 files changed
+924 -4

No files matched your search

+25
View File
@@ -990,3 +990,28 @@ non è rimosso le sezioni precedenti descrivono lo stato storico. Scelte: [ADR-5
solo `DJANGO_DEBUG=true` (sviluppo senza Docker) ne genera uno non sicuro.
*Stato:* implementato (A1) ·
*Codice:* `config/settings.py` · *Test:* `tests/django/test_scaffold.py::test_refuses_to_start_without_a_secret`
- **[ARC-75]** **Il denaro si muove attraverso un'interfaccia sola.** Viste e worker usano `Ledger`
(`deposit`, `place_bet`, `confirm_bet`, `reject_bet`, `exclude_bet`, `pay_winner`, `confirm_payout`);
`LEDGER_BACKEND` sceglie l'implementazione. Nella Fase A è `SimulatedLedger` (fondi che esistono solo nel
database, la conferma è una chiamata); nella Fase B un'implementazione di catena sta dietro gli stessi metodi
senza toccare viste né modelli ([ADR-59](adr/ADR-59-motore-plm-pacchetto-senza-framework-ledger-simulato.md)).
Il ledger simulato **non parte su `mainnet`** (`PLM_NETWORK=mainnet` con `LEDGER_BACKEND=simulated` è un errore
di configurazione), e `PLM_NETWORK` e `LEDGER_BACKEND` sconosciuti sono rifiutati all'avvio.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py`, `config/settings.py` ·
*Test:* `tests/django/test_ledger.py::test_the_simulated_ledger_cannot_run_on_mainnet`, `test_get_ledger_follows_the_configuration`
- **[ARC-76]** **Idempotenza.** Ogni richiesta di deposito o di puntata porta una chiave (`request_id`):
la stessa chiave dello stesso giocatore è la stessa operazione. Il secondo invio restituisce l'esito del primo
(`replayed`), non addebita né registra nulla e non scrive una seconda riga di audit; una chiave riusata per
un'altra operazione (importo, tipo o round diversi) è l'errore `idempotency_conflict`. La puntata richiede la
chiave (`missing_request_id`). Il vincolo `(user, request_id)` di [DAT-78] è la rete di sicurezza.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py:SimulatedLedger._replay` ·
*Test:* `tests/django/test_ledger.py::test_the_same_bet_request_is_one_bet`, `test_the_same_deposit_request_is_one_deposit`, `test_concurrent_requests_with_the_same_key_make_one_bet`
- **[ARC-77]** **Un'operazione è una transazione.** Controlli e scritture di ogni operazione del ledger stanno in una
sola transazione che prende subito il blocco di scrittura ([ARC-70]), così nessun'altra richiesta si inserisce fra
la verifica del saldo e l'addebito; la riga di audit si scrive nella stessa transazione ([AUD-47]). Un'operazione
rifiutata non lascia nulla. Una puntata concorrente dello stesso giocatore nello stesso round ne produce una sola.
*Stato:* implementato (A3) ·
*Codice:* `apps/lottery/ledger.py` ·
*Test:* `tests/django/test_ledger.py::test_a_failed_operation_leaves_nothing_behind`, `test_concurrent_requests_with_different_keys_make_one_bet` (sei processi su un solo file SQLite)