# Documentazione di PLM Lottery

Questa cartella è la **fonte di verità** del progetto: si lavora **docs-first**
(prima si scrive o si modifica la documentazione, poi il codice) e ogni
informazione ha **un solo proprietario** (SSOT). Questo file è l'indice: da
qui si raggiunge tutto il resto.

## I tre principi

1. **Docs-first.** Nessuna modifica di comportamento parte dal codice. Si
   modifica il requisito (o si scrive l'ADR, se è una scelta nuova), poi si
   implementa, poi si testa. Spec, codice e test entrano nello stesso commit.
2. **SSOT — un solo proprietario per ogni informazione.** Il *perché* di una
   scelta sta in un ADR; il *cosa* verificabile in un requisito
   (`PREFISSO-NN`) del documento di dominio; il *come* nel codice; la cronologia
   dei difetti in `storico-bug.md`. Gli altri documenti **rimandano all'ID**,
   non ripetono il testo. Se due documenti dicono cose diverse, vince la
   specifica e si corregge l'altro.
3. **Un ADR per ogni funzionalità.** Ogni funzionalità nuova inizia con un ADR
   in [adr/](adr/README.md) (modello: [adr/TEMPLATE.md](adr/TEMPLATE.md)) che
   registra contesto, decisione, alternative scartate e conseguenze, e ne
   elenca i requisiti.

## Dove si trova cosa

| Domanda | Dove |
|---|---|
| Perché è fatto così? Quali alternative sono state scartate? | [adr/](adr/README.md) — indice per area e tabella funzionalità → ADR |
| Cosa deve fare esattamente il software? | I documenti di dominio qui sotto (requisiti con ID stabile) |
| Quali limiti abbiamo accettato? | [limiti-noti.md](limiti-noti.md) (`LIM-nn`) |
| Che bug sono stati trovati/corretti? Quali restano aperti? | [storico-bug.md](storico-bug.md); i soli aperti in [../BUGS.md](../BUGS.md) |
| In che ordine si implementano le correzioni aperte? | [piano-correzioni.md](piano-correzioni.md) |
| Come si modifica la documentazione/il codice? | [processo-di-modifica.md](processo-di-modifica.md) |
| Come si installa, si avvia, si usa? | Guide operative qui sotto |

## Specifica (documenti di dominio)

Punto d'ingresso narrativo: [come-funziona.md](come-funziona.md).

| Documento | Prefisso | Contenuto |
|---|---|---|
| [registrazione-e-depositi.md](registrazione-e-depositi.md) | `REG`, `DEP` | Account, indirizzi, depositi, saldo |
| [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | `BET`, `WDR` | Scommesse e prelievi |
| [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | `RND` | Apertura, chiusura, estrazione, pagamento |
| [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | `TX` | Ciclo di vita delle transazioni, RBF, riconciliazione |
| [connessione-electrum.md](connessione-electrum.md) | `ELC` | Accesso alla rete PLM e difese |
| [architettura.md](architettura.md) | `ARC` | Struttura del codice, processi, frontend, test |
| [modello-dati.md](modello-dati.md) | `DAT` | Tabelle, campi, stati, vincoli |
| [api.md](api.md) | `API` | Endpoint, risposte, codici di errore |
| [sicurezza.md](sicurezza.md) | `SEC` | Fiducia, chiavi, autenticazione, limiti sui tentativi |
| [audit-log.md](audit-log.md) | `AUD` | Catalogo degli eventi di audit |
| [operativita.md](operativita.md) | `OPS` | Backup, riavvii, incidenti |

## Decisioni, limiti, storia

| Documento | Prefisso | Contenuto |
|---|---|---|
| [adr/](adr/README.md) | `ADR` | Una decisione di progetto per file (53 al momento) |
| [limiti-noti.md](limiti-noti.md) | `LIM` | Limiti accettati consapevolmente |
| [storico-bug.md](storico-bug.md) | `B-nn` | Tutti i bug trovati e corretti |
| [piano-correzioni.md](piano-correzioni.md) | — | Ordine di implementazione delle correzioni aperte |

## Guide operative (senza requisiti)

[setup.md](setup.md) · [running-the-server.md](running-the-server.md) ·
[guida-utente.md](guida-utente.md) · [guida-admin.md](guida-admin.md). Si
aggiornano quando la specifica cambia qualcosa di visibile.

## Lingua

La documentazione di `docs/` è in italiano, per scelta esplicita; tutto il
resto del repository (codice, commenti, commit, `CLAUDE.md`, `BUGS.md`) è in
inglese.