davideandClaude Opus 5.5
61efbb0e37
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>
4.4 KiB
Processo di modifica: dalla documentazione al codice
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:
- **[RND-11]** Alla scadenza il round passa subito a `closing`: da quel momento
nessuna scommessa è più accettata.
*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:funzioneopercorso:Classe.metodo, mai numeri di riga (cambiano a ogni modifica). - Il testo descrittivo che non contiene regole (introduzioni, spiegazioni, esempi) non ha identificativo.
Prefissi
| Prefisso | Documento | Ambito |
|---|---|---|
ARC |
architettura.md | Struttura del codice, processi, frontend, test |
DAT |
modello-dati.md | Tabelle, campi, stati, vincoli |
API |
api.md | Endpoint, formato delle risposte, codici di errore |
SEC |
sicurezza.md | Chiavi, autenticazione, limiti, rischi accettati |
REG |
registrazione-e-depositi.md | Registrazione e account |
DEP |
registrazione-e-depositi.md | Depositi e saldo |
BET |
scommesse-e-prelievi.md | Scommesse |
WDR |
scommesse-e-prelievi.md | Prelievi |
RND |
ciclo-di-vita-del-round.md | Round, estrazione, pagamento |
TX |
transazioni-e-riconciliazione.md | Ciclo di vita delle transazioni, RBF, riconciliazione |
ELC |
connessione-electrum.md | Connessione alla rete |
AUD |
audit-log.md | Eventi del registro di audit |
OPS |
operativita.md | Procedure operative |
DEC |
decisioni-e-limiti.md | Decisioni di progetto |
LIM |
decisioni-e-limiti.md | Limiti noti accettati |
Il ciclo di una modifica
- 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 (DEC-*) o un limite (LIM-*), si aggiorna anche quello. - 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. - 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.
- Allineare i riferimenti. Se il codice si è spostato (funzione rinominata, file diviso), si aggiornano i riferimenti Codice del requisito.
- 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: 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. Le guide operative (setup.md, running-the-server.md, guida-utente.md, guida-admin.md) non contengono requisiti: descrivono come usare il software, e si aggiornano quando la specifica cambia qualcosa di visibile.