The two Mermaid diagrams under flowchart/ described the intended flow but had drifted from the code and carried no link back to it. docs/ now holds the specification instead: 15 Italian documents (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history) with 472 numbered requirements, each pointing at the function that implements it and the test that covers it. docs/processo-di-modifica.md defines the ID convention and the spec -> code -> test change workflow, and CLAUDE.md now names docs/ as authoritative. Writing the spec from the code also corrected stale claims in CLAUDE.md (B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control scope, the error contract's bare-string exceptions) and in the operator guides (payouts do retry, only `drawing` fails to resume, rounds do not open without fee_address). The B-70 doc test now pins the prose in docs/scommesse-e-prelievi.md instead of the deleted diagram. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
345 lines
20 KiB
Markdown
345 lines
20 KiB
Markdown
# Ciclo di vita del round
|
||
|
||
Fase 4 del [funzionamento generale](come-funziona.md): come un round si apre,
|
||
si chiude, estrae un vincitore e lo paga. Tutto è guidato da `RoundScheduler`,
|
||
che si risveglia ogni 5 secondi.
|
||
|
||
I requisiti usano il prefisso `RND`, secondo la convenzione di
|
||
[processo-di-modifica.md](processo-di-modifica.md). Le colonne della tabella
|
||
`rounds` sono descritte in [modello-dati.md](modello-dati.md), gli eventi di
|
||
audit in [audit-log.md](audit-log.md), le attività in background in
|
||
[architettura.md](architettura.md).
|
||
|
||
- **[RND-01]** Lo scheduler esegue un passo ogni 5 secondi
|
||
(`_TICK_INTERVAL_SECONDS`). Un passo non fa nulla se non c'è connessione a
|
||
Electrum: senza rete nessun round si apre, si chiude o si paga. Un errore in
|
||
un passo viene registrato nei log e non ferma i passi successivi.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler.run`, `app/rounds/scheduler.py:RoundScheduler._tick` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
|
||
## Gli stati
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> open: nessun round attivo,<br/>pausa tra i round trascorsa,<br/>lotteria non in manutenzione,<br/>indirizzo commissioni impostato
|
||
open --> closing: scade il tempo<br/>(al primo passo dopo la scadenza)
|
||
closing --> closing: scommesse ancora in volo
|
||
closing --> closed: nessun partecipante confermato
|
||
closing --> drawing: tutte le scommesse confermate
|
||
drawing --> drawing: blocco non corroborato,<br/>si attende il successivo
|
||
drawing --> paying_out: nuovo blocco corroborato,<br/>vincitore scelto
|
||
paying_out --> paying_out: pagamento fallito o abbandonato,<br/>nuovo tentativo dopo 60s
|
||
paying_out --> closed: pagamento confermato
|
||
closed --> [*]
|
||
```
|
||
|
||
| Stato | Significato |
|
||
|---|---|
|
||
| `open` | Accetta scommesse fino alla scadenza |
|
||
| `closing` | Scadenza passata: nessuna nuova scommessa, si aspettano quelle già inviate |
|
||
| `drawing` | Partecipanti fissati, si attende il blocco che sceglie il vincitore |
|
||
| `paying_out` | Vincitore noto, pagamento in costruzione, inviato o in attesa di conferma |
|
||
| `closed` | Concluso (con o senza vincitore) |
|
||
|
||
- **[RND-02]** Gli stati sono esattamente quelli della tabella e le sole
|
||
transizioni sono quelle del diagramma; `closed` è definitivo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw`, `app/rounds/confirmation.py:_on_payout_confirmed` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_confirmation.py`
|
||
- **[RND-03]** **Al massimo un round attivo alla volta** (cioè in uno stato
|
||
diverso da `closed`). Non è una convenzione ma un vincolo del database: un
|
||
indice univoco (`ix_rounds_single_active`) fa fallire un secondo inserimento
|
||
concorrente, e il codice di apertura in quel caso adotta il round già creato
|
||
(fino a 3 tentativi, `_OPEN_ROUND_ATTEMPTS`). Se mai risultassero due round
|
||
attivi, si usa il più recente e lo si segnala nei log come violazione.
|
||
*Codice:* `app/db/models.py:Round`, `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:get_active_round` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`
|
||
|
||
## 0 · Apertura
|
||
|
||
L'apertura viene tentata a ogni passo dello scheduler e anche da ogni
|
||
richiesta di scommessa (vedi
|
||
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata)).
|
||
|
||
- **[RND-04]** Un nuovo round si apre solo quando **tutte** queste condizioni
|
||
sono vere:
|
||
- nessun round è attivo (il precedente è `closed`);
|
||
- è trascorsa la **pausa tra i round** del round chiuso più recente, contata
|
||
dal suo `closed_at`: per un round pagato è il momento della conferma del
|
||
pagamento, per un round chiuso senza partecipanti è il momento della
|
||
chiusura. Serve a lasciare ai giocatori il tempo di vedere il risultato;
|
||
- la lotteria **non è in manutenzione** (`POST /admin/pause`);
|
||
- l'**indirizzo delle commissioni** (`fee_address`) è impostato (un valore
|
||
di soli spazi conta come vuoto). Senza, il pagamento non si potrebbe
|
||
costruire, quindi il round non viene nemmeno aperto invece di bloccarsi
|
||
più avanti con i soldi già nel montepremi.
|
||
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:rounds_can_open` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`
|
||
- **[RND-05]** All'apertura il round **fotografa** la durata
|
||
(`round_duration_seconds`, 600s predefiniti) e la pausa
|
||
(`round_cooldown_seconds`, 30s predefiniti) correnti. Scadenza del round e
|
||
pausa successiva usano sempre i valori fotografati: una modifica da
|
||
`/admin` vale dal round successivo, mai per quello in corso.
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/rounds/service.py:round_deadline` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_scheduler.py`
|
||
- **[RND-06]** La pausa di manutenzione e l'indirizzo mancante bloccano solo
|
||
l'apertura del *prossimo* round: un round già in corso prosegue fino al
|
||
pagamento, anche se l'indirizzo viene cancellato nel frattempo.
|
||
`GET /rounds/current` espone i due casi separatamente (`lottery_paused`,
|
||
`lottery_configured`) perché `/` mostri avvisi diversi. Le procedure sono in
|
||
[guida-admin.md](guida-admin.md).
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`, `app/api/routes/rounds.py:current_round` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`, `tests/unit/test_rounds_route.py`
|
||
- **[RND-07]** L'apertura di un round invia una notifica SSE.
|
||
*Codice:* `app/rounds/service.py:open_new_round_if_needed`
|
||
|
||
## 1 · Round aperto
|
||
|
||
Il round accetta scommesse fino a `apertura + durata`. Le regole di
|
||
accettazione sono in
|
||
[scommesse-e-prelievi.md](scommesse-e-prelievi.md#quando-è-accettata).
|
||
|
||
- **[RND-08]** La scadenza (`closes_at`) è `opened_at` più la durata
|
||
fotografata all'apertura; è la stessa usata per rifiutare le scommesse e per
|
||
chiudere il round.
|
||
*Codice:* `app/rounds/service.py:round_deadline`, `app/rounds/service.py:round_accepts_bets` ·
|
||
*Test:* `tests/unit/test_rounds_service.py`
|
||
- **[RND-09]** `GET /rounds/current` pubblica il montepremi in due forme:
|
||
- `jackpot_sats` e `participant_count`: calcolati sulle sole scommesse
|
||
**confermate** — esattamente ciò che l'estrazione considererà e che il
|
||
pagamento potrà spendere. `jackpot_sats` è già il 70% del vincitore
|
||
(arrotondato per difetto) della somma degli importi netti, non l'intero
|
||
montepremi; resta un limite superiore, perché la commissione del pagamento
|
||
sarà dedotta da lì;
|
||
- `pending_jackpot_sats` e `pending_participant_count`: gli stessi valori
|
||
includendo le scommesse ancora in volo (`building`, `broadcast`), come
|
||
totali e non come differenze; `has_pending_bets` dice se differiscono.
|
||
|
||
*Codice:* `app/api/routes/rounds.py:current_round`, `app/rounds/service.py:winner_share` ·
|
||
*Test:* `tests/unit/test_rounds_route.py`
|
||
- **[RND-10]** `user_played` è vero solo se chi chiama è autenticato e ha una
|
||
scommessa nel round attivo; senza login la risposta non è personalizzata.
|
||
*Codice:* `app/api/routes/rounds.py:current_round` ·
|
||
*Test:* `tests/unit/test_rounds_route.py`
|
||
|
||
L'interfaccia mostra in grande i valori confermati e la differenza come
|
||
suffisso ambra "+N in attesa": chi ha appena scommesso vede subito la propria
|
||
giocata, ma il montepremi pubblicizzato non supera mai quello che verrà pagato.
|
||
|
||
## 2 · Chiusura
|
||
|
||
- **[RND-11]** Al primo passo dello scheduler dopo la scadenza (quindi entro
|
||
circa 5 secondi) il round passa a `closing`, qualunque cosa stia accadendo:
|
||
si annota `closed_at` e si invia una notifica SSE. Le scommesse sono però
|
||
rifiutate già dall'istante della scadenza ([BET-04](scommesse-e-prelievi.md#quando-è-accettata)).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-12]** Poi il round **attende che ogni scommessa già inviata sia
|
||
confermata** (il "semaforo giallo"): finché esiste un partecipante in stato
|
||
`building` o `broadcast` il round resta `closing` e il controllo si ripete
|
||
al passo successivo. Il controllo viene ripetuto anche nella stessa sessione
|
||
del database in cui si fissa l'elenco dei partecipanti, così una scommessa
|
||
salvata tra i due controlli non può restare esclusa. Una scommessa partita
|
||
un attimo prima della scadenza resta quindi valida e non va persa. Ciò che
|
||
impedisce all'attesa di durare per sempre è il riconciliatore, che prima o
|
||
poi abbandona una scommessa che non conferma mai
|
||
([TX-17](transazioni-e-riconciliazione.md#riconciliazione)).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-13]** Quando non resta nulla in volo e **nessun partecipante è
|
||
confermato**, il round passa a `closed` senza vincitore, si scrive
|
||
`round_closed` (con `participants: 0`) e si invia una notifica SSE.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-14]** Con **almeno un partecipante confermato**, si fissa l'elenco dei
|
||
partecipanti confermati, ordinato per momento di invio della scommessa, si
|
||
somma il montepremi dai loro importi netti, e il round passa a `drawing`
|
||
annotando `drawing_started_at`; si invia una notifica SSE. L'altezza della
|
||
catena nota in quell'istante diventa il riferimento dell'estrazione.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
|
||
## 3 · Estrazione
|
||
|
||
L'estrazione usa come fonte di casualità l'**hash di un blocco confermato
|
||
dopo la chiusura**, un valore che nessuno conosceva mentre le scommesse erano
|
||
aperte.
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
A["Altezza nota alla chiusura<br/>(se sconosciuta: la prima che si<br/>viene a sapere, draw_baseline_tip_unknown)"] --> B{"La punta della catena<br/>è più alta?<br/>(controllo ogni 5s)"}
|
||
B -- "No" --> B
|
||
B -- "Sì" --> C{"La maggioranza degli<br/>altri server conferma<br/>l'hash a quell'altezza?"}
|
||
C -- "No" --> D["Registrato in audit<br/>(draw_header_corroboration_failed),<br/>quell'altezza diventa il nuovo riferimento"] --> B
|
||
C -- "Sì" --> E["seme = hash come numero intero<br/>indice = seme mod numero partecipanti"]
|
||
E --> F["Vincitore = partecipante all'indice"]
|
||
```
|
||
|
||
- **[RND-15]** L'estrazione attende che la punta della catena superi
|
||
l'altezza di riferimento, controllando ogni 5 secondi; il blocco candidato è
|
||
la punta nota in quel momento (di norma il primo blocco dopo la chiusura).
|
||
Per tutta l'attesa lo scheduler resta dentro l'estrazione e non esegue
|
||
altri passi.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-16]** **Blocco corroborato**: l'header ricevuto dal server Electrum
|
||
attivo è l'unica fonte di casualità, quindi un server malevolo che lo
|
||
falsificasse sceglierebbe il vincitore. Per questo, prima di usarlo, lo si fa
|
||
confermare dagli altri server
|
||
([ELC-15](connessione-electrum.md#5-il-quorum)). Se la conferma manca, si
|
||
scrive `draw_header_corroboration_failed` (altezza e hash riportato), il
|
||
blocco non viene mai usato e si attende un blocco ulteriore.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/electrum/listener.py:ElectrumListener.corroborate_header` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-17]** **Algoritmo**: seme = hash del blocco letto come numero
|
||
esadecimale, indice = seme modulo numero dei partecipanti, vincitore = il
|
||
partecipante in quella posizione dell'elenco ordinato per momento di invio.
|
||
**Probabilità uguale per tutti**: ogni partecipante ha una e una sola
|
||
posizione nell'elenco, indipendentemente dall'importo.
|
||
*Codice:* `app/rounds/draw.py:draw_winner`, `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_draw.py`
|
||
- **[RND-18]** **Verificabile**: il round salva altezza e hash del blocco
|
||
(`draw_block_height`, `draw_block_hash`), il seme (`seed_int`), il
|
||
vincitore e il montepremi (`pool_amount_sats`), passa a `paying_out`,
|
||
scrive `winner_drawn` (indirizzo del vincitore, montepremi, altezza, hash,
|
||
numero di partecipanti) e invia una notifica SSE. Chiunque, con l'hash del
|
||
blocco e l'elenco dei partecipanti, può rifare il calcolo. Il primo
|
||
tentativo di pagamento parte subito dopo.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-19]** **Altezza iniziale sconosciuta**: se alla chiusura l'altezza
|
||
della catena non era nota (valore 0), non si parte da zero (qualunque blocco
|
||
già esistente sarebbe "successivo", e quindi prevedibile): si attende il
|
||
primo header, se ne adotta l'altezza come riferimento, si scrive
|
||
`draw_baseline_tip_unknown` e si aspetta un blocco strettamente successivo.
|
||
In condizioni normali non accade, perché la connessione è resa disponibile
|
||
solo con l'altezza già nota ([ELC-07](connessione-electrum.md#3-caduta-rilevata)).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._adopt_baseline_tip` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-20]** **Attesa lunga ma visibile**: l'attesa non ha un limite,
|
||
perché dipende davvero dall'arrivo di un blocco. Ogni 60 secondi se ne
|
||
registra l'avanzamento nei log; dopo 6 minuti (`_DRAW_STALL_THRESHOLD_SECONDS`
|
||
= 360s) viene scritto un evento `draw_stalled`, ripetuto ogni 6 minuti
|
||
finché l'attesa continua. Durante `drawing`, `GET /rounds/current` espone
|
||
`draw_waiting_since` (l'orario di inizio dell'attesa); negli altri stati il
|
||
campo è assente.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._wait_for_next_block`, `app/api/routes/rounds.py:current_round` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_rounds_route.py`
|
||
|
||
L'algoritmo è volutamente semplice ed è pensato per essere **sostituito**
|
||
(vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||
|
||
## 4 · Pagamento
|
||
|
||
Con il vincitore noto il round è in `paying_out` e si costruisce il
|
||
pagamento, firmato con la chiave del montepremi.
|
||
|
||
- **[RND-21]** **Ripartizione**: il vincitore riceve il 70% del montepremi
|
||
arrotondato per difetto, l'indirizzo delle commissioni il resto (30% più
|
||
l'eventuale resto dell'arrotondamento). La ripartizione è fissata nel
|
||
codice, non modificabile da `/admin`.
|
||
*Codice:* `app/rounds/service.py:winner_share`, `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
|
||
*Test:* `tests/unit/test_payout_builder.py`
|
||
- **[RND-22]** Il pagamento spende le monete **confermate** dell'indirizzo del
|
||
montepremi, lette dal server Electrum attivo ed escluse quelle già
|
||
impegnate da un altro pagamento non risolto ([RND-26]), scelte dalla più
|
||
grande fino a coprire il montepremi e al massimo 500
|
||
(`MAX_PAYOUT_TX_INPUTS`). Non abbastanza monete dà il motivo
|
||
`insufficient pool UTXOs`, troppe `too_many_inputs`.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/wallet/psbt_builder.py:build_payout_transaction` ·
|
||
*Test:* `tests/unit/test_scheduler.py`, `tests/unit/test_payout_builder.py`
|
||
- **[RND-23]** La transazione ha un'uscita verso l'indirizzo del vincitore, una
|
||
verso l'indirizzo delle commissioni e, se supera 294 sat, una di resto verso
|
||
il montepremi (un resto inferiore va alla commissione di rete). La
|
||
**commissione di rete** (stimata su tre uscite, a `fee_rate_sat_vb`) è
|
||
pagata dalla quota del vincitore, così il 30% resta intatto. Se la quota del
|
||
vincitore meno la commissione, o la quota delle commissioni, scende sotto
|
||
294 sat, il pagamento non si costruisce (`winner_share_below_network_fee`,
|
||
`commission_below_dust_limit`).
|
||
*Codice:* `app/wallet/psbt_builder.py:build_payout_transaction` ·
|
||
*Test:* `tests/unit/test_payout_builder.py`
|
||
- **[RND-24]** **Prima si scrive, poi si invia**: prima dell'invio il round
|
||
registra importo del vincitore (`winner_amount_sats`), commissioni
|
||
(`fee_amount_sats`) e txid (`payout_txid`), e si salva una transazione in
|
||
corso di tipo `payout` in stato `building`. Se l'invio riesce, la
|
||
transazione passa a `pending` e si scrive `payout_sent`. Se fallisce, la
|
||
riga resta `building` e si scrive `payout_failed`: sarà il riconciliatore a
|
||
constatare che la rete non la conosce, abbandonarla e liberare il round per
|
||
un nuovo tentativo ([TX-18](transazioni-e-riconciliazione.md#pagamenti-del-round-riprovare-senza-pagare-due-volte)).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-25]** Ogni tentativo che non arriva all'invio riuscito scrive un
|
||
evento `payout_failed` con il motivo: `electrum client not connected`,
|
||
`no fee_address configured`, `winner user not found`,
|
||
`insufficient pool UTXOs`, il codice dell'errore di costruzione
|
||
(`too_many_inputs`, `winner_share_below_network_fee`,
|
||
`commission_below_dust_limit`), `payout build failed` per ogni altro errore
|
||
di costruzione, `broadcast rejected`. A ogni passo lo scheduler riesamina un
|
||
round in `paying_out` e riprova **al massimo una volta ogni 60 secondi**
|
||
(`_PAYOUT_RETRY_INTERVAL_SECONDS`), misurati dall'ultimo `payout_failed` di
|
||
quel round; senza alcun `payout_failed` (ad esempio dopo un riavvio) riprova
|
||
subito.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._retry_payout_if_due`, `app/rounds/scheduler.py:RoundScheduler._log_payout_failure` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-26]** Due protezioni impediscono di pagare due volte: non si
|
||
costruisce un nuovo pagamento se per il round ne esiste già uno `building` o
|
||
`pending` (il tentativo termina senza fare nulla), e le monete del
|
||
montepremi impegnate da un qualunque pagamento non risolto, anche di un
|
||
round precedente, sono escluse dalla selezione.
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._trigger_payout`, `app/rounds/scheduler.py:_reserved_payout_outpoints` ·
|
||
*Test:* `tests/unit/test_scheduler.py`
|
||
- **[RND-27]** Se il pagamento non conferma in tempo si applica l'RBF, pagato
|
||
dal resto del montepremi ([TX-11](transazioni-e-riconciliazione.md#rbf-accelerare-una-transazione-lenta)).
|
||
*Codice:* `app/tx/broadcast.py:bump_fee`
|
||
- **[RND-28]** Quando il pagamento è confermato il round passa a `closed` e
|
||
`closed_at` viene riscritto con l'orario della conferma: da lì parte la
|
||
pausa prima del round successivo. Il vincitore si vede accreditare la
|
||
vincita come un normale deposito
|
||
([registrazione-e-depositi.md](registrazione-e-depositi.md#deposito)).
|
||
*Codice:* `app/rounds/confirmation.py:_on_payout_confirmed` ·
|
||
*Test:* `tests/unit/test_confirmation.py`
|
||
|
||
## Tempi reali
|
||
|
||
Tra lo scadere del timer e l'arrivo della vincita ci sono **tre conferme
|
||
distinte**, ognuna in un blocco diverso:
|
||
|
||
1. l'ultima scommessa in volo (può essere già avvenuta prima della scadenza);
|
||
2. il blocco dell'estrazione, necessariamente successivo al punto 1;
|
||
3. il pagamento, costruito solo dopo il punto 2.
|
||
|
||
Con blocchi da 120 secondi sono circa **2–4 minuti** nel caso migliore e
|
||
**4–6** nel peggiore, indipendentemente da `draw_animation_seconds`.
|
||
|
||
## Cosa vede il giocatore
|
||
|
||
Due livelli indipendenti:
|
||
|
||
- **[RND-29]** A **tutti** i visitatori, per l'intera durata di `closing`,
|
||
`drawing` e `paying_out`, un riquadro con la fase in corso (ad esempio
|
||
"Pagamento al vincitore in corso…").
|
||
*Codice:* `app/static/app.js:refreshRound`
|
||
- **[RND-30]** **In più**, solo a chi ha giocato quel round
|
||
(`user_played`), il riquadro personale "Hai vinto!" / "Non hai vinto". Il
|
||
risultato compare quando il vincitore è noto (quindi da `paying_out`), non
|
||
prima di `draw_animation_seconds` (20s predefiniti) dall'orario di chiusura
|
||
del server `closes_at` — così ricaricare la pagina non fa ripartire il conto
|
||
alla rovescia — e, per il vincitore, solo quando è noto l'importo vinto.
|
||
*Codice:* `app/static/app.js:refreshRound`
|
||
- **[RND-31]** Una volta rivelato, il risultato resta salvato nel browser
|
||
(`localStorage.plm_persisted_result`) anche dopo che il round è `closed`
|
||
(quando `GET /rounds/current` non lo restituisce più), fino all'apertura di
|
||
un round nuovo. Per un dispositivo che si è perso del tutto la finestra,
|
||
`GET /users/me/last-round-result` restituisce dal database l'ultimo round
|
||
`closed` a cui l'utente ha partecipato, se ha vinto e l'importo vinto.
|
||
*Codice:* `app/static/app.js:checkLastRoundResult`, `app/api/routes/users.py:last_round_result`
|
||
|
||
## Limite noto
|
||
|
||
- **[RND-32]** Se il server si riavvia mentre un round è in `drawing`,
|
||
l'attesa del blocco **non riprende da sola**: lo scheduler riprende i round
|
||
in `closing` e `paying_out`, ma su un round in `drawing` non fa nulla. È
|
||
l'ultimo prerequisito mancante per un funzionamento completamente non
|
||
presidiato (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
|
||
*Codice:* `app/rounds/scheduler.py:RoundScheduler._tick`
|