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,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: []