homelab_automation/documentation/STORAGE_DETAILS.md

# Stockage Détaillé - Documentation Technique

## Vue d'ensemble

La fonctionnalité "Stockage Détaillé" fournit une vue complète et normalisée des informations de stockage pour tous les hôtes, avec support multi-OS (Linux Alpine/Debian, TrueNAS CORE, TrueNAS SCALE).

## Architecture

### Backend

```
app/
├── models/host_metrics.py      # Colonne storage_details (JSON)
├── schemas/host_metrics.py     # Schéma Pydantic avec storage_details
├── services/builtin_playbooks.py  # Définition du builtin playbook
└── routes/builtin_playbooks.py    # API endpoints

ansible/playbooks/builtin/
└── _builtin_collect_storage_details.yml  # Playbook de collecte
```

### Frontend

```
app/
└── main.js
    ├── renderStorageDetailsSection()  # Rendu de l'accordion
    ├── toggleStorageDetails()         # Toggle accordion
    └── toggleStorageInspector()       # Toggle mode inspecteur
```

## Schéma de Données

### StorageDetails v1

```json
{
  "os_type": "linux-debian|linux-alpine|truenas-core|truenas-scale|linux-generic",
  "status": "ok|partial|error",
  "collected_at": "2025-12-19T10:00:00Z",
  "commands_run": [
    {"cmd": "lsblk", "status": "ok"},
    {"cmd": "df", "status": "ok"}
  ],
  "partial_failures": [],
  "summary": {
    "total_bytes": 500107862016,
    "used_bytes": 125026965504,
    "free_bytes": 349600112640,
    "used_pct": 25.0
  },
  "block_devices": [...],
  "mounts": [...],
  "filesystems": [...],
  "lvm": {
    "pvs": [...],
    "vgs": [...],
    "lvs": [...]
  },
  "zfs": {
    "pools": [...],
    "datasets": [...]
  },
  "feature_flags": {
    "has_lvm": false,
    "has_zfs": false,
    "has_lsblk": true,
    "has_findmnt": true
  }
}
```

## Commandes par OS

### Linux (Alpine/Debian)

| Commande | Description | Fallback |
|----------|-------------|----------|
| `lsblk -J -b -o ...` | Block devices avec JSON | Options réduites |
| `findmnt -J -b` | Points de montage fiables | df seul |
| `df -B1 -PT` | Filesystems usage | Toujours disponible |
| `pvs/vgs/lvs --reportformat json` | LVM info | Ignoré si absent |

### TrueNAS CORE (FreeBSD)

| Commande | Description | Notes |
|----------|-------------|-------|
| `df -k -T` | Filesystems | Conversion bytes nécessaire |
| `zpool list -H -p` | ZFS pools | Parsable output |
| `zfs list -H -p` | ZFS datasets | Avec bytes |

### TrueNAS SCALE (Linux + ZFS)

Combine les commandes Linux + ZFS.

## Interface Utilisateur

### Accordion "Stockage détaillé"

L'accordion est replié par défaut et affiche un résumé compact :

```
[icon] Stockage détaillé [OK] [4 FS] [ZFS] 25% utilisé • 116 GB / 465 GB [i] [v]
```

Éléments :
- **Icône** : `fa-database` (indigo)
- **Badge statut** : OK (vert), Partiel (jaune), Erreur (rouge)
- **Chips** : Nombre de filesystems, ZFS, LVM si présents
- **Résumé** : % utilisé et tailles
- **Bouton inspecteur** : `fa-info-circle`
- **Chevron** : expand/collapse

### Contenu de l'accordion

1. **Table Filesystems** :
   - Colonnes : Mount, Device, FS, Taille, Utilisé, %
   - Seuils de warning : 75% jaune, 90% rouge
   - Fond rouge léger pour partitions > 85%

2. **Section ZFS** (si présent) :
   - Pools avec santé (ONLINE/DEGRADED/FAULTED)
   - Barre de progression usage
   - Liste des datasets

3. **Section LVM** (si présent) :
   - Volume Groups avec taille/free
   - Liste des LVs

### Mode Inspecteur

Drawer affichant les métadonnées de collecte :

- OS détecté
- Timestamp de collecte
- Statut de collecte
- Liste des commandes exécutées avec statut
- Avertissements (partial failures)

## API Endpoints

### Exécuter la collecte

```http
POST /api/builtin-playbooks/execute
Content-Type: application/json

{
  "builtin_id": "collect_storage_details",
  "target": "hostname"
}
```

### Collecte sur tous les hôtes

```http
POST /api/builtin-playbooks/collect-all
```

## Migration Base de Données

Migration `0016_add_storage_details_column.py` :

```python
def upgrade():
    op.add_column('host_metrics', 
        sa.Column('storage_details', sa.JSON(), nullable=True))
```

## Tests

### Backend

```bash
pytest tests/backend/test_storage_details.py -v
```

Couverture :
- Validation schéma
- Parsing données par OS
- Feature flags
- Seuils de warning
- Métadonnées de collecte

### Frontend

```bash
npm run test -- tests/frontend/storage_details.test.js
```

Couverture :
- Rendu accordion
- Table filesystems avec warnings
- Sections ZFS/LVM
- Mode inspecteur
- Formatage bytes

## Checklist de Validation

- [ ] Section "Stockage détaillé" visible sur un host (repliée par défaut)
- [ ] Summary correct (chips, usage, tailles)
- [ ] Linux : filesystems/mounts affichés correctement
- [ ] TrueNAS CORE : df + ZFS pools/datasets affichés
- [ ] TrueNAS SCALE : Linux + ZFS affichés
- [ ] LVM affiché si présent
- [ ] Seuils de warning appliqués (75% jaune, 90% rouge)
- [ ] Mode inspecteur affiche les commandes et statuts
- [ ] Gestion gracieuse des erreurs partielles
- [ ] Données collectées dans le même run que les autres métriques

## Compatibilité

### Commandes Manquantes

| OS | Commande | Comportement |
|----|----------|--------------|
| Alpine | `findmnt` | Fallback df seul, status=partial |
| FreeBSD | `lsblk` | Non utilisé, block_devices=[] |
| Tout | LVM | Ignoré si absent |
| Tout | ZFS | Ignoré si absent |

### Fallbacks

1. Si `lsblk -J -O -b` échoue → essai avec options réduites
2. Si `findmnt -J` échoue → utilise `df` seul
3. Si LVM absent → `lvm_info` vide, pas d'erreur
4. Si ZFS absent → `zfs` vide, pas d'erreur

## Performance

- Timeouts implicites via Ansible (task timeout)
- Commandes légères (lecture seule)
- Pas d'opérations bloquantes
- Collecte parallèle multi-hôtes possible

## Sécurité

- Toutes les commandes sont en lecture seule
- Pas de commandes destructives
- Pas d'exposition de données sensibles (mots de passe, clés)
- Les serial numbers de disques sont optionnels