Files

T

davideandClaude Sonnet 5 0e56f63e63 Document the DB-only config model and the new dashboard sections

CLAUDE.md and docs/guida-admin.md now describe RoundConfig as the sole
source of truth for business parameters, with no env var counterpart —
defaults live as hardcoded model column defaults, not app/config.py.
guida-admin.md documents the four new dashboard sections (Round,
Transazioni pendenti, Audit log alongside Parametri/Utenti). setup.md
points readers to the admin panel instead of .env for those values.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-21 15:06:51 +02:00

4.7 KiB

Raw Blame History

Guida admin

Come gestire la configurazione operativa di PLM Lottery. Presuppone che il server sia già avviato — vedi running-the-server.md.

Accesso

Il pannello admin è su https://<host>/admin — non è collegato da nessun link nell'interfaccia utente (né in entrata né in uscita): ci si arriva solo conoscendo l'URL. La pagina mostra solo un campo token finché non accedi: non è protetta da login personale, ma da un token condiviso (ADMIN_TOKEN, definito in .env).

Incolla il valore di ADMIN_TOKEN e premi "Accedi" (o Invio): se il token è valido, si apre la dashboard con una navbar in alto e carica automaticamente tutte le sezioni — nessun bottone "Carica" separato. Il token resta in sessionStorage (si perde chiudendo la tab/il browser); "Esci" torna alla sola schermata di login.

Sezioni della dashboard

Parametri — configurazione operativa (vedi tabella sotto)
Utenti — elenco utenti, saldo, accesso alla chiave privata
Round — storico round: stato, vincitore, importi, txid di payout
Transazioni pendenti — bet/payout/prelievi non ancora confermati, candidati al fee-bump RBF
Audit log — eventi registrati dal sistema (config cambiata, bet, payout, accessi a chiavi private, ecc.)

Parametri

Tutti i parametri operativi/di business sono nella sezione "Parametri", salvati nel database — modificabili in qualsiasi momento, effetto immediato, nessun riavvio del server necessario. Non esiste alcuna variabile d'ambiente equivalente: .env contiene solo segreti e configurazione di infrastruttura (chiave master, JWT, Electrum, token admin), non parametri di business — quelli si toccano solo da qui.

Campo	Significato
Fee address	L'indirizzo PLM su cui finisce il 30% di ogni round (fee). Obbligatorio: i payout non partono se questo campo è vuoto.
Bet amount (PLM)	Il costo fisso d'ingresso per round.
Durata round (secondi)	Quanto resta aperto un round prima di chiudersi ed estrarre il vincitore.
Pausa tra un round e il successivo (secondi)	Cooldown dopo la chiusura di un round, prima che il successivo si apra — dà tempo ai giocatori di vedere l'esito.
Importo minimo deposito/prelievo (PLM)	Soglia minima per un prelievo (i depositi non hanno un controllo minimo lato server, solo un floor consigliato).
Fee rate di rete (sat/vB)	Fee per byte usata per costruire bet, payout e prelievi.
Timeout prima del fee-bump RBF (secondi)	Dopo quanto tempo senza conferma una transazione viene ritrasmessa con fee più alta.

Tutti gli importi in PLM vengono convertiti in sats (1 PLM = 100.000.000 sats) solo nella chiamata API — il backend lavora sempre in sats.

Su un'istanza nuova (mai avviata), questi campi partono con dei default hardcoded nel codice (RoundConfig in app/db/models.py: bet 10 PLM, round 10 minuti, cooldown 30s, minimo 1 PLM, fee 1 sat/vB, RBF timeout 900s) — vanno comunque rivisti e confermati dal pannello prima del primo utilizzo reale.

Alternative all'interfaccia grafica

Le stesse operazioni si possono fare da terminale o da Swagger UI (https://<host>/docs, sezione admin), sempre passando ADMIN_TOKEN nell'header X-Admin-Token:

# leggere la configurazione
curl https://<host>/admin/config -H "X-Admin-Token: <ADMIN_TOKEN>"

# aggiornarla (importi in sats: 10 PLM = 1000000000; solo i campi passati vengono cambiati)
curl -X PUT https://<host>/admin/config \
  -H "X-Admin-Token: <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"fee_address": "plm1q...", "bet_amount_sats": 1000000000, "round_duration_seconds": 600}'

Utenti e chiave privata

La card "Utenti" elenca id, username, indirizzo e saldo di ogni utente registrato. Il bottone "Mostra" su ogni riga rivela la chiave privata (WIF) di quell'utente, dietro conferma esplicita — serve per interventi manuali (es. restituire fondi bloccati). Ogni visualizzazione viene registrata nell'audit log (admin_privkey_accessed). Questo non introduce una nuova falla: il server è già custodial, la chiave master da cui derivano tutte le chiavi utente vive sul server — questo pannello espone solo qualcosa che l'operatore può già fare via script.

Limiti noti

Il token è unico e condiviso: non c'è identità per singolo admin né audit di chi ha cambiato cosa (oltre alla tabella audit_log generica).
Nessun rate limiting sugli endpoint admin (né su registrazione/bet/ prelievo utente).
Se un payout fallisce (es. Electrum disconnesso, UTXO insufficienti), il round resta bloccato in paying_out senza retry automatico — richiede intervento manuale.

Per l'elenco completo dei gap noti vedi la sezione "Known gaps / TODO" in CLAUDE.md.

4.7 KiB Raw Blame History