From ee0dc2461c2f3f0160c0ec935e68bc7b883214d2 Mon Sep 17 00:00:00 2001
From: Gilles Soulier <gilles@maison43>
Date: Thu, 28 May 2026 19:58:24 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20API=20compl=C3=A8te=20+=20=C3=A9volutiv?=
 =?UTF-8?q?it=C3=A9=20sch=C3=A9ma=20Alembic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Routes read séparées dashboard vs agents IA
- Endpoints /api/ai/* (summary, at-risk, moved-disks, backup-needed)
- Stratégie migrations Alembic (alembic upgrade head au démarrage)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../specs/2026-05-28-inventaire-hdd-design.md | 50 ++++++++++++++++---
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-28-inventaire-hdd-design.md b/docs/superpowers/specs/2026-05-28-inventaire-hdd-design.md
index f4210cf..206d830 100644
--- a/docs/superpowers/specs/2026-05-28-inventaire-hdd-design.md
+++ b/docs/superpowers/specs/2026-05-28-inventaire-hdd-design.md
@@ -207,16 +207,52 @@ Les champs numériques (`temperature_c`, `power_on_hours`, `reallocated_sectors`
 
 ## Backend — FastAPI
 
-### Routes
+### Routes complètes
+
+**Écriture**
 
 | Méthode | Route | Description |
 |---|---|---|
-| `POST` | `/api/ingest` | Reçoit le payload du script client |
-| `GET` | `/api/disks` | Liste tous les disques (dernière observation par serial) |
-| `GET` | `/api/disks/{serial}` | Historique complet d'un disque |
-| `GET` | `/api/machines` | Liste des machines avec last_seen |
-| `GET` | `/api/ai/summary` | Synthèse structurée pour agents IA |
-| `GET` | `/api/ai/at-risk` | Disques avec status warn ou fail |
+| `POST` | `/api/ingest` | Reçoit le payload complet du script client |
+
+**Lecture — Dashboard / frontend**
+
+| Méthode | Route | Description |
+|---|---|---|
+| `GET` | `/api/disks` | Tous les disques — dernière observation par serial |
+| `GET` | `/api/disks/{serial}` | Détail + historique complet d'un disque |
+| `GET` | `/api/machines` | Toutes les machines avec last_seen et nombre de disques |
+| `GET` | `/api/machines/{hostname}` | Détail d'une machine + ses disques courants |
+| `GET` | `/api/machines/{hostname}/disks` | Disques d'une machine (dernière observation) |
+
+**Lecture — Agents IA et apps externes**
+
+| Méthode | Route | Description |
+|---|---|---|
+| `GET` | `/api/ai/summary` | Synthèse globale : machines, disques, statuts SMART, espaces |
+| `GET` | `/api/ai/at-risk` | Disques en `warn` ou `fail` avec détail SMART |
+| `GET` | `/api/ai/moved-disks` | Disques dont `last_seen_host ≠ first_seen_host` |
+| `GET` | `/api/ai/backup-needed` | Disques avec `home_users` non vide, triés par taille décroissante |
+| `GET` | `/api/ai/machines/{hostname}` | Vue complète d'une machine pour agent IA |
+
+Les routes `/api/ai/*` retournent du JSON compact et plat, sans pagination ni enveloppe, optimisé pour consommation LLM.
+
+### Évolutivité du schéma SQLite — Alembic
+
+Le schéma évolue via **Alembic** (migrations versionnées) :
+
+```
+api/
+├── alembic.ini
+├── migrations/
+│   ├── env.py
+│   └── versions/
+│       └── 0001_initial_schema.py
+```
+
+- Chaque ajout de colonne ou de table = une nouvelle migration numérotée
+- Appliquées automatiquement au démarrage du conteneur (`alembic upgrade head`)
+- Permet d'ajouter des champs sans recréer la base ni perdre l'historique
 
 ### Logique d'ingest