plm-lottery/docs/processo-di-modifica.md

# Processo di modifica: dalla documentazione al codice

L'indice di tutta la documentazione è [README.md](README.md). Questo documento
ne fissa le regole di lavoro.

## Principi: docs-first, SSOT, ADR

- **Docs-first.** Si cambia prima la documentazione, poi il codice; spec,
  codice e test stanno nello stesso commit.
- **SSOT.** Ogni informazione ha un solo proprietario e gli altri documenti
  rimandano a lei per ID senza ripeterla:

  | Informazione | Proprietario |
  |---|---|
  | Perché una scelta (contesto, alternative, conseguenze) | un ADR in [adr/](adr/README.md) |
  | Che cosa deve fare il software (regola verificabile) | il requisito `PREFISSO-NN` del documento di dominio |
  | Schema, stati, vincoli | `DAT` in [modello-dati.md](modello-dati.md) |
  | Soglie e rischi di sicurezza | `SEC` in [sicurezza.md](sicurezza.md) |
  | Eventi di audit | `AUD` in [audit-log.md](audit-log.md) |
  | Come lo fa | il codice (riferimento `percorso:funzione`) |
  | Limiti accettati | `LIM` in [limiti-noti.md](limiti-noti.md) |
  | Difetti trovati e corretti | [storico-bug.md](storico-bug.md) |

- **Un ADR per ogni funzionalità.** Una funzionalità nuova, o un cambio di
  scelta in una esistente, parte da un ADR scritto da [adr/TEMPLATE.md](adr/TEMPLATE.md):
  prossimo numero libero, stato *Proposta* finché non è approvato, poi
  *Accettata*. L'ADR elenca i requisiti che lo attuano; i requisiti citano
  l'ADR. Un ADR non si riscrive: se la scelta cambia se ne scrive uno nuovo e
  il vecchio passa a *Sostituita da ADR-MM*. Un nuovo ADR va aggiunto
  all'indice per area e alla tabella funzionalità → ADR di
  [adr/README.md](adr/README.md).

La cartella `docs/` è la **specifica** di PLM Lottery. Descrive cosa il
software fa e perché; il codice è l'implementazione di questa specifica.
Ogni modifica di comportamento parte da qui.

## Convenzione dei requisiti

Ogni regola verificabile ha un **identificativo stabile**, nella forma
`PREFISSO-NN`, scritto in grassetto all'inizio del punto che la descrive,
seguito dai riferimenti all'implementazione e, dove esistono, ai test:

```markdown
- **[RND-11]** Al primo passo dello scheduler successivo alla scadenza il round
  passa a `closing`; le scommesse sono però rifiutate già dall'istante della
  scadenza ([BET-04]).
  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
  *Test:* `tests/unit/test_scheduler.py`
```

Regole della convenzione:

- **Un identificativo non si riusa mai.** Un requisito eliminato resta nel
  documento come `~~[RND-11]~~ Rimosso: <motivo>`, così i riferimenti già
  scritti (commenti, commit, test) non puntano a una regola diversa.
- **I numeri non si rinumerano.** Un requisito nuovo prende il numero
  successivo al più alto del suo prefisso, anche se finisce in mezzo al testo.
- **I riferimenti al codice** sono `percorso:funzione` o `percorso:Classe.metodo`,
  mai numeri di riga (cambiano a ogni modifica).
- Il testo descrittivo che non contiene regole (introduzioni, spiegazioni,
  esempi) non ha identificativo.
- **Un solo proprietario per regola.** Ogni regola ha l'identificativo in un
  solo documento; gli altri documenti che la citano rimandano a quell'ID
  invece di ripeterla con un ID proprio. Il documento di dominio (round,
  scommesse, transazioni…) è proprietario del comportamento, `DAT` dello
  schema, `SEC` delle soglie di sicurezza.
- **Niente formulazioni vaghe nelle regole.** "Circa", "normalmente", "prima o
  poi" non compaiono in un requisito: si scrive la condizione esatta, con il
  nome della costante.

### Requisiti non ancora implementati

La specifica può essere più avanti del codice: è il caso normale fra il passo 1
e il passo 3 del ciclo qui sotto. Un requisito che il codice non soddisfa
ancora porta, subito dopo i riferimenti, una riga di stato e una che dice cosa
fa il codice oggi:

```markdown
- **[RND-33]** L'altezza del blocco di estrazione è fissata all'ingresso in
  `drawing` come `tip_at_close + 1` e non cambia più.
  *Codice:* `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
  *Test:* —
  *Stato:* da implementare (B-nn) · *Oggi:* si usa la punta vista al primo
  controllo utile, che può essere un blocco successivo.
```

- *Codice* indica dove andrà l'implementazione (il file o la funzione
  esistente più vicina); *Test* è `—` finché il test non esiste.
- Il B-nn rimanda alla voce di [BUGS.md](../BUGS.md) che descrive la
  correzione; l'ordine di implementazione è in
  [piano-correzioni.md](piano-correzioni.md).
- Quando il codice viene implementato, nello stesso commit si tolgono le righe
  *Stato* e *Oggi* e si completano *Codice* e *Test*. `git grep "da
  implementare"` elenca in ogni momento tutto ciò che manca.
- Un requisito modificato (non nuovo) mantiene il suo identificativo: il testo
  descrive il comportamento atteso, *Oggi* quello attuale.

### Prefissi

| Prefisso | Documento | Ambito |
|---|---|---|
| `ARC` | [architettura.md](architettura.md) | Struttura del codice, processi, frontend, test |
| `DAT` | [modello-dati.md](modello-dati.md) | Tabelle, campi, stati, vincoli |
| `API` | [api.md](api.md) | Endpoint, formato delle risposte, codici di errore |
| `SEC` | [sicurezza.md](sicurezza.md) | Chiavi, autenticazione, limiti, rischi accettati |
| `REG` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Registrazione e account |
| `DEP` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Depositi e saldo |
| `BET` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Scommesse |
| `WDR` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Prelievi |
| `RND` | [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | Round, estrazione, pagamento |
| `TX` | [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | Ciclo di vita delle transazioni, RBF, riconciliazione |
| `ELC` | [connessione-electrum.md](connessione-electrum.md) | Connessione alla rete |
| `AUD` | [audit-log.md](audit-log.md) | Eventi del registro di audit |
| `OPS` | [operativita.md](operativita.md) | Procedure operative |
| `ADR` | [adr/](adr/README.md) | Decisioni di progetto (un file per decisione) |
| `LIM` | [limiti-noti.md](limiti-noti.md) | Limiti noti accettati |

## Il ciclo di una modifica

0. **Scegliere.** Se la modifica è una funzionalità o una scelta nuova, si
   scrive o aggiorna l'ADR (e si approva) prima di toccare i requisiti.
1. **Modificare la specifica.** Si cambia il testo del requisito in `docs/`
   (o se ne aggiunge uno nuovo con il prossimo numero libero). Se la modifica
   tocca una decisione (`ADR-*`) o un limite (`LIM-*`), si aggiorna anche
   quello; se introduce una funzionalità o una scelta nuova, si scrive prima
   il relativo ADR (vedi sotto).
2. **Individuare l'impatto.** I riferimenti *Codice* e *Test* del requisito
   dicono dove intervenire. Si cercano anche le altre occorrenze
   dell'identificativo nel repository (`git grep RND-11`) e i requisiti di
   altri documenti che dipendono dallo stesso codice.
3. **Implementare e testare.** Si modifica il codice e si aggiunge o aggiorna
   un test che verifica il nuovo comportamento. Il test cita l'identificativo
   nella sua docstring.
4. **Allineare i riferimenti.** Se il codice si è spostato (funzione
   rinominata, file diviso), si aggiornano i riferimenti *Codice* del
   requisito.
5. **Commit unico.** Specifica, codice e test entrano nello stesso commit,
   con l'identificativo nel messaggio (ad esempio
   `Close the round on its own deadline (RND-11)`).

Una correzione di bug che non cambia la specifica (il codice non faceva ciò
che il documento già diceva) segue la convenzione `B-nn` descritta in
[storico-bug.md](storico-bug.md): numero successivo, commit dedicato, test di
regressione. Se invece il bug rivela che la specifica era sbagliata o
incompleta, si corregge prima la specifica, come per qualunque altra modifica.

## Documenti della specifica

Il punto d'ingresso è [come-funziona.md](come-funziona.md). Le guide
operative ([setup.md](setup.md), [running-the-server.md](running-the-server.md),
[guida-utente.md](guida-utente.md), [guida-admin.md](guida-admin.md)) non
contengono requisiti: descrivono come usare il software, e si aggiornano
quando la specifica cambia qualcosa di visibile.