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,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 |