# {{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>