# Guida admin

Come gestire la configurazione operativa di PLM Lottery. Presuppone che il
server sia già avviato — vedi [running-the-server.md](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. Non è protetto da login personale, ma da un
**token condiviso** (`ADMIN_TOKEN`, definito in `.env`).

Apri la pagina, incolla il valore di `ADMIN_TOKEN` nel campo "Admin token" e
usa i bottoni:

- **"Carica configurazione attuale"** → mostra `fee_address` e
  `bet_amount_sats` (in PLM) correnti
- **"Salva"** → aggiorna i valori nel database, effetto immediato, nessun
  riavvio del server necessario

## Cosa si configura

| 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, mostrato/impostato in PLM (internamente il backend lavora in sats: 1 PLM = 100.000.000 sats). |

`ROUND_DURATION_SECONDS` (durata del round) e `ROUND_COOLDOWN_SECONDS` (pausa
tra un round e il successivo, default 30s) **non** sono qui: sono variabili
d'ambiente in `.env`, non modificabili a runtime — per cambiarle serve
riavviare il server con il nuovo valore.

## 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`:

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

# aggiornarla (importi in sats: 10 PLM = 1000000000)
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}'
```

## 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`.