# Consigne pour Claude Code — inventaire HDD/SMART vers MQTT

## Contexte
Gilles veut un **script Linux lancé une seule fois par machine** pour inventorier les disques d’un système Debian ou Proxmox.

Le script doit fonctionner sur :
- une machine physique
- une VM
- une VM avec disques pass-through
- une VM avec PCI passthrough si les disques apparaissent dans l’OS invité

Le but est de **collecter un snapshot à l’instant T** puis de **publier le résultat sur MQTT**.

Le script doit être stocké dans le même dépôt que le reste du projet :
- dépôt local : `mes_hdd`
- chemin local du projet : `/home/gilles/projects/mes_hdd/`

Le fichier de consigne doit être copié dans ce projet sous le nom :
- `consigne.hd`

---

## Objectif principal
Créer un script qui :
1. détecte les disques visibles par l’OS
2. identifie chaque disque dans le système
3. lit l’état SMART quand c’est possible
4. récupère la taille du disque
5. récupère les partitions et le taux d’utilisation des points de montage
6. publie un **message MQTT retenu** (`retain`) sur le broker de Gilles
7. s’arrête après une exécution unique

Il ne faut **pas** prévoir de cron ni d’agent permanent.

---

## Broker MQTT cible
Le script doit publier vers :
- hôte : `10.0.0.3`
- port : `1883`
- sans user ni mot de passe

Le message doit être **retenu sur le serveur MQTT**.

La publication doit donc utiliser l’équivalent de :
- `mosquitto_pub ... -r`

---

## Résultat attendu
Le script doit produire un **payload structuré**, idéalement en JSON, contenant au minimum :
- hostname
- IP principale
- date/heure de collecte
- liste des disques
- identifiant système du disque : `sda`, `sdb`, `nvme0n1`, etc.
- chemin du périphérique : `/dev/sdX`, `/dev/nvmeXn1`, etc.
- modèle
- numéro de série
- type : HDD / SSD / NVMe / inconnu
- capacité totale
- partitions détectées
- point de montage associé
- espace libre
- espace total
- taux d’utilisation
- état SMART
- état SMART expliqué en français simple
- remarque / statut

---

## Exigences sur l’état SMART
L’état SMART doit être compréhensible par un novice, en français.

Exemples de libellés attendus :
- `Bon état`
- `Attention`
- `Défaillance probable`
- `SMART indisponible`

Le script peut aussi ajouter une explication courte, par exemple :
- `Bon état : aucun problème SMART détecté`
- `Attention : certains indicateurs SMART sont dégradés`
- `Défaillance probable : prévoir le remplacement du disque`

Le but est que la lecture côté MQTT soit immédiatement compréhensible.

---

## Exigences sur l’identification système
Le script doit identifier clairement les disques visibles sous Linux :
- `sda`, `sdb`, `sdc`, …
- `nvme0n1`, `nvme1n1`, …
- si possible, inclure aussi le lien `/dev/disk/by-id/...`

L’objectif est de relier :
- le nom logique dans l’OS
- le modèle du disque
- le numéro de série
- les partitions
- le point de montage
- l’usage réel

---

## Exigences sur les partitions et l’espace
Pour chaque disque, si des partitions ou des montages existent, récupérer :
- la liste des partitions
- le point de montage
- l’espace libre
- l’espace total
- le taux d’utilisation

Si un disque n’a pas de filesystem monté, le script doit l’indiquer clairement.

---

## Robustesse
Le script doit rester robuste si :
- un disque ne répond pas
- `smartctl` échoue
- un disque n’est pas monté
- SMART n’est pas accessible depuis l’environnement
- le système est une VM et ne voit pas tous les disques physiques sous-jacents

Le script ne doit pas casser l’inventaire global si un disque est problématique.

---

## Mode d’exécution
Le script doit être **exécuté une seule fois** par machine.

Il ne faut pas créer :
- de service permanent
- de daemon
- de cron
- de timer systemd

Le mode attendu est une exécution manuelle ou à distance ponctuelle.

---

## Publication MQTT
Le script doit publier le résultat :
- sur un topic dédié par machine, par exemple `hdd/inventaire/<hostname>`
- en **JSON** si possible
- avec le mode **retain** activé

Le message retenu permettra à un client MQTT de relire le dernier état plus tard.

---

## Format de message conseillé
Exemple de structure JSON :

```json
{
  "hostname": "pve1",
  "ip": "10.0.3.205",
  "timestamp": "2026-05-28T15:30:00+02:00",
  "disks": [
    {
      "device": "sda",
      "path": "/dev/sda",
      "by_id": "/dev/disk/by-id/...",
      "model": "ST1000LM024",
      "serial": "...",
      "type": "HDD",
      "capacity": "1T",
      "smart": "Bon état",
      "smart_detail": "Bon état : aucun problème SMART détecté",
      "partitions": [
        {
          "name": "sda1",
          "mountpoint": "/mnt/data",
          "free": "500G",
          "total": "1T",
          "used_percent": 50
        }
      ]
    }
  ]
}
```

---

## Fichier de sortie local
Même si la destination principale est MQTT, le script peut aussi générer localement :
- un fichier JSON temporaire
- ou un fichier Markdown de debug si utile

Mais ce n’est pas obligatoire.

---

## Lancement à distance
Prévoir une méthode simple pour exécuter le script à distance, par exemple :
- `curl ... | bash`
- ou téléchargement puis exécution
- ou script brut servi depuis le dépôt Gitea

La méthode distante doit être :
- documentée
- reproductible
- sans secret en clair

---

## Source de vérité fonctionnelle
Le script doit s’appuyer sur des outils simples et standards :
- `lsblk`
- `df`
- `smartctl`
- `hostname`
- `ip`
- `mosquitto_pub`

---

## Critères de qualité
- code lisible
- exécution unique
- sortie JSON claire
- état SMART compréhensible en français
- publication MQTT retenue
- aucune dépendance inutile
- pas de cron
- pas d’agent permanent

---

## Attendu de Claude Code
Claude Code doit :
1. proposer l’architecture minimale du script
2. créer le script dans `mes_hdd`
3. documenter le topic MQTT et le format JSON
4. prévoir la publication retenue
5. vérifier que le résultat est simple à exploiter sur MQTT