ff

2026-10-26 00:25:18 +01:00
parent 1df884da84
commit 1bc033c329
46 changed files with 2958 additions and 0 deletions
@@ -0,0 +1,60 @@
+# {{TITOLO}}
+
+Stato: **da approvare** · Versione 0.1 · {{DATA}} · Prefisso task: **T-{{PREFISSO}}**
+
+**Decisioni di riferimento:** <!-- `D-…` o «nessuna» -->
+
+---
+
+## 1. Contesto e requisito
+
+<!-- DA COMPILARE: perché serve, chi lo ha chiesto e quando, cosa deve ottenere l'utente. -->
+
+## 2. Requisiti
+
+| ID | Requisito | Origine |
+|---|---|---|
+| <!-- REQ-AREA-01 --> | <!-- «Il sistema …», limiti numerici espliciti --> | <!-- committente, data --> |
+
+## 3. Opzioni valutate e raccomandazione
+
+<!-- Solo se c'è una scelta da fare. Ogni opzione con pro, contro, costo. La scelta finale
+diventa una D-xxx in DECISIONS.md. -->
+
+## 4. Regole
+
+<!-- DA COMPILARE in forma normativa. -->
+
+## 5. Architettura del modulo
+
+<!-- DA COMPILARE: servizi, code, modelli dati, storage toccati. -->
+
+## 6. Contratto API
+
+| Metodo | Percorso | Ruolo minimo | Esiti |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | 200 · 404 · 422 |
+
+## 7. Errori e casi limite
+
+| Caso | Comportamento |
+|---|---|
+| <!-- DA COMPILARE --> | |
+
+## 8. Criteri di accettazione
+
+| # | Criterio |
+|:-:|---|
+| {{PREFISSO}}1 | <!-- «Dato …, quando …, allora …» --> |
+
+## 9. Task
+
+| ID | Attività | Prio | Dipende da |
+|----|----------|------|------------|
+| T-{{PREFISSO}}01 | <!-- DA COMPILARE --> | P1 | — |
+
+## 10. Domande ancora aperte
+
+<!-- Finché questa sezione non è vuota il documento non può essere approvato. -->
+
+- <!-- DA COMPILARE o «nessuna» -->
@@ -0,0 +1,30 @@
+# API — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Il contratto si scrive **prima** del codice. Se esiste un `openapi.yaml`, quello è la fonte di verità.
+
+## Convenzioni
+
+| Aspetto | Regola |
+|---|---|
+| Prefisso | `/api/v1` |
+| Formato | JSON, UTF-8, date ISO 8601 UTC |
+| Autenticazione | <!-- DA COMPILARE --> |
+| Errori | `{ "error": { "code", "message", "details" } }` |
+
+## Endpoint — Stato di servizio
+
+### `GET /health`  *(pubblico)*
+
+Risponde `200 {"status": "ok"}`.
+
+## Endpoint previsti
+
+<!-- Un gruppo per modulo. Stato nel titolo: *(previsto)* · ✅ *implementato (T-xxx)*. -->
+
+### <!-- Gruppo --> — *(previsto)*
+
+| Metodo | Percorso | Ruolo minimo | Descrizione | Task |
+|---|---|---|---|---|
+| <!-- DA COMPILARE --> | | | | |
@@ -0,0 +1,45 @@
+# ARCHITECTURE — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+## Struttura del repository
+
+```
+<!-- DA COMPILARE -->
+```
+
+## 1. Vista d'insieme
+
+```
+<!-- DA COMPILARE: schema ASCII dei servizi -->
+```
+
+## 2. Servizi/componenti
+
+| Componente | Tecnologia | Responsabilità |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+## 3. Flusso principale
+
+<!-- DA COMPILARE: passo per passo, con code e dati scambiati. -->
+
+## 4. Macchina a stati
+
+<!-- DA COMPILARE: stati, transizioni ammesse (ogni altra è rifiutata), invarianti — o «non applicabile». -->
+
+## 5. Code e lavori asincroni
+
+<!-- DA COMPILARE o «non applicabile». -->
+
+## 6. Storage
+
+<!-- DA COMPILARE: database, file/oggetti, convenzioni di nome. -->
+
+## 7. Sicurezza e multi-tenancy
+
+<!-- DA COMPILARE: autenticazione, ruoli, isolamento, segreti (mai nel repository). -->
+
+## 8. Aperto / da decidere
+
+- <!-- DA COMPILARE -->
@@ -0,0 +1,10 @@
+# CHANGELOG — {{PROGETTO}}
+
+Formato: ogni voce riporta **data · componente · modifica · motivo**. Le voci più recenti in alto.
+
+---
+
+## {{DATA}} — Avvio della documentazione
+
+Creata la documentazione di progetto con metodo spec-driven: PROJECT_MEMORY, ARCHITECTURE, API,
+DATABASE, DECISIONS (D-001…D-003), TODO.
@@ -0,0 +1,18 @@
+# DATABASE — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Motore: <!-- DA COMPILARE --> · Migrazioni: <!-- DA COMPILARE: strumento e numerazione -->
+
+Regole: date sempre UTC · una migrazione per modifica, mai riscrivere una migrazione applicata ·
+nessun file binario nel database.
+
+## A. <!-- Gruppo di tabelle -->
+
+### `<!-- tabella -->`  *(migrazione `0001`)*
+
+| Colonna | Tipo | Null | Note |
+|---|---|:-:|---|
+| `id` | | no | PK |
+
+Indici: <!-- DA COMPILARE --> · Vincoli: <!-- DA COMPILARE -->
@@ -0,0 +1,28 @@
+# DECISIONS — {{PROGETTO}} (Architecture Decision Records)
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Formato: ogni decisione ha contesto, opzioni valutate, scelta e motivazione.
+Stato: `accepted` · `proposed` · `superseded by D-xxx` · `rejected`.
+Le decisioni non si cancellano: si superano.
+
+---
+
+## D-001 — Stack tecnologico
+- **Stato:** proposed
+- **Contesto:** <!-- DA COMPILARE -->
+- **Opzioni:** <!-- (a) …; (b) … -->
+- **Scelta:** <!-- DA COMPILARE -->
+- **Motivazione:** <!-- DA COMPILARE -->
+
+## D-002 — Sviluppo spec-driven
+- **Stato:** accepted
+- **Contesto:** le regole di business scritte solo nel codice emergono dal debugging invece che dalla specifica.
+- **Opzioni:** (a) documentazione a valle del codice; (b) documento di modulo approvato prima del codice.
+- **Scelta:** (b). Nessun codice senza un documento di modulo in stato *Approvato*, con regole, contratto, criteri di accettazione e task.
+- **Motivazione:** le regole diventano esplicite e verificabili prima di costare un difetto.
+
+## D-003 — La documentazione vive nel repository
+- **Stato:** accepted
+- **Scelta:** `docs/` nel repository del codice, aggiornata nella stessa modifica del codice che la riguarda.
+- **Motivazione:** documenti e codice non divergono; la revisione del codice è anche revisione dei documenti.
@@ -0,0 +1,12 @@
+# DEVELOPMENT_LOG — {{PROGETTO}}
+
+Diario operativo per sessione: cosa fatto, problemi, perché si è deciso così, prossime azioni.
+Le voci più recenti in alto. Le voci non si cancellano.
+
+---
+
+## {{DATA}} — Avvio della documentazione
+
+Creato lo scheletro della documentazione spec-driven.
+
+**Prossime azioni:** completare D-001 (stack), scrivere il primo documento di modulo.
@@ -0,0 +1,68 @@
+# PROJECT_MEMORY — {{PROGETTO}}
+
+> Memoria permanente del progetto. Leggere **sempre** questo file (e l'intera cartella `docs/`)
+> prima di scrivere codice. Aggiornarlo dopo ogni modifica significativa.
+
+Ultimo aggiornamento: **{{DATA}}** · Sessione: **avvio della documentazione**
+
+---
+
+## 1. Cos'è {{PROGETTO}}
+
+<!-- DA COMPILARE: cosa fa, per chi, flusso ad alto livello in 4-6 passi, valore. -->
+
+---
+
+## 2. Architettura attuale (sintesi)
+
+> Dettaglio completo in [`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+- <!-- DA COMPILARE: un punto per servizio/componente, con la tecnologia -->
+
+---
+
+## 3. Decisioni tecniche prese
+
+> Registro completo con alternative e motivazioni in [`DECISIONS.md`](./DECISIONS.md).
+
+- D-001 Stack tecnologico *(proposed)*
+- D-002 Sviluppo spec-driven: nessun codice senza un documento di modulo approvato
+- D-003 La documentazione vive nel repository e si aggiorna con il codice
+
+---
+
+## 4. Moduli e documenti di specifica
+
+| Modulo | Documento | Stato |
+|---|---|---|
+| <!-- DA COMPILARE --> | <!-- [`NOME_MODULE.md`](./NOME_MODULE.md) --> | da approvare |
+
+---
+
+## 5. Componenti GIÀ creati
+
+- [ ] <!-- DA COMPILARE -->
+
+## 6. Componenti ANCORA da creare
+
+- [ ] <!-- DA COMPILARE -->
+
+---
+
+## 7. Vincoli importanti
+
+<!-- Ciò che, se dimenticato, fa ripetere un errore. Ogni vincolo con il suo perché. -->
+
+- <!-- DA COMPILARE -->
+
+---
+
+## 8. Come continuare (per la prossima sessione)
+
+1. Leggere questo file, poi [`TODO.md`](./TODO.md) (P0 aperti per primi).
+2. Per il task scelto, leggere il documento di modulo e le decisioni citate.
+3. A fine lavoro: TODO, CHANGELOG, DEVELOPMENT_LOG e questo file.
+
+---
+
+<sub>Documentazione redatta con il metodo spec-driven di STS Lab Srl.</sub>
@@ -0,0 +1,25 @@
+# TODO — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Legenda stato: `pending` · `in_progress` · `done` · `blocked`
+Priorità: **P0** (fondante/bloccante) · **P1** (core) · **P2** (importante) · **P3** (successivo)
+
+**Regola:** un task entra in lavorazione solo se il suo documento di modulo è approvato (D-002).
+`done` solo con i test del criterio passanti.
+
+**Numerazione:** `T-<lettera del modulo><nn>` (es. `T-S<nn>` per la sicurezza, `T-W<nn>` per WhatsApp);
+la lettera si fissa quando nasce il modulo e si annota qui sotto.
+
+| Lettera | Modulo |
+|:-:|---|
+| <!-- S --> | <!-- Sicurezza & API --> |
+
+---
+
+## Documentazione ({{DATA}})
+
+| ID | Attività | Prio | Stato |
+|----|----------|------|-------|
+| T-D01 | Completare PROJECT_MEMORY, ARCHITECTURE, DECISIONS (D-001) | P0 | in_progress |
+| T-D02 | Primo documento di modulo approvato | P0 | pending |
@@ -0,0 +1,83 @@
+# {{SPEC_ID}} — {{TITOLO}}
+
+Stato: **da approvare** · Versione 0.1 · {{DATA}}
+
+**Requisiti coperti:** <!-- DA COMPILARE: `REQ-…` -->
+**Decisioni di riferimento:** <!-- `D-…` o «nessuna» -->
+
+---
+
+## 1. Contesto e obiettivo
+
+<!-- DA COMPILARE: perché questa capability esiste, cosa decide per l'utente. Un dato misurato
+vale più di un aggettivo. Se la spec è a sé per una ragione (regola delicata, rischio), dirlo. -->
+
+---
+
+## 2. Cosa cambia rispetto a ciò che è già scritto
+
+<!-- Solo se la spec modifica requisiti, decisioni o altre spec. Altrimenti rimuovere la sezione. -->
+
+| Dove | Prima | Dopo |
+|---|---|---|
+| | | |
+
+---
+
+## 3. Regole
+
+<!-- DA COMPILARE in forma NORMATIVA: «il sistema …», «non …», limiti numerici espliciti.
+Pseudocodice per gli algoritmi. Una tabella per le combinazioni di casi. Quando un comportamento
+sembra un errore ma è voluto, dirlo: «è una decisione, non una dimenticanza». -->
+
+---
+
+## 4. Contratto API
+
+### `METODO /api/v1/percorso`
+
+**Ingresso:** <!-- campi e tipi -->
+
+**Uscita:** <!-- campi e tipi -->
+
+| Esito | Codice |
+|---|:-:|
+| <!-- Riuscito --> | 200 |
+| <!-- Non trovato o di altro tenant --> | 404 |
+| <!-- Validazione fallita --> | 422 |
+
+Il dettaglio formale va in `04-api/openapi.yaml` **prima** del codice.
+
+---
+
+## 5. Dati
+
+<!-- DA COMPILARE: entità, colonne, vincoli toccati — rimando a DATA_MODEL e DATABASE. -->
+
+---
+
+## 6. Errori e casi limite
+
+| Caso | Comportamento |
+|---|---|
+| <!-- DA COMPILARE --> | |
+
+---
+
+## 7. Criteri di accettazione
+
+Ogni criterio è verificabile da un test e ha un esito binario.
+
+| # | Criterio |
+|:-:|---|
+| {{LETTERA}}1 | <!-- DA COMPILARE: «Dato …, quando …, allora …» --> |
+| {{LETTERA}}2 | |
+
+---
+
+## 8. Task
+
+| ID | Task | Dipende da |
+|---|---|---|
+| **{{T0}}** | <!-- DA COMPILARE --> | — |
+| **{{T1}}** | Test di accettazione {{LETTERA}}1–{{LETTERA}}n | {{T0}} |
@@ -0,0 +1,153 @@
+# {{PROGETTO}} — Indice della documentazione
+
+Ultimo aggiornamento: **{{DATA}}**
+
+| Step | Contenuto | Stato |
+|:-:|---|:-:|
+| 0 | Scheletro della documentazione · indice · decisioni iniziali | 🟡 |
+| 1 | `01-product/` + `02-architecture/` — visione, requisiti, architettura | ⬜ |
+| 2 | `03-specs/` — specifiche e criteri di accettazione | ⬜ |
+| 3 | `04-api/` + `05-data/` — contratto OpenAPI e schema dati | ⬜ |
+| 4 | `06-devops/` — ambienti, pipeline, infrastruttura | ⬜ |
+| 5 | `07-quality/` + `08-project/` — tracciabilità e backlog | ⬜ |
+| 6 | Implementazione — vedi [`08-project/ROADMAP.md`](08-project/ROADMAP.md) | ⬜ |
+
+<!-- Novità: un riquadro per ogni consegna rilevante, il più recente in alto. Esempio:
+> **Titolo breve (AAAA-MM-GG):** cosa è cambiato e perché — `REQ-…`, `D-…`, `T-…`.
+> Verificato come (test, sistema reale) — backend N (+k).
+-->
+
+---
+
+## Cos'è questo progetto
+
+<!-- DA COMPILARE: due o tre frasi. Che cosa fa il prodotto, per chi, su quale stack. -->
+
+Obiettivi vincolanti del progetto:
+
+1. <!-- DA COMPILARE: obiettivo misurabile -->
+2. <!-- DA COMPILARE -->
+3. **Spec-driven** — nessuna riga di codice senza una spec approvata e tracciata (D-002).
+
+---
+
+## Metodo: spec-driven development
+
+Il flusso di lavoro è vincolato e va in un'unica direzione:
+
+```
+REQ-xxx (01-product/REQUIREMENTS.md)
+    │  cosa deve fare il prodotto
+    ▼
+SPEC-xxx (03-specs/)
+    │  come lo fa: contratto API, dati, regole, errori, criteri di accettazione
+    ▼
+T-xxx (08-project/TODO.md)
+    │  unità di lavoro implementabile
+    ▼
+codice + test
+    │
+    ▼
+07-quality/TRACEABILITY.md   ← chiude il cerchio: ogni REQ ha spec, task e test
+```
+
+**Regola:** si implementa solo ciò che ha una `SPEC-xxx` in stato *Approvata*. Una spec non
+approvata non genera task; un task senza spec non entra in lavorazione. Ogni scelta strutturale
+diventa una decisione numerata `D-xxx` in [`08-project/DECISIONS.md`](08-project/DECISIONS.md).
+
+---
+
+## Mappa dei documenti
+
+Legenda stato: ⬜ da scrivere · 🟡 in stesura · ✅ completo · 🔒 congelato (modifica solo via nuova D-xxx)
+
+### 01 · Prodotto — *cosa* e *per chi*
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`01-product/VISION.md`](01-product/VISION.md) | Perché esiste il prodotto, valore, perimetro, non-obiettivi | ⬜ |
+| [`01-product/GLOSSARY.md`](01-product/GLOSSARY.md) | Lessico condiviso | ⬜ |
+| [`01-product/PERSONAS_CASI_USO.md`](01-product/PERSONAS_CASI_USO.md) | Attori, persone, casi d'uso end-to-end | ⬜ |
+| [`01-product/REQUIREMENTS.md`](01-product/REQUIREMENTS.md) | Requisiti `REQ-*` e difetti noti `DIF-*` | ⬜ |
+
+### 02 · Architettura — *come è fatto*
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`02-architecture/ARCHITECTURE.md`](02-architecture/ARCHITECTURE.md) | Vista d'insieme, servizi, flusso principale | ⬜ |
+| [`02-architecture/C4_MODEL.md`](02-architecture/C4_MODEL.md) | Contesto / Contenitori / Componenti | ⬜ |
+| [`02-architecture/DOMAIN_WORKFLOW.md`](02-architecture/DOMAIN_WORKFLOW.md) | Stati, transizioni ammesse, invarianti | ⬜ |
+| [`02-architecture/DATA_MODEL.md`](02-architecture/DATA_MODEL.md) | Entità, relazioni, chiavi, cancellazioni, invarianti | ⬜ |
+| [`02-architecture/SECURITY.md`](02-architecture/SECURITY.md) | Autenticazione, autorizzazione, segreti, audit | ⬜ |
+
+### 03 · Specifiche — *contratto per l'implementazione*
+
+| Spec | Capability | Stato |
+|---|---|---|
+<!-- Una riga per spec, aggiunta quando la spec nasce:
+| [`SPEC-001-slug.md`](03-specs/SPEC-001-slug.md) | Capability · N criteri · T-010…019 | 🟡 da approvare |
+-->
+
+### 04 · API — *contratto esterno*
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`04-api/API.md`](04-api/API.md) | Catalogo endpoint, convenzioni, errori, paginazione | ⬜ |
+| [`04-api/openapi.yaml`](04-api/openapi.yaml) | Contratto OpenAPI 3.1 — **fonte di verità** | ⬜ |
+
+### 05 · Dati
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`05-data/DATABASE.md`](05-data/DATABASE.md) | Schema fisico: tabelle, enumerazioni, indici, vincoli, migrazioni | ⬜ |
+| [`05-data/SEED_BOOTSTRAP.md`](05-data/SEED_BOOTSTRAP.md) | Stato iniziale, bootstrap idempotente, credenziali | ⬜ |
+
+### 06 · DevOps
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`06-devops/INFRASTRUCTURE.md`](06-devops/INFRASTRUCTURE.md) | Topologia, servizi, risorse, rete, persistenza | ⬜ |
+| [`06-devops/ENVIRONMENTS.md`](06-devops/ENVIRONMENTS.md) | dev/qa/prod, variabili, promozione | ⬜ |
+| [`06-devops/CI_CD.md`](06-devops/CI_CD.md) | Pipeline, verifiche, rilascio, rientro | ⬜ |
+| [`06-devops/OBSERVABILITY.md`](06-devops/OBSERVABILITY.md) | Log, metriche, allarmi | ⬜ |
+| [`06-devops/RUNBOOK.md`](06-devops/RUNBOOK.md) | Procedure: sintomo → verifica → azione → conferma | ⬜ |
+| [`06-devops/BACKUP_DR.md`](06-devops/BACKUP_DR.md) | Backup, ripristino, prova periodica | ⬜ |
+
+### 07 · Qualità
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`07-quality/TEST_STRATEGY.md`](07-quality/TEST_STRATEGY.md) | Livelli di test, simulatori, criteri di uscita | ⬜ |
+| [`07-quality/ACCEPTANCE_CRITERIA.md`](07-quality/ACCEPTANCE_CRITERIA.md) | Criteri bloccanti di rilascio | ⬜ |
+| [`07-quality/TRACEABILITY.md`](07-quality/TRACEABILITY.md) | Matrice REQ → SPEC → T → test, senza righe scoperte | ⬜ |
+
+### 08 · Progetto
+
+| Documento | Contenuto | Stato |
+|---|---|---|
+| [`08-project/DECISIONS.md`](08-project/DECISIONS.md) | Decisioni architetturali `D-xxx` | 🟡 |
+| [`08-project/ROADMAP.md`](08-project/ROADMAP.md) | Fasi con criteri di uscita, dipendenze, rischi | ⬜ |
+| [`08-project/TODO.md`](08-project/TODO.md) | Task `T-xxx` per fase, tracciati sulle spec | ⬜ |
+| [`08-project/CHANGELOG.md`](08-project/CHANGELOG.md) | Cosa cambia per chi usa il prodotto | ⬜ |
+| [`08-project/DEVELOPMENT_LOG.md`](08-project/DEVELOPMENT_LOG.md) | Diario tecnico: cosa si è scoperto e perché | ⬜ |
+| [`08-project/PROJECT_MEMORY.md`](08-project/PROJECT_MEMORY.md) | **Da leggere a inizio di ogni sessione** | 🟡 |
+
+---
+
+## Struttura del repository
+
+```
+<!-- DA COMPILARE: albero delle cartelle principali, una riga di descrizione ciascuna -->
+```
+
+---
+
+## Riferimenti esterni
+
+| Risorsa | Percorso / URL |
+|---|---|
+| <!-- DA COMPILARE: repository, documenti del committente, sistemi collegati --> | |
+
+---
+
+<sub>Documentazione redatta con il metodo spec-driven di STS Lab Srl.</sub>
@@ -0,0 +1,37 @@
+# GLOSSARY — Lessico di {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Un termine, un significato. Gli stessi nomi si usano nei documenti, nel codice (classi,
+tabelle, rotte) e nell'interfaccia. Se un termine cambia, cambia qui per primo.
+
+---
+
+## 1. Termini di dominio
+
+| Termine | Significato | Nel codice |
+|---|---|---|
+| <!-- DA COMPILARE --> | | `nome_tecnico` |
+
+## 2. Termini di piattaforma
+
+| Termine | Significato | Nel codice |
+|---|---|---|
+| <!-- DA COMPILARE: es. Tenant, Utente, Ruolo --> | | |
+
+## 3. Convenzioni di identificazione nei documenti
+
+| ID | Significato | Dove nasce |
+|---|---|---|
+| `REQ-<AREA>-<nn>` | Requisito | `01-product/REQUIREMENTS.md` |
+| `DIF-<nn>` | Difetto noto | `01-product/REQUIREMENTS.md` |
+| `SPEC-<nnn>` | Specifica | `03-specs/` |
+| `T-<nnn>` | Task | sezione *Task* della spec e `08-project/TODO.md` |
+| `D-<nnn>` | Decisione | `08-project/DECISIONS.md` |
+| `A1`, `B3`, … | Criterio di accettazione (lettera della spec + numero) | sezione *Criteri* della spec |
+
+Gli ID sono **immutabili**: non si rinumerano e non si riusano. Un ID chiuso senza lavoro si barra (`~~T-xxx~~`).
+
+## 4. Falsi amici
+
+<!-- DA COMPILARE: parole che il committente usa con un significato diverso da quello tecnico. -->
@@ -0,0 +1,44 @@
+# PERSONAS E CASI D'USO — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Attori
+
+### 1.1 Attori umani
+
+| Attore | Ruolo nel sistema | Permessi |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+### 1.2 Attori non umani
+
+| Attore | Come interagisce |
+|---|---|
+| <!-- DA COMPILARE: sistemi esterni, job pianificati, integrazioni --> | |
+
+## 2. Persone
+
+### 2.1 <!-- Nome — Ruolo -->
+
+<!-- DA COMPILARE: chi è, cosa fa ogni giorno, cosa lo frustra oggi, cosa considera un successo. -->
+
+## 3. Casi d'uso
+
+### UC-01 — <!-- titolo come risultato: «Una richiesta completa diventa una proposta» -->
+
+| | |
+|---|---|
+| **Attore** | |
+| **Precondizioni** | |
+| **Flusso principale** | 1. … 2. … 3. … |
+| **Flussi alternativi** | |
+| **Esito** | |
+| **Requisiti** | `REQ-…` |
+
+## 4. Matrice attore × caso d'uso
+
+| Caso d'uso | <!-- attore 1 --> | <!-- attore 2 --> |
+|---|:-:|:-:|
+| UC-01 | ● | |
@@ -0,0 +1,62 @@
+# REQUIREMENTS — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}** · Stato: **in stesura**
+
+---
+
+## Come leggere questo documento
+
+Ogni requisito ha un identificativo `REQ-<AREA>-<nn>` immutabile, citato dalle specifiche
+(`03-specs/`), dai task (`08-project/TODO.md`) e dalla matrice di tracciabilità
+(`07-quality/TRACEABILITY.md`).
+
+**Tipo:**
+
+| Sigla | Significato |
+|:-:|---|
+| **P** | **Parità** — comportamento già presente nel sistema esistente, da riprodurre **identico**. Una differenza è una regressione. *(Solo per riscritture o evoluzioni.)* |
+| **C** | **Correzione** — comportamento esistente difettoso, da correggere. Rimanda a un `DIF-nn`. |
+| **N** | **Nuovo** — introdotto da questo progetto. |
+
+**Origine:** dove il requisito è stato osservato o deciso: committente e data, `D-nnn`, oppure
+`file:funzione` del codice esistente per i requisiti di parità.
+
+> **Regola.** Un requisito descrive un comportamento osservabile e verificabile, non una
+> soluzione tecnica. Modificare un requisito approvato è una decisione di prodotto e richiede
+> una `D-nnn`.
+
+---
+
+## Riepilogo
+
+| Area | Codice | Requisiti | P | C | N |
+|---|:-:|:-:|:-:|:-:|:-:|
+| <!-- DA COMPILARE: es. Autenticazione e utenti --> | <!-- AUT --> | | | | |
+| Non funzionali | NFR | | | | |
+| **Totale** | | | | | |
+
+---
+
+## <!-- AREA --> · <!-- Nome dell'area -->
+
+| ID | Requisito | Tipo | Origine |
+|---|---|:-:|---|
+| <!-- **REQ-AREA-01** --> | <!-- DA COMPILARE: «Il sistema …», condizioni in grassetto, limiti numerici espliciti --> | N | <!-- committente, AAAA-MM-GG --> |
+
+---
+
+## NFR · Non funzionali
+
+| ID | Requisito | Tipo | Origine |
+|---|---|:-:|---|
+| <!-- **REQ-NFR-01** --> | <!-- DA COMPILARE: prestazioni, disponibilità, sicurezza, conservazione dei dati — sempre con un numero --> | N | |
+
+---
+
+## Difetti noti
+
+Difetti del sistema esistente, o emersi durante il progetto, che un requisito di tipo **C** corregge.
+
+| ID | Difetto | Effetto osservato | Requisito |
+|---|---|---|---|
+| <!-- **DIF-01** --> | | | `REQ-…` |
@@ -0,0 +1,52 @@
+# VISION — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}** · Stato: **in stesura**
+
+---
+
+## 1. La frase che guida il prodotto
+
+> <!-- DA COMPILARE: una frase sola, quella con cui si decide cosa entra e cosa no. -->
+
+## 2. Il problema
+
+<!-- DA COMPILARE: chi ha il problema, come lo risolve oggi, quanto costa (tempo, errori, denaro).
+Preferire un dato misurato a un aggettivo. -->
+
+## 3. Cosa fa il prodotto
+
+<!-- DA COMPILARE: il flusso principale in 5-7 passi, dal punto di vista di chi lo usa. -->
+
+## 4. Perché adesso
+
+<!-- DA COMPILARE: cosa rende necessario il progetto ora (scadenza, cliente, limite del sistema attuale). -->
+
+## 5. Cosa NON cambia
+
+<!-- DA COMPILARE: vincoli fissi (sistemi esistenti, interfacce, abitudini degli utenti), oppure «non applicabile». -->
+
+## 6. Perimetro
+
+### Dentro il perimetro (primo rilascio)
+
+- <!-- DA COMPILARE -->
+
+### Fuori dal perimetro (esplicitamente)
+
+- <!-- DA COMPILARE: ciò che qualcuno potrebbe aspettarsi e che NON si fa. Scriverlo evita discussioni dopo. -->
+
+## 7. Come si misura il successo
+
+| Indicatore | Valore attuale | Obiettivo |
+|---|:-:|:-:|
+| <!-- DA COMPILARE --> | | |
+
+## 8. Rischi principali
+
+| Rischio | Probabilità | Impatto | Contromisura |
+|---|:-:|:-:|---|
+| <!-- DA COMPILARE --> | | | |
+
+## 9. Documenti collegati
+
+[`REQUIREMENTS.md`](REQUIREMENTS.md) · [`PERSONAS_CASI_USO.md`](PERSONAS_CASI_USO.md) · [`../08-project/DECISIONS.md`](../08-project/DECISIONS.md)
@@ -0,0 +1,52 @@
+# ARCHITECTURE — {{PROGETTO}}
+
+Ultimo aggiornamento: **{{DATA}}** · Stato: **in stesura**
+
+---
+
+## 1. Vista d'insieme
+
+```
+<!-- DA COMPILARE: schema ASCII dei servizi e delle frecce principali -->
+```
+
+## 2. Servizi
+
+| Servizio | Tecnologia | Responsabilità | Non fa |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | |
+
+<!-- Per ogni scelta non ovvia («perché due servizi e non uno») una sottosezione breve che
+rimanda alla D-xxx. -->
+
+## 3. Flusso principale
+
+<!-- DA COMPILARE: il caso d'uso UC-01 attraverso i servizi, passo per passo, con le code e i dati scambiati. -->
+
+## 4. Code e lavori asincroni
+
+| Coda / lavoro | Produttore | Consumatore | Tentativi | Cosa succede se fallisce |
+|---|---|---|:-:|---|
+| <!-- DA COMPILARE o «non applicabile» --> | | | | |
+
+## 5. Configurazione
+
+<!-- DA COMPILARE: cosa è variabile d'ambiente, cosa è configurazione a caldo, cosa è segreto. -->
+
+## 6. Multi-tenancy e isolamento
+
+<!-- DA COMPILARE o «non applicabile». -->
+
+## 7. Integrazioni esterne
+
+| Sistema | Direzione | Protocollo | Contratto |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | |
+
+## 8. Ambienti
+
+Vedi [`../06-devops/ENVIRONMENTS.md`](../06-devops/ENVIRONMENTS.md).
+
+## 9. Documenti collegati
+
+[`C4_MODEL.md`](C4_MODEL.md) · [`DATA_MODEL.md`](DATA_MODEL.md) · [`DOMAIN_WORKFLOW.md`](DOMAIN_WORKFLOW.md) · [`SECURITY.md`](SECURITY.md)
@@ -0,0 +1,35 @@
+# C4 MODEL — Contesto, Contenitori, Componenti
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## Livello 1 · Contesto
+
+```
+<!-- DA COMPILARE: il sistema al centro, attori e sistemi esterni intorno -->
+```
+
+| Attore / sistema esterno | Relazione con {{PROGETTO}} |
+|---|---|
+| <!-- DA COMPILARE --> | |
+
+## Livello 2 · Contenitori
+
+| Contenitore | Tecnologia | Parla con | Porta / protocollo |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | |
+
+## Livello 3 · Componenti
+
+### 3.1 <!-- Contenitore -->
+
+| Componente | Responsabilità | Spec |
+|---|---|---|
+| <!-- DA COMPILARE --> | | `SPEC-…` |
+
+## 4. Corrispondenza fra i livelli e i requisiti
+
+| Componente | Requisiti |
+|---|---|
+| <!-- DA COMPILARE --> | `REQ-…` |
@@ -0,0 +1,42 @@
+# DATA MODEL — Entità, relazioni, invarianti
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Modello **logico**. Lo schema fisico (tipi, indici, migrazioni) è in
+[`../05-data/DATABASE.md`](../05-data/DATABASE.md).
+
+---
+
+## 1. Mappa delle entità
+
+```
+<!-- DA COMPILARE: entità e cardinalità, es. Tenant 1──* Utente -->
+```
+
+## 2. Entità
+
+### 2.1 <!-- Entità -->
+
+| Attributo | Significato | Obbligatorio | Note |
+|---|---|:-:|---|
+| <!-- DA COMPILARE --> | | | |
+
+**Ciclo di vita:** <!-- chi la crea, chi la modifica, quando si cancella -->
+
+## 3. Chiavi naturali e univocità
+
+| Entità | Univoca per |
+|---|---|
+| <!-- DA COMPILARE --> | |
+
+## 4. Cancellazioni
+
+| Entità | Cancellazione | Effetto sui figli |
+|---|---|---|
+| <!-- DA COMPILARE: fisica, logica (soft delete), vietata --> | | |
+
+## 5. Invarianti del modello
+
+| # | Invariante |
+|:-:|---|
+| M1 | <!-- DA COMPILARE --> |
@@ -0,0 +1,35 @@
+# DOMAIN WORKFLOW — Stati, transizioni, invarianti
+
+Ultimo aggiornamento: **{{DATA}}**
+
+<!-- Se il dominio non ha un ciclo di vita con stati, scrivere «non applicabile» e il perché. -->
+
+---
+
+## 1. Stati
+
+| Stato | Significato | Terminale |
+|---|---|:-:|
+| <!-- DA COMPILARE --> | | |
+
+## 2. Macchina a stati
+
+```
+<!-- DA COMPILARE: diagramma ASCII degli stati -->
+```
+
+## 3. Transizioni ammesse
+
+Qualsiasi transizione non elencata qui è **rifiutata**.
+
+| # | Da | A | Attore | Condizione | Effetti collaterali |
+|:-:|---|---|---|---|---|
+| T1 | | | | | |
+
+## 4. Invarianti
+
+Condizioni che devono essere vere **sempre**, verificate da test.
+
+| # | Invariante |
+|:-:|---|
+| I1 | <!-- DA COMPILARE --> |
@@ -0,0 +1,44 @@
+# SECURITY — Modello di sicurezza
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Perimetro
+
+<!-- DA COMPILARE: cosa è esposto a Internet, cosa resta interno. -->
+
+## 2. Autenticazione
+
+<!-- DA COMPILARE: meccanismo, durata dei token, rotte pubbliche (elenco chiuso: aggiungerne una richiede una D-xxx). -->
+
+## 3. Autorizzazione
+
+| Ruolo | Può | Non può |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+Regola: nessuno crea un utente più potente di sé.
+
+## 4. Segreti
+
+- I segreti non entrano mai nel repository, nei log o nella documentazione.
+- <!-- DA COMPILARE: dove vivono (variabili d'ambiente, secret manager, cifrati a riposo). -->
+
+## 5. Dati in ingresso e in uscita
+
+<!-- DA COMPILARE: validazione, dimensioni massime, dati personali, cosa esce verso terzi. -->
+
+## 6. Audit
+
+<!-- DA COMPILARE: quali eventi si registrano, dove, per quanto tempo. -->
+
+## 7. Minacce e contromisure
+
+| Minaccia | Contromisura | Verificata da |
+|---|---|---|
+| <!-- DA COMPILARE --> | | test / `REQ-…` |
+
+## 8. Cosa resta aperto
+
+<!-- DA COMPILARE -->
@@ -0,0 +1,59 @@
+# API — Catalogo e convenzioni
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Il contratto è [`openapi.yaml`](openapi.yaml), **fonte di verità**: in caso di differenza fra
+questo documento, il codice e il contratto, vale il contratto. Si scrive il contratto **prima**
+del codice (contract-first).
+
+---
+
+## 1. Convenzioni
+
+| Aspetto | Regola |
+|---|---|
+| Prefisso | `/api/v1` |
+| Formato | JSON, UTF-8, date ISO 8601 in UTC |
+| Nomi | <!-- DA COMPILARE: snake_case o camelCase, una sola scelta --> |
+| Autenticazione | <!-- DA COMPILARE --> |
+
+## 2. Errori
+
+Forma unica per tutti gli errori:
+
+```json
+{ "error": { "code": "stringa_stabile", "message": "testo leggibile", "details": {} } }
+```
+
+| Codice HTTP | Quando |
+|:-:|---|
+| 400 | Richiesta malformata |
+| 401 | Non autenticato |
+| 403 | Autenticato ma non autorizzato |
+| 404 | Risorsa inesistente **o di un altro tenant** (non si rivela l'esistenza) |
+| 409 | Conflitto (duplicato, stato non compatibile) |
+| 422 | Validazione fallita |
+
+## 3. Paginazione
+
+<!-- DA COMPILARE: parametri (page/size o cursore), limiti massimi, forma della risposta. -->
+
+## 4. Catalogo
+
+### <!-- Gruppo --> — `SPEC-…`
+
+| Metodo | Percorso | Ruolo minimo | Descrizione |
+|---|---|---|---|
+| <!-- DA COMPILARE --> | | | |
+
+## 5. API interne — non esposte
+
+<!-- DA COMPILARE o «nessuna». -->
+
+## 6. Idempotenza e concorrenza
+
+<!-- DA COMPILARE: chiavi di idempotenza, controllo delle versioni, comportamento in caso di doppio invio. -->
+
+## 7. Limiti
+
+<!-- DA COMPILARE: rate limit, dimensioni massime dei corpi e dei file. -->
@@ -0,0 +1,54 @@
+# Contratto pubblico di {{PROGETTO}} — FONTE DI VERITÀ (D-002).
+# Si modifica PRIMA del codice. Ogni operazione cita la spec che la definisce.
+openapi: 3.1.0
+info:
+  title: "{{PROGETTO}} API"
+  version: 0.1.0
+  description: |
+    Contratto dell'API di {{PROGETTO}}.
+    Documentazione redatta con il metodo spec-driven di STS Lab Srl.
+servers:
+  - url: /api/v1
+tags:
+  - name: health
+    description: Stato del servizio
+paths:
+  /health:
+    get:
+      tags: [health]
+      summary: Stato del servizio
+      security: []
+      responses:
+        "200":
+          description: Servizio attivo
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            details:
+              type: object
+security:
+  - BearerAuth: []
@@ -0,0 +1,47 @@
+# DATABASE — Schema fisico
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Traduzione fisica di [`../02-architecture/DATA_MODEL.md`](../02-architecture/DATA_MODEL.md).
+
+---
+
+## 1. Convenzioni
+
+| Aspetto | Regola |
+|---|---|
+| Motore | <!-- DA COMPILARE: es. PostgreSQL 16 --> |
+| Nomi | tabelle al singolare, `snake_case` |
+| Chiavi primarie | <!-- DA COMPILARE: UUID / bigint --> |
+| Date | `timestamptz`, sempre UTC |
+| Multi-tenancy | <!-- DA COMPILARE: colonna `tenant_id` su ogni tabella di dominio, o «non applicabile» --> |
+
+## 2. Tipi enumerati
+
+| Tipo | Valori |
+|---|---|
+| <!-- DA COMPILARE --> | |
+
+## 3. Tabelle
+
+### `<!-- tabella -->`
+
+| Colonna | Tipo | Null | Default | Note |
+|---|---|:-:|---|---|
+| `id` | | no | | PK |
+
+Indici: <!-- DA COMPILARE --> · Vincoli: <!-- DA COMPILARE -->
+
+## 4. Vincoli che riflettono requisiti
+
+| Vincolo | Requisito |
+|---|---|
+| <!-- DA COMPILARE --> | `REQ-…` |
+
+## 5. Migrazioni
+
+<!-- DA COMPILARE: strumento (es. Alembic), regola «una migrazione per modifica, mai riscrivere una migrazione già applicata». -->
+
+## 6. Dimensionamento
+
+<!-- DA COMPILARE: volumi attesi per tabella a 1 e 3 anni. -->
@@ -0,0 +1,30 @@
+# SEED E BOOTSTRAP — Stato iniziale del sistema
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Principio
+
+Il bootstrap è **idempotente**: eseguirlo due volte produce lo stesso stato di eseguirlo una.
+
+## 2. Cosa viene creato
+
+| Elemento | Quando | Origine dei valori |
+|---|---|---|
+| <!-- DA COMPILARE: utente amministratore iniziale, configurazione di base --> | primo avvio | variabili d'ambiente |
+
+## 3. Credenziali iniziali
+
+In collaudo e produzione l'avvio **fallisce** se le credenziali di bootstrap sono lasciate ai
+valori predefiniti.
+
+## 4. Variabili di bootstrap
+
+| Variabile | Obbligatoria | Significato |
+|---|:-:|---|
+| <!-- DA COMPILARE --> | | |
+
+## 5. Dati di prova per lo sviluppo
+
+<!-- DA COMPILARE: come si generano, e la regola che non arrivano mai in produzione. -->
@@ -0,0 +1,34 @@
+# BACKUP E RIPRISTINO
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Cosa va salvato
+
+| Dato | Dove vive | Ricostruibile | Backup |
+|---|---|:-:|---|
+| <!-- DA COMPILARE --> | | | |
+
+## 2. Obiettivi
+
+| Obiettivo | Valore |
+|---|---|
+| RPO (dati che si accetta di perdere) | <!-- DA COMPILARE --> |
+| RTO (tempo per tornare operativi) | <!-- DA COMPILARE --> |
+
+## 3. Procedura di ripristino
+
+1. <!-- DA COMPILARE -->
+
+## 4. Verifiche dopo un ripristino
+
+- [ ] <!-- DA COMPILARE -->
+
+## 5. Prova di ripristino
+
+Un backup mai ripristinato non è un backup. Prova <!-- DA COMPILARE: frequenza -->, esito registrato in `DEVELOPMENT_LOG`.
+
+## 6. Cosa non è coperto
+
+<!-- DA COMPILARE -->
@@ -0,0 +1,31 @@
+# CI/CD — Integrazione e rilascio
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Flussi
+
+| Flusso | Innesco | Ambiente di destinazione |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+## 2. Sequenza
+
+1. <!-- DA COMPILARE: build, test, analisi, immagini, deploy -->
+
+## 3. Verifiche in pipeline
+
+| Verifica | Perché | Blocca il rilascio |
+|---|---|:-:|
+| Test automatici | criteri di accettazione delle spec | sì |
+| Ricerca di segreti | nessun segreto nel repository | sì |
+| Contratto contro implementazione | il codice rispetta `openapi.yaml` | sì |
+
+## 4. Segreti della pipeline
+
+<!-- DA COMPILARE -->
+
+## 5. Rilascio in produzione e rientro
+
+<!-- DA COMPILARE: chi approva, come si torna alla versione precedente, in quanto tempo. -->
@@ -0,0 +1,31 @@
+# ENVIRONMENTS — Sviluppo, collaudo, produzione
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Gli ambienti
+
+| Ambiente | Scopo | Dati | Chi vi accede |
+|---|---|---|---|
+| dev | sviluppo | di prova | sviluppatori |
+| qa | collaudo | di prova, realistici | sviluppatori, committente |
+| prod | esercizio | reali | utenti |
+
+## 2. Variabili di configurazione
+
+| Variabile | Significato | dev | qa | prod | Segreta |
+|---|---|---|---|---|:-:|
+| <!-- DA COMPILARE --> | | | | | |
+
+## 3. Ambiente locale di sviluppo
+
+<!-- DA COMPILARE: comandi per avviare tutto in locale (es. docker compose up). -->
+
+## 4. Promozione fra ambienti
+
+<!-- DA COMPILARE: dev → qa → prod, chi approva, cosa si verifica a ogni passo. -->
+
+## 5. Prima di dichiarare un ambiente pronto
+
+- [ ] <!-- DA COMPILARE -->
@@ -0,0 +1,31 @@
+# INFRASTRUCTURE — Topologia e risorse
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Topologia
+
+```
+<!-- DA COMPILARE: nodi, servizi, rete -->
+```
+
+## 2. Servizi e risorse
+
+| Servizio | Immagine / runtime | Repliche | CPU | Memoria |
+|---|---|:-:|---|---|
+| <!-- DA COMPILARE --> | | | | |
+
+## 3. Persistenza
+
+| Volume / storage | Contenuto | Dimensione | Backup |
+|---|---|---|:-:|
+| <!-- DA COMPILARE --> | | | |
+
+## 4. Rete, nomi e certificati
+
+<!-- DA COMPILARE: domini, ingress, TLS, porte esposte. -->
+
+## 5. Capacità e crescita
+
+<!-- DA COMPILARE -->
@@ -0,0 +1,37 @@
+# OBSERVABILITY — Log, metriche, allarmi
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Il problema che risolve
+
+<!-- DA COMPILARE: quali domande operative si devono poter rispondere senza aprire il database. -->
+
+## 2. Log
+
+| Aspetto | Regola |
+|---|---|
+| Formato | JSON strutturato |
+| Correlazione | un identificativo di richiesta propagato fra i servizi |
+| Mai nei log | password, token, segreti, dati personali non necessari |
+
+## 3. Metriche
+
+| Metrica | Tipo | Significato |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+## 4. Allarmi
+
+| Allarme | Condizione | Gravità | Procedura |
+|---|---|:-:|---|
+| <!-- DA COMPILARE --> | | | [`RUNBOOK`](RUNBOOK.md) §… |
+
+## 5. Salute
+
+`GET /health` — <!-- DA COMPILARE: cosa verifica. -->
+
+## 6. Conservazione
+
+<!-- DA COMPILARE -->
@@ -0,0 +1,25 @@
+# RUNBOOK — Procedure operative
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Ogni procedura segue lo stesso schema: **sintomo → verifica → azione → conferma**.
+
+---
+
+## 1. <!-- Sintomo, come lo descriverebbe chi lo nota -->
+
+| Passo | Cosa fare |
+|---|---|
+| **Verifica** | <!-- comando o schermata --> |
+| **Azione** | |
+| **Conferma** | |
+
+## 2. Ripristino da backup
+
+Vedi [`BACKUP_DR.md`](BACKUP_DR.md) §… .
+
+## 3. Contatti e riferimenti
+
+| Ruolo | Contatto |
+|---|---|
+| <!-- DA COMPILARE --> | |
@@ -0,0 +1,35 @@
+# ACCEPTANCE CRITERIA — Criteri di rilascio
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Riepilogo per specifica
+
+| Spec | Criteri | Verificati | Stato |
+|---|:-:|:-:|:-:|
+| <!-- SPEC-001 --> | | | ⬜ |
+
+## 2. Criteri di rilascio — versione <!-- x.y.z -->
+
+### 2.1 Bloccanti
+
+| # | Criterio | Verificato da |
+|:-:|---|---|
+| R1 | Tutti i test passano in pipeline | CI |
+| R2 | Nessuna riga scoperta in `TRACEABILITY.md` | revisione |
+| R3 | <!-- DA COMPILARE --> | |
+
+### 2.2 Attesi (non bloccanti)
+
+| # | Criterio |
+|:-:|---|
+| <!-- DA COMPILARE --> | |
+
+## 3. Verifica funzionale prima del rilascio
+
+- [ ] <!-- DA COMPILARE: percorsi da provare a mano con il committente -->
+
+## 4. Cosa non è criterio di rilascio
+
+<!-- DA COMPILARE -->
@@ -0,0 +1,38 @@
+# TEST STRATEGY
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 1. Il criterio
+
+Ogni criterio di accettazione di ogni spec ha **almeno un test eseguito**. Lo stato di un
+requisito in [`TRACEABILITY.md`](TRACEABILITY.md) diventa ✅ quando il test passa, non quando
+il codice è scritto. Ogni difetto `DIF-nn` ha un test che lo riproduce.
+
+## 2. Livelli
+
+| Livello | Cosa verifica | Strumento | Dove |
+|---|---|---|---|
+| Unitario | funzioni pure, regole di business | <!-- DA COMPILARE --> | |
+| Integrazione | servizi + database + code, con simulatori dei sistemi esterni | | |
+| Contratto | implementazione contro `openapi.yaml` | | |
+| End-to-end | casi d'uso dall'interfaccia | | |
+
+## 3. Simulatori dei sistemi esterni
+
+| Sistema | Simulatore | Comportamenti simulati (anche i guasti) |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
+
+## 4. Nominare i test
+
+Il nome del test cita il criterio: `test_D3_sufficiente_urgente_ricorrente_lotto_grande_priorita_1`.
+
+## 5. Esecuzione
+
+<!-- DA COMPILARE: comandi, durata attesa, numero di test (aggiornato in DEVELOPMENT_LOG). -->
+
+## 6. Cosa non verifichiamo
+
+<!-- DA COMPILARE, con il perché. -->
@@ -0,0 +1,48 @@
+# TRACEABILITY — Matrice REQ → SPEC → T → test
+
+Ultimo aggiornamento: **{{DATA}}** · Stato: **in stesura**
+
+---
+
+## 1. Regola
+
+> **Nessuna riga vuota.** Ogni requisito ha una specifica, ogni specifica ha task, ogni task ha
+> test. Un requisito senza spec non è implementabile; un task senza spec non entra in lavorazione.
+
+La colonna *Stato* si compila durante l'implementazione: ⬜ da fare · 🟡 in corso · ✅ verificato.
+Lo stato si aggiorna **quando il test passa, non quando il codice è scritto**.
+
+---
+
+## 2. Copertura
+
+| Area | REQ | Spec | Task | Criteri | Copertura |
+|---|:-:|---|---|:-:|:-:|
+| <!-- DA COMPILARE --> | | | | | ⬜ |
+| **Totale** | | | | | |
+
+---
+
+## 3. Matrice per requisito
+
+### <!-- AREA --> · <!-- Nome -->
+
+| REQ | Spec | Task | Criteri | Stato |
+|---|---|---|---|:-:|
+| <!-- AREA-01 --> | <!-- SPEC-001 §2 --> | <!-- T-010 --> | <!-- A1 --> | ⬜ |
+
+---
+
+## 4. Decisioni → specifiche
+
+| Decisione | Dove si applica | Task |
+|---|---|---|
+| D-002 | metodo | — |
+
+---
+
+## 5. Difetti → test
+
+| Difetto | Requisito | Test |
+|---|---|---|
+| <!-- DIF-01 --> | | |
@@ -0,0 +1,14 @@
+# CHANGELOG
+
+Formato: [Keep a Changelog](https://keepachangelog.com/it/1.1.0/) · Versionamento semantico.
+
+Le voci descrivono ciò che cambia **per chi usa il prodotto**. Le decisioni tecniche stanno in
+[`DECISIONS.md`](DECISIONS.md), il diario di lavoro in [`DEVELOPMENT_LOG.md`](DEVELOPMENT_LOG.md).
+
+---
+
+## [Non rilasciato] — 0.1.0
+
+### Aggiunto
+
+- Documentazione di progetto con metodo spec-driven ({{DATA}}).
@@ -0,0 +1,83 @@
+# DECISIONS — Registro delle decisioni architetturali (ADR)
+
+Ultimo aggiornamento: **{{DATA}}** · Progetto: **{{PROGETTO}}**
+
+Ogni decisione strutturale del progetto è registrata qui con un identificativo `D-xxx` immutabile.
+Le decisioni si **superano**, non si cancellano: una decisione sbagliata resta a registro con stato
+*Superata da D-yyy*, così la storia del progetto resta leggibile.
+
+**Stati:** `Proposta` · `Accettata` · `Superata da D-xxx` · `Respinta`
+
+**Formato:** Contesto → Decisione → Alternative valutate → Conseguenze.
+
+---
+
+## Indice
+
+| ID | Titolo | Stato | Data |
+|---|---|---|---|
+| [D-001](#d-001--stack-tecnologico) | Stack tecnologico | Proposta | {{DATA}} |
+| [D-002](#d-002--sviluppo-spec-driven-vincolante) | Sviluppo spec-driven vincolante | Accettata | {{DATA}} |
+| [D-003](#d-003--la-documentazione-vive-nel-repository) | La documentazione vive nel repository | Accettata | {{DATA}} |
+
+---
+
+## D-001 — Stack tecnologico
+
+**Stato:** Proposta · {{DATA}}
+
+### Contesto
+<!-- DA COMPILARE: vincoli del committente, competenze, sistemi esistenti con cui integrarsi. -->
+
+### Decisione
+<!-- DA COMPILARE: linguaggi, framework, database, code, storage, deploy. -->
+
+### Alternative valutate
+- <!-- DA COMPILARE: alternativa — perché scartata. -->
+
+### Conseguenze
+- <!-- DA COMPILARE -->
+
+---
+
+## D-002 — Sviluppo spec-driven vincolante
+
+**Stato:** Accettata · {{DATA}}
+
+### Contesto
+Le regole di business scritte solo nel codice emergono dal debugging invece che dalla
+specifica, e si scoprono quando un difetto le rivela.
+
+### Decisione
+Nessuna implementazione senza una `SPEC-xxx` in stato *Approvata*. Ogni spec contiene: contesto,
+requisiti coperti (`REQ-xxx`), contratto API, modello dati, regole, casi di errore, criteri di
+accettazione, task derivati (`T-xxx`). `07-quality/TRACEABILITY.md` mantiene la matrice
+REQ → SPEC → T → test e non deve avere righe vuote. Il contratto API (`04-api/openapi.yaml`) è
+la fonte di verità e si scrive prima del codice.
+
+### Alternative valutate
+- **Documentazione a valle del codice.** Produce documenti veri ma tardivi; le regole restano
+  scoperte finché un bug non le rivela.
+
+### Conseguenze
+- La fase di documentazione precede quella di codice; il codice inizia più tardi e procede più dritto.
+- Una spec approvata si modifica solo con una nuova `D-xxx` o una revisione tracciata.
+
+---
+
+## D-003 — La documentazione vive nel repository
+
+**Stato:** Accettata · {{DATA}}
+
+### Contesto
+Documentazione e codice divergono quando vivono in luoghi diversi.
+
+### Decisione
+`docs/` sta nel repository del codice e si aggiorna **nella stessa modifica** del codice che la
+riguarda.
+
+### Alternative valutate
+- **Wiki esterno.** Più comodo da modificare, ma non versionato con il codice.
+
+### Conseguenze
+- Una revisione del codice è anche revisione della documentazione.
@@ -0,0 +1,14 @@
+# DEVELOPMENT LOG — Diario tecnico
+
+Diario in ordine cronologico inverso. Registra **cosa si è scoperto e perché si è deciso così**,
+non l'elenco delle modifiche (quello è in [`CHANGELOG.md`](CHANGELOG.md)). Le voci non si
+cancellano: si annotano.
+
+Formato del titolo: `## AAAA-MM-GG (n) · titolo che dice cosa si è capito`
+
+---
+
+## {{DATA}} · Nasce la documentazione
+
+Creato lo scheletro della documentazione spec-driven. Decisioni iniziali: `D-001` (stack,
+proposta), `D-002` (metodo spec-driven), `D-003` (documentazione nel repository).
@@ -0,0 +1,43 @@
+# PROJECT MEMORY — Memoria permanente
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Da leggere **all'inizio di ogni sessione di lavoro** sul progetto. Contiene ciò che non è
+deducibile dal codice e che, se dimenticato, fa ripetere errori già commessi. Non è un
+riassunto della documentazione: ogni voce qui deve avere un perché.
+
+---
+
+## 1. In una frase
+
+<!-- DA COMPILARE -->
+
+---
+
+## 2. Le cose da non dimenticare mai
+
+<!-- Una sottosezione per vincolo. Ogni vincolo dice: la regola, perché esiste (meglio se con
+un fatto osservato e la data), la decisione D-xxx che la fissa. -->
+
+### 2.1 <!-- vincolo -->
+
+---
+
+## 3. Azioni pendenti fuori sequenza
+
+<!-- DA COMPILARE o «nessuna». Es. credenziali da ruotare. -->
+
+---
+
+## 4. Metodo
+
+Spec-driven **vincolante** (D-002): `REQ → SPEC → T → codice + test → TRACEABILITY`.
+Si implementa solo da una spec *Approvata*.
+
+---
+
+## 5. Come riprendere il lavoro
+
+1. Leggere questo file e [`../00-INDEX.md`](../00-INDEX.md) (riquadri delle novità in testa).
+2. Aprire [`TODO.md`](TODO.md): fuori sequenza, poi la fase corrente.
+3. Per il task scelto: la sua spec, i `REQ` e le `D-xxx` citate.
@@ -0,0 +1,45 @@
+# ROADMAP
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 0. Fuori sequenza — da fare subito
+
+| # | Azione | Perché ora |
+|:-:|---|---|
+| <!-- DA COMPILARE o «nessuna» --> | | |
+
+## 1. Fasi
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ FASE 0 · Documentazione                                            │
+│   visione · requisiti · architettura · spec · contratto · dati     │
+│   ▸ criterio di uscita: spec della fase 1 approvate                │
+└────────────────────────────────────────────────────────────────────┘
+                              ▼
+┌────────────────────────────────────────────────────────────────────┐
+│ FASE 1 · Fondamenta                                                │
+│   <!-- DA COMPILARE -->                                            │
+│   ▸ criterio di uscita: <!-- DA COMPILARE -->                      │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. Dettaglio
+
+### Fase 1 · Fondamenta
+
+| Spec | Task | Criterio di uscita |
+|---|---|---|
+| <!-- SPEC-001 --> | <!-- T-010…019 --> | |
+
+## 3. Dipendenze critiche
+
+<!-- DA COMPILARE -->
+
+## 4. Rischi
+
+| Rischio | Fase | Contromisura |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
@@ -0,0 +1,39 @@
+# TODO — Backlog
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Stato: ⬜ da fare · 🟡 in corso · ✅ fatto · ⏸ sospeso
+
+**Regola:** un task entra in lavorazione solo se la sua specifica è approvata (D-002). Al termine
+si aggiorna [`TRACEABILITY.md`](../07-quality/TRACEABILITY.md) — quando il test passa, non quando
+il codice è scritto.
+
+**Numerazione:** i task di `SPEC-nnn` usano il blocco `T-nnn0…T-nnn9` (la spec 4 usa i task da
+40 a 49); oltre il nono si aggiunge un suffisso (`b`, `c`). I task fuori sequenza usano i numeri
+da 1 a 9.
+
+---
+
+## 🔴 Fuori sequenza — prima di tutto
+
+| ID | Task | Stato |
+|---|---|:-:|
+| <!-- T-001 --> | | ⬜ |
+
+---
+
+## Fase 0 · Documentazione
+
+| ID | Task | Spec | Stato |
+|---|---|---|:-:|
+| — | Visione, glossario, casi d'uso, requisiti | — | 🟡 |
+| — | Architettura, modello dati, sicurezza | — | ⬜ |
+| — | Specifiche della fase 1 approvate | — | ⬜ |
+
+---
+
+## Fase 1 · Fondamenta
+
+| ID | Task | Spec | Stato |
+|---|---|---|:-:|
+| <!-- T-010 --> | | <!-- SPEC-001 --> | ⬜ |