life-noc/docs/inputs-store-model-v1.md

# 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