From aa3ebf329415794293a8c604e9575b80a30d85b5 Mon Sep 17 00:00:00 2001
From: Daniel Allaire <allaire.dan@chezlepro.ca>
Date: Sat, 14 Mar 2026 17:13:56 -0400
Subject: [PATCH] Fige la taxonomie des sondes Life-NOC v1

---
 docs/probe-model-v1.md | 453 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 453 insertions(+)
 create mode 100644 docs/probe-model-v1.md

diff --git a/docs/probe-model-v1.md b/docs/probe-model-v1.md
new file mode 100644
index 0000000..5a62db2
--- /dev/null
+++ b/docs/probe-model-v1.md
@@ -0,0 +1,453 @@
+# Life-NOC — Probe Model v1
+
+## 1. Objet
+
+Ce document définit le **modèle canonique de sonde** de Life-NOC.
+
+L’objectif est de séparer clairement :
+
+- la **nature du suivi**
+- la **source des données**
+- la **métrique calculée**
+- les **seuils**
+- la **traduction en états Life-NOC**
+
+Ce modèle doit permettre de faire coexister :
+
+- des suivis encore **mockés**
+- des suivis **réels**
+- des intrants provenant de sources variées
+- une évolution progressive du système, sans casser l’existant
+
+---
+
+## 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. Coexistence avec le modèle mocké
+
+Le dépôt actuel repose sur une preuve de concept **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.
+
+---
+
+## 10. 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
+
+---
+
+## 11. 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
+        value: "2026-03-10"
+      metric:
+        unit: days
+      thresholds:
+        unknown_lt: 5
+        ok_gte: 5
+        warning_gte: 7
+        critical_gte: 10
+      policy:
+        on_error: critical
+```
+
+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`
+
+---
+
+## 12. Positionnement architectural
+
+Le modèle de sonde Life-NOC s’inscrit dans une architecture à quatre couches :
+
+1. **définition**
+
+   * schéma des sondes
+   * règles
+   * seuils
+   * unités
+
+2. **acquisition**
+
+   * MQTT
+   * saisie manuelle
+   * fichiers
+   * API
+   * commandes
+
+3. **persistance**
+
+   * mémoire durable des valeurs utiles
+   * dates
+   * compteurs
+   * provenance
+
+4. **évaluation**
+
+   * calcul de métrique
+   * comparaison aux seuils
+   * retour d’état vers Icinga
+
+---
+
+## 13. Conclusion
+
+Le modèle de sonde v1 donne à Life-NOC un cadre formel pour sortir progressivement du mock sans compromettre la stabilité du système.
+
+Il permet de :
+
+* figer la taxonomie des suivis
+* uniformiser les méthodes d’évaluation
+* préparer l’intégration de sources de données réelles
+* conserver une migration graduelle et réversible