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

# 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