92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# Layout della documentazione — STS Lab Srl
|
||
|
||
Due forme ricorrenti nei progetti STS Lab Srl. La skill deve funzionare con entrambe e con
|
||
varianti intermedie. Per un progetto nuovo l'utente sceglie quale creare: i modelli sono in
|
||
`templates/strutturato/` e `templates/piatto/` (vedi [scrittura.md](scrittura.md)).
|
||
|
||
---
|
||
|
||
## A. Layout strutturato (es. `KadeonCad_v2/docs`)
|
||
|
||
```
|
||
docs/
|
||
├── 00-INDEX.md mappa, stato degli step, novità recenti in riquadri datati
|
||
├── 01-product/ COSA e PER CHI
|
||
│ ├── VISION.md perché esiste, perimetro, non-obiettivi
|
||
│ ├── GLOSSARY.md lessico condiviso (usare gli stessi termini nel codice)
|
||
│ ├── PERSONAS_CASI_USO.md attori e casi d'uso end-to-end
|
||
│ └── REQUIREMENTS.md REQ-<AREA>-<nn> + DIF-<nn> (difetti noti)
|
||
├── 02-architecture/ COME È FATTO
|
||
│ ├── ARCHITECTURE.md · C4_MODEL.md · DOMAIN_WORKFLOW.md (macchina a stati, invarianti)
|
||
│ ├── DATA_MODEL.md (entità, relazioni, invarianti) · SECURITY.md · STORAGE.md
|
||
│ └── <componente>.md (AI_GATEWAY, MESH_ENGINE, …)
|
||
├── 03-specs/ CONTRATTO PER L'IMPLEMENTAZIONE
|
||
│ └── SPEC-<nnn>-<slug>.md
|
||
├── 04-api/ CONTRATTO ESTERNO
|
||
│ ├── openapi.yaml FONTE DI VERITÀ dell'API
|
||
│ └── API.md · WEBHOOKS.md · INTEGRATION_*.md
|
||
├── 05-data/ DATABASE.md (schema fisico) · MIGRATION_*.md · SEED_BOOTSTRAP.md
|
||
├── 06-devops/ INFRASTRUCTURE · KUBERNETES · CI_CD · ENVIRONMENTS · OBSERVABILITY · RUNBOOK · BACKUP_DR
|
||
├── 07-quality/ TEST_STRATEGY · ACCEPTANCE_CRITERIA · TRACEABILITY · liste di parità
|
||
└── 08-project/ DECISIONS · ROADMAP · TODO · CHANGELOG · DEVELOPMENT_LOG · PROJECT_MEMORY
|
||
```
|
||
|
||
**Dove cercare cosa**
|
||
|
||
| Domanda | Documento |
|
||
|---|---|
|
||
| Cosa deve fare il prodotto? | `01-product/REQUIREMENTS.md` |
|
||
| Come deve farlo questa funzione? | `03-specs/SPEC-xxx` |
|
||
| Che forma ha la rotta? | `04-api/openapi.yaml` (poi API.md per le convenzioni) |
|
||
| Che colonne/vincoli ha la tabella? | `05-data/DATABASE.md`; entità logiche in `02-architecture/DATA_MODEL.md` |
|
||
| Transizioni di stato ammesse? | `02-architecture/DOMAIN_WORKFLOW.md` |
|
||
| Perché è così? | `08-project/DECISIONS.md` (`## D-xxx`), poi `DEVELOPMENT_LOG.md` |
|
||
| È fatto? È verificato? | `08-project/TODO.md`, `07-quality/TRACEABILITY.md` |
|
||
| Come si rilascia / variabili d'ambiente? | `06-devops/ENVIRONMENTS.md`, `KUBERNETES.md` |
|
||
|
||
**Legenda stati usata:** ⬜ da scrivere/fare · 🟡 in corso/parziale · ✅ completo/verificato ·
|
||
🔒 congelato (modifica solo con nuova D-xxx) · ⏸ sospeso.
|
||
|
||
---
|
||
|
||
## B. Layout piatto (es. `Kadeon/kadeon/src/docs`)
|
||
|
||
```
|
||
docs/
|
||
├── PROJECT_MEMORY.md «leggere sempre prima di scrivere codice»; sintesi architettura,
|
||
│ decisioni, componenti già creati, sessioni
|
||
├── ARCHITECTURE.md · API.md · DATABASE.md · AI_GATEWAY.md · OUTPUT_SCHEMA.md
|
||
├── <MODULO>.md proposta/specifica di un modulo (es. CAD_MODULE.md)
|
||
├── <area>/DESIGN.md proposte con opzioni e «domande ancora aperte» (es. whatsapp/)
|
||
├── <area>/openapi.yaml contratto del modulo
|
||
├── DECISIONS.md D-xxx con Stato · Contesto · Opzioni · Scelta · Motivazione
|
||
├── TODO.md T-<lettera><nn> raggruppati per tema, con Prio (P0–P3) e Stato
|
||
├── CHANGELOG.md · DEVELOPMENT_LOG.md
|
||
```
|
||
|
||
Differenze da tenere presenti:
|
||
|
||
- Non ci sono `REQ-`/`SPEC-`: il ruolo della spec lo svolge il **documento di modulo** o la
|
||
sezione di PROJECT_MEMORY/ARCHITECTURE; il cancello §3 si applica a quello.
|
||
- Gli ID dei task hanno un prefisso tematico (`T-S01` sicurezza, `T-Q5`, `T-H01`…).
|
||
- Stati in inglese: `pending` · `in_progress` · `done` · `blocked`; decisioni `accepted` ·
|
||
`proposed` · `superseded`.
|
||
- Un `DESIGN.md` con «Domande ancora aperte» **non è approvato**: chiarire con l'utente.
|
||
- PROJECT_MEMORY può essere lungo e datato: confronta la sua data con quelle di TODO e
|
||
DECISIONS.
|
||
|
||
---
|
||
|
||
## C. Formati degli ID
|
||
|
||
| ID | Forma | Dove nasce | Note |
|
||
|---|---|---|---|
|
||
| Requisito | `REQ-<AREA>-<nn>` (AREA 2–5 lettere) | REQUIREMENTS | Tipo **P/C/N**; mai rinumerato |
|
||
| Difetto | `DIF-<nn>` | REQUIREMENTS (sezione difetti) | ogni DIF ha un REQ di tipo C e un test |
|
||
| Specifica | `SPEC-<nnn>` | file `03-specs/SPEC-nnn-slug.md` | riga `Stato:` in testa |
|
||
| Task | `T-<nnn>` o `T-<lettera><nn>`, suffissi `b`, `c` | sezione *Task* della spec e TODO | barrato se chiuso senza lavoro |
|
||
| Decisione | `D-<nnn>` | DECISIONS | *superata*, mai cancellata |
|
||
| Criterio | lettera + numero (`D1`, `P12`, `M18`) | sezione *Criteri* della spec | ⚠ `D1` criterio ≠ `D-001` decisione |
|
||
|
||
<sub>STS Lab Srl · Spec-Driven Reader</sub>
|