docs: API complète + évolutivité schéma Alembic

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

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