Fusionne le modèle des sondes et des intrants v1

docs/inputs-store-model-v1.md

@@ -0,0 +1,315 @@
+# Life-NOC — Inputs Store Model v1
+
+## 1. Objet
+
+Ce document définit le **modèle de stockage des intrants** de Life-NOC.
+
+L’objectif est de séparer clairement :
+
+- la **définition** des services, des sondes et des seuils
+- les **valeurs vivantes** utilisées par les sondes
+- les **mécanismes d’ingestion** de ces valeurs
+
+Dans Life-NOC :
+
+- `domains.yaml` définit les domaines, les items, les seuils, les politiques et le type de sonde
+- `data/inputs/` contient les **intrants vivants**
+- les sondes lisent ces intrants pour produire les états Icinga
+
+---
+
+## 2. Principe général
+
+La source de vérité des **intrants** ne doit pas être mélangée avec la définition des services.
+
+### Séparation voulue
+
+- `domains.yaml` = **configuration**
+- `data/inputs/*.yaml` = **valeurs**
+- les interfaces = **moyens d’alimentation**
+- les sondes = **mécanismes d’évaluation**
+
+Cela permet :
+
+- de modifier une valeur sans régénérer toute la définition du système
+- d’alimenter une sonde par saisie manuelle, MQTT, API ou autre
+- de garder un dépôt stable même lorsque les valeurs changent
+
+---
+
+## 3. Convention de structure
+
+Le modèle standard v1 des intrants est :
+
+```text
+data/inputs/<domaine>.yaml
+````
+
+Exemples :
+
+* `data/inputs/revue.yaml`
+* `data/inputs/voiture.yaml`
+* `data/inputs/maison.yaml`
+* `data/inputs/energie.yaml`
+
+Cette convention est **canonique** pour Life-NOC v1.
+
+---
+
+## 4. Pourquoi un fichier par domaine
+
+Le domaine constitue la bonne granularité pour les intrants car :
+
+* il regroupe des items de même nature métier
+* il tend à partager un profil d’ingestion commun
+* il facilite la lecture humaine
+* il permet d’introduire des interfaces cohérentes par domaine
+
+Le domaine fournit donc le **cadre d’ingestion**.
+Chaque item garde sa propre source logique à l’intérieur de ce cadre.
+
+---
+
+## 5. Structure d’un fichier d’intrants de domaine
+
+Chaque fichier `data/inputs/<domaine>.yaml` contient un mapping dont les clés correspondent aux `item_key`.
+
+Exemple :
+
+```yaml
+revue-quotidienne-life-noc:
+  value: "2026-03-14"
+  captured_at: "2026-03-14T08:00:00Z"
+  origin: manual
+
+revue-hebdomadaire-priorites:
+  value: "2026-03-10"
+  captured_at: "2026-03-14T08:00:00Z"
+  origin: manual
+```
+
+---
+
+## 6. Champs minimaux v1
+
+### `value`
+
+Valeur métier utilisée par la sonde.
+
+Exemples :
+
+* date de dernière exécution
+* compteur
+* niveau de stock
+* valeur mesurée
+
+### `captured_at`
+
+Horodatage de capture ou de mise à jour de l’intrant.
+
+Format recommandé :
+
+* ISO 8601 UTC
+
+Exemple :
+
+```text
+2026-03-14T08:00:00Z
+```
+
+### `origin`
+
+Origine de l’intrant.
+
+Valeurs typiques :
+
+* `manual`
+* `mqtt`
+* `api`
+* `derived`
+
+---
+
+## 7. Champs optionnels
+
+Des champs complémentaires pourront être ajoutés selon les besoins :
+
+* `unit`
+* `source_ref`
+* `notes`
+* `quality`
+* `comment`
+* `updated_by`
+
+Ils ne font pas partie du noyau minimal v1.
+
+---
+
+## 8. Rôle du domaine et rôle de l’item
+
+### Le domaine
+
+Le domaine définit le **cadre général** :
+
+* structure d’intrants dominante
+* profil d’ingestion principal
+* interfaces cohérentes
+* conventions de stockage
+
+### L’item
+
+L’item définit le **cas particulier** :
+
+* type de sonde
+* seuils
+* unité
+* clé de lookup
+* paramètres propres
+
+Autrement dit :
+
+* le domaine dit **comment on travaille**
+* l’item dit **quoi on surveille**
+
+---
+
+## 9. Référence entre un item et son intrant
+
+Un item sondé peut référencer un intrant du store avec :
+
+```yaml
+probe:
+  type: elapsed_time
+  source:
+    type: manual_date
+    inputs_file: "/opt/life-noc/data/inputs/revue.yaml"
+    item_key: "revue-hebdomadaire-priorites"
+```
+
+La sonde résout alors :
+
+* `inputs_file` → fichier de domaine
+* `item_key` → clé à l’intérieur du fichier
+
+---
+
+## 10. Compatibilité et migration
+
+Le store des intrants est introduit progressivement.
+
+### Règle de compatibilité
+
+Si la sonde reçoit :
+
+* `inputs_file`
+* `item_key`
+
+elle lit le store.
+
+Sinon, elle peut utiliser une valeur inline fournie dans `domains.yaml`.
+
+Cela permet une migration sans rupture.
+
+### Conséquence
+
+Il n’est pas nécessaire de migrer tous les domaines en même temps.
+
+---
+
+## 11. Portée v1
+
+### Convention cible
+
+Tous les domaines Life-NOC sont destinés à utiliser, à terme, cette structure :
+
+```text
+data/inputs/<domaine>.yaml
+```
+
+### Mise en œuvre initiale
+
+La migration effective commence seulement par les domaines réellement sondés avec la nouvelle méthode.
+
+En v1, il est recommandé de commencer par :
+
+* `data/inputs/revue.yaml`
+
+Les autres domaines seront migrés progressivement, au fur et à mesure de l’introduction de vraies sondes.
+
+---
+
+## 12. Pourquoi ne pas tout migrer d’un coup
+
+Une migration brutale de tous les domaines augmenterait le risque de régression et compliquerait inutilement le dépôt.
+
+Le modèle retenu privilégie :
+
+* une convention unique
+* une adoption graduelle
+* une compatibilité arrière
+* une progression domaine par domaine
+
+---
+
+## 13. Interfaces d’alimentation possibles
+
+Les intrants stockés dans `data/inputs/*.yaml` peuvent provenir de différentes interfaces :
+
+* édition manuelle
+* script CLI
+* interface web
+* API
+* ingestion MQTT
+* calcul dérivé
+
+Le store d’intrants constitue la **couche commune de persistance**, indépendamment du mode d’ingestion.
+
+---
+
+## 14. Positionnement architectural
+
+Le modèle de store d’intrants s’inscrit dans l’architecture Life-NOC suivante :
+
+1. **définition**
+
+   * `domains.yaml`
+   * types de sondes
+   * seuils
+   * politiques
+
+2. **ingestion**
+
+   * GUI
+   * API
+   * MQTT
+   * scripts
+
+3. **persistance**
+
+   * `data/inputs/<domaine>.yaml`
+
+4. **évaluation**
+
+   * sondes
+   * calcul de métrique
+   * états Icinga
+
+---
+
+## 15. Conclusion
+
+Le répertoire `data/inputs/` devient le modèle canonique de stockage des intrants Life-NOC.
+
+Le format standard v1 est :
+
+```text
+data/inputs/<domaine>.yaml
+```
+
+Cette convention permet :
+
+* une séparation claire entre définition et valeurs
+* une gestion cohérente domaine par domaine
+* une migration graduelle
+* une intégration future avec GUI, API et MQTT
+

docs/life-noc-sondes-et-intrants-v1.md

@@ -0,0 +1,711 @@
+# Life-NOC — Modèle des sondes et des intrants v1
+
+## 1. Objet
+
+Ce document définit le **modèle canonique des sondes** et le **modèle de gestion des intrants** de Life-NOC.
+
+L’objectif est de séparer clairement :
+
+- la **définition** des services, des sondes et des seuils
+- les **intrants vivants** utilisés par les sondes
+- les **mécanismes d’ingestion** de ces intrants
+- la **traduction en états Life-NOC**
+
+Ce modèle doit permettre :
+
+- de faire coexister des suivis encore **mockés** et des suivis **réels**
+- d’introduire progressivement des sondes réelles sans casser l’existant
+- d’unifier les méthodes d’évaluation par grandes familles de suivis
+
+---
+
+## 2. Principes de design
+
+### 2.1 Stabilité d’abord
+
+Le dépôt existant doit rester fonctionnel et déployable pendant toute l’introduction des sondes réelles.
+
+Aucune migration brutale ne doit être exigée.
+
+---
+
+### 2.2 Une sonde par nature de calcul, pas par item
+
+Les services Life-NOC ne doivent pas reposer sur une multitude de scripts ad hoc.
+
+Ils doivent être des **instances paramétrées** d’un petit nombre de types de sondes génériques.
+
+Autrement dit :
+
+- un item décrit **quoi mesurer**
+- la sonde décrit **comment l’évaluer**
+
+---
+
+### 2.3 Les sources de données sont multiples
+
+Life-NOC doit pouvoir recevoir des données à partir de plusieurs mécanismes :
+
+- saisie manuelle
+- MQTT
+- fichiers
+- API
+- commandes locales
+- valeurs dérivées
+
+MQTT est un **mécanisme de transport**, pas une mémoire durable.
+
+---
+
+### 2.4 L’ambiguïté technique est critique
+
+Dans Life-NOC, l’impossibilité de conclure techniquement ne doit pas être interprétée comme un état neutre.
+
+Une erreur de lecture, de parsing ou d’accès à la donnée doit produire un état **CRITICAL**, afin de forcer la correction de la sonde ou de sa source.
+
+---
+
+## 3. Sémantique des états Life-NOC
+
+Life-NOC utilise la sémantique suivante :
+
+- **UNKNOWN** : pas encore dû, pas encore à faire
+- **OK** : actionnable maintenant
+- **WARNING** : il faut se presser
+- **CRITICAL** : en retard, anormal, ou impossible à évaluer
+
+Cette convention diffère volontairement de l’usage classique de Nagios/Icinga.
+
+Dans Life-NOC :
+
+- le vert n’exprime pas l’absence de travail
+- il exprime le **bon moment pour agir**
+- le gris `UNKNOWN` signifie que l’item n’est pas encore dans sa fenêtre d’action
+
+---
+
+## 4. Taxonomie des sondes v1
+
+Le modèle conceptuel v1 couvre cinq types de sondes.
+
+### 4.1 `elapsed_time`
+
+Mesure le **temps écoulé** depuis un événement ou une exécution précédente.
+
+#### Exemples
+- revue quotidienne
+- revue hebdomadaire
+- inspection trimestrielle
+- test détecteurs
+- vérification sauvegardes
+
+#### Donnée de base
+- date de dernière exécution
+
+#### Métrique typique
+- jours écoulés
+
+#### Logique générale
+Plus le temps écoulé augmente, plus l’item devient dû.
+
+---
+
+### 4.2 `elapsed_distance`
+
+Mesure une **distance écoulée** depuis un événement passé.
+
+#### Exemples
+- kilométrage depuis vidange
+- kilométrage depuis entretien pneus
+- kilométrage depuis vérification freins
+- kilomètres depuis changement de courroie
+
+#### Données de base
+- compteur courant
+- compteur lors de la dernière exécution
+
+#### Métrique typique
+- kilomètres écoulés
+
+#### Logique générale
+Plus la distance écoulée augmente, plus l’item devient dû.
+
+---
+
+### 4.3 `current_value`
+
+Mesure une **valeur instantanée** comparée à des seuils.
+
+#### Exemples
+- tension batterie
+- température
+- humidité
+- espace disque libre
+- charge électrique
+- niveau de tension
+
+#### Donnée de base
+- valeur actuelle observée
+
+#### Métriques typiques
+- volts
+- pourcentage
+- degrés
+- gigaoctets
+- watts
+
+#### Logique générale
+L’état dépend d’un positionnement par rapport à un ou plusieurs seuils.
+
+---
+
+### 4.4 `remaining_quantity`
+
+Mesure ce qu’il **reste** d’un stock, d’une réserve ou d’une autonomie.
+
+#### Exemples
+- nourriture chats restante
+- réserve d’eau
+- vitamines restantes
+- carburant restant
+- consommables
+
+#### Donnée de base
+- quantité restante
+
+#### Métriques typiques
+- jours d’autonomie
+- litres
+- unités
+- kilogrammes
+- pourcentage
+
+#### Logique générale
+Plus la quantité restante diminue, plus l’item devient critique.
+
+---
+
+### 4.5 `days_until_due`
+
+Mesure le **temps restant avant une échéance fixe**.
+
+#### Exemples
+- permis de conduire
+- carte d’assurance maladie
+- passeport
+- assurances
+- échéance fiscale
+- rendez-vous
+
+#### Donnée de base
+- date d’échéance
+
+#### Métrique typique
+- jours restants
+
+#### Logique générale
+Plus on approche de la date, plus l’item entre dans la fenêtre d’action, puis dans l’urgence.
+
+---
+
+## 5. Sources de données
+
+Le modèle distingue le **type de sonde** de la **source de données**.
+
+### 5.1 Sources conceptuellement prévues
+
+- `manual_date`
+- `manual_counter`
+- `manual_value`
+- `mqtt`
+- `file_json`
+- `file_text`
+- `csv`
+- `api`
+- `command`
+- `derived`
+
+### 5.2 Sources v1 à faible risque
+
+Pour l’implémentation initiale, seules les sources suivantes sont retenues :
+
+- `manual_date`
+
+Les autres sources sont **réservées** au modèle, mais non implémentées dans la première tranche.
+
+---
+
+## 6. Schéma canonique d’un item
+
+Chaque item peut, à terme, porter une description de sonde structurée.
+
+Exemple canonique :
+
+```yaml
+probe:
+  type: elapsed_time
+  source:
+    type: manual_date
+    value: "2026-03-10"
+  metric:
+    unit: days
+  thresholds:
+    unknown_lt: 5
+    ok_gte: 5
+    warning_gte: 7
+    critical_gte: 10
+  policy:
+    on_error: critical
+````
+
+---
+
+## 7. Règles générales de seuils
+
+### 7.1 Cas où la métrique augmente avec l’urgence
+
+Exemples :
+
+* jours écoulés
+* kilomètres écoulés
+
+Ordre d’évaluation recommandé :
+
+1. `critical_gte`
+2. `warning_gte`
+3. `ok_gte`
+4. sinon `unknown`
+
+---
+
+### 7.2 Cas où la métrique diminue avec la gravité
+
+Exemples :
+
+* quantité restante
+* tension minimale
+* autonomie restante
+
+Ordre d’évaluation recommandé :
+
+1. `critical_lt`
+2. `warning_lt`
+3. `ok_gte`
+4. sinon `unknown`
+
+---
+
+### 7.3 Cas où la métrique est une échéance future
+
+Exemples :
+
+* jours avant expiration
+* jours avant rendez-vous
+* jours avant renouvellement
+
+Ordre d’évaluation recommandé :
+
+1. `critical_lt`
+2. `warning_lt`
+3. `ok_lt`
+4. sinon `unknown`
+
+---
+
+## 8. Politique d’erreur
+
+La politique d’erreur par défaut de Life-NOC est :
+
+```yaml
+policy:
+  on_error: critical
+```
+
+Cela signifie que les situations suivantes doivent produire `CRITICAL` :
+
+* donnée absente
+* donnée invalide
+* parsing impossible
+* source inaccessible
+* seuils incohérents
+* type de sonde non supporté
+* unité non supportée
+* configuration incomplète
+
+Cette règle vise à éviter que des erreurs techniques demeurent invisibles.
+
+---
+
+## 9. Modèle de stockage des intrants
+
+La source de vérité des **intrants** ne doit pas être mélangée avec la définition des services.
+
+### Séparation voulue
+
+* `domains.yaml` = **configuration**
+* `data/inputs/*.yaml` = **valeurs**
+* les interfaces = **moyens d’alimentation**
+* les sondes = **mécanismes d’évaluation**
+
+Cela permet :
+
+* de modifier une valeur sans régénérer toute la définition du système
+* d’alimenter une sonde par saisie manuelle, MQTT, API ou autre
+* de garder un dépôt stable même lorsque les valeurs changent
+
+---
+
+## 10. Convention de structure du store
+
+Le modèle standard v1 des intrants est :
+
+```text
+data/inputs/<domaine>.yaml
+```
+
+Exemples :
+
+* `data/inputs/revue.yaml`
+* `data/inputs/voiture.yaml`
+* `data/inputs/maison.yaml`
+* `data/inputs/energie.yaml`
+
+Cette convention est **canonique** pour Life-NOC v1.
+
+---
+
+## 11. Pourquoi un fichier par domaine
+
+Le domaine constitue la bonne granularité pour les intrants car :
+
+* il regroupe des items de même nature métier
+* il tend à partager un profil d’ingestion commun
+* il facilite la lecture humaine
+* il permet d’introduire des interfaces cohérentes par domaine
+
+Le domaine fournit donc le **cadre d’ingestion**.
+Chaque item garde sa propre source logique à l’intérieur de ce cadre.
+
+---
+
+## 12. Structure d’un fichier d’intrants de domaine
+
+Chaque fichier `data/inputs/<domaine>.yaml` contient un mapping dont les clés correspondent aux `item_key`.
+
+Exemple :
+
+```yaml
+revue-quotidienne-life-noc:
+  value: "2026-03-14"
+  captured_at: "2026-03-14T08:00:00Z"
+  origin: manual
+
+revue-hebdomadaire-priorites:
+  value: "2026-03-10"
+  captured_at: "2026-03-14T08:00:00Z"
+  origin: manual
+```
+
+---
+
+## 13. Champs minimaux v1 du store
+
+### `value`
+
+Valeur métier utilisée par la sonde.
+
+Exemples :
+
+* date de dernière exécution
+* compteur
+* niveau de stock
+* valeur mesurée
+
+### `captured_at`
+
+Horodatage de capture ou de mise à jour de l’intrant.
+
+Format recommandé :
+
+* ISO 8601 UTC
+
+Exemple :
+
+```text
+2026-03-14T08:00:00Z
+```
+
+### `origin`
+
+Origine de l’intrant.
+
+Valeurs typiques :
+
+* `manual`
+* `mqtt`
+* `api`
+* `derived`
+
+---
+
+## 14. Champs optionnels du store
+
+Des champs complémentaires pourront être ajoutés selon les besoins :
+
+* `unit`
+* `source_ref`
+* `notes`
+* `quality`
+* `comment`
+* `updated_by`
+
+Ils ne font pas partie du noyau minimal v1.
+
+---
+
+## 15. Rôle du domaine et rôle de l’item
+
+### Le domaine
+
+Le domaine définit le **cadre général** :
+
+* structure d’intrants dominante
+* profil d’ingestion principal
+* interfaces cohérentes
+* conventions de stockage
+
+### L’item
+
+L’item définit le **cas particulier** :
+
+* type de sonde
+* seuils
+* unité
+* clé de lookup
+* paramètres propres
+
+Autrement dit :
+
+* le domaine dit **comment on travaille**
+* l’item dit **quoi on surveille**
+
+---
+
+## 16. Référence entre un item et son intrant
+
+Un item sondé peut référencer un intrant du store avec :
+
+```yaml
+probe:
+  type: elapsed_time
+  source:
+    type: manual_date
+    inputs_file: "/opt/life-noc/data/inputs/revue.yaml"
+    item_key: "revue-hebdomadaire-priorites"
+```
+
+La sonde résout alors :
+
+* `inputs_file` → fichier de domaine
+* `item_key` → clé à l’intérieur du fichier
+
+---
+
+## 17. Compatibilité et migration
+
+Le store des intrants est introduit progressivement.
+
+### Règle de compatibilité
+
+Si la sonde reçoit :
+
+* `inputs_file`
+* `item_key`
+
+elle lit le store.
+
+Sinon, elle peut utiliser une valeur inline fournie dans `domains.yaml`.
+
+Cela permet une migration sans rupture.
+
+### Conséquence
+
+Il n’est pas nécessaire de migrer tous les domaines en même temps.
+
+---
+
+## 18. Portée v1
+
+### Convention cible
+
+Tous les domaines Life-NOC sont destinés à utiliser, à terme, cette structure :
+
+```text
+data/inputs/<domaine>.yaml
+```
+
+### Mise en œuvre initiale
+
+La migration effective commence seulement par les domaines réellement sondés avec la nouvelle méthode.
+
+En v1, il est recommandé de commencer par :
+
+* `data/inputs/revue.yaml`
+
+Les autres domaines seront migrés progressivement, au fur et à mesure de l’introduction de vraies sondes.
+
+---
+
+## 19. Pourquoi ne pas tout migrer d’un coup
+
+Une migration brutale de tous les domaines augmenterait le risque de régression et compliquerait inutilement le dépôt.
+
+Le modèle retenu privilégie :
+
+* une convention unique
+* une adoption graduelle
+* une compatibilité arrière
+* une progression domaine par domaine
+
+---
+
+## 20. Interfaces d’alimentation possibles
+
+Les intrants stockés dans `data/inputs/*.yaml` peuvent provenir de différentes interfaces :
+
+* édition manuelle
+* script CLI
+* interface web
+* API
+* ingestion MQTT
+* calcul dérivé
+
+Le store d’intrants constitue la **couche commune de persistance**, indépendamment du mode d’ingestion.
+
+---
+
+## 21. Positionnement architectural
+
+Le modèle des sondes et des intrants s’inscrit dans l’architecture Life-NOC suivante :
+
+1. **définition**
+
+   * `domains.yaml`
+   * types de sondes
+   * seuils
+   * politiques
+
+2. **ingestion**
+
+   * GUI
+   * API
+   * MQTT
+   * scripts
+
+3. **persistance**
+
+   * `data/inputs/<domaine>.yaml`
+
+4. **évaluation**
+
+   * sondes
+   * calcul de métrique
+   * états Icinga
+
+---
+
+## 22. Coexistence avec le modèle mocké
+
+Le dépôt actuel repose sur une preuve de concept initialement mockée.
+
+L’introduction du modèle de sonde ne doit pas casser cette base.
+
+### Règle de compatibilité
+
+* si un item **ne définit pas** de bloc `probe`, il continue de fonctionner selon la logique mock existante
+* si un item **définit** un bloc `probe`, il peut être pris en charge par la nouvelle sonde générique, selon les types réellement supportés par le moteur
+
+Cette compatibilité permet une migration progressive, item par item.
+
+---
+
+## 23. Portée de l’implémentation initiale
+
+Le **modèle conceptuel v1** couvre cinq types de sondes.
+
+Cependant, afin de préserver la stabilité du dépôt, l’**implémentation initiale** est volontairement limitée à :
+
+* `probe.type = elapsed_time`
+* `source.type = manual_date`
+* `metric.unit = days`
+
+Tous les autres types restent **documentés mais non encore codés**.
+
+Cette décision est volontaire. Elle permet :
+
+* de garder le dépôt stable
+* de valider la mécanique sur un seul cas simple
+* de faciliter le débogage
+* de réduire le risque de régression
+
+---
+
+## 24. Exemple complet
+
+```yaml
+revue:
+  - name: revue-hebdomadaire-priorites
+    date: "2026-03-10"
+    notes: Revoir les priorités de la semaine
+
+    probe:
+      type: elapsed_time
+      source:
+        type: manual_date
+        inputs_file: "/opt/life-noc/data/inputs/revue.yaml"
+        item_key: "revue-hebdomadaire-priorites"
+      metric:
+        unit: days
+      thresholds:
+        unknown_lt: 5
+        ok_gte: 5
+        warning_gte: 7
+        critical_gte: 10
+      policy:
+        on_error: critical
+```
+
+Et dans le store :
+
+```yaml
+revue-hebdomadaire-priorites:
+  value: "2026-03-10"
+  captured_at: "2026-03-14T08:00:00Z"
+  origin: manual
+```
+
+Interprétation :
+
+* moins de 5 jours depuis la dernière revue : `UNKNOWN`
+* à partir de 5 jours : `OK`
+* à partir de 7 jours : `WARNING`
+* à partir de 10 jours : `CRITICAL`
+
+---
+
+## 25. Conclusion
+
+Life-NOC dispose maintenant d’un cadre unifié pour :
+
+* définir les types de sondes
+* structurer les seuils
+* normaliser les intrants
+* séparer configuration et valeurs
+* préparer l’intégration future avec GUI, API et MQTT
+
+Le modèle standard v1 repose sur :
+
+* une taxonomie de cinq types de sondes
+* une convention de store d’intrants par domaine
+* une migration progressive, compatible avec l’existant
+