life-noc/docs/probe-model-v1.md

# 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