life-noc/docs/life_noc_documentation_pack.md

# Life-NOC — Documentation complète

## 1. Présentation générale

### 1.1 Définition

**Life-NOC** est un système de pilotage personnel qui applique à la vie réelle la logique d’un **NOC** (Network Operations Center / centre d’opérations).

Son but n’est pas d’automatiser la vie à la place de la personne.
Son but est de :

- rendre visibles les suivis importants ;
- transformer la charge mentale en état observable ;
- soutenir la mémoire prospective ;
- orienter l’attention vers ce qui mérite réellement d’être vu ;
- réduire la friction entre la prise de conscience et l’action.

Life-NOC peut être résumé ainsi :

> **Voir clair, prioriser juste, agir au bon endroit.**

---

### 1.2 Finalité

Life-NOC sert à superviser des éléments de la vie personnelle, domestique, administrative, technique ou communautaire comme s’il s’agissait de services critiques dans une salle de contrôle.

Il permet par exemple de suivre :

- des revues périodiques ;
- des échéances ;
- des stocks ;
- des vérifications techniques ;
- des obligations administratives ;
- des contrôles de maintenance ;
- des routines de résilience ;
- des points d’attention dans l’environnement physique.

---

### 1.3 Positionnement

Life-NOC n’est pas :

- un simple gestionnaire de tâches ;
- un agenda ;
- un ERP ;
- un moteur d’automatisation généraliste ;
- un outil d’inventaire pur.

Life-NOC est :

- un **système de supervision attentionnelle** ;
- un **cadre d’évaluation de suivis** ;
- un **point de convergence** entre intrants, règles, états et actions ;
- une **interface de réduction de charge mentale**.

---

## 2. Principes de fonctionnement

### 2.1 Séparation des couches

Life-NOC repose sur quatre couches distinctes :

1. **définition** ;
2. **ingestion** ;
3. **persistance** ;
4. **évaluation**.

#### Définition
Contient les items à superviser, les méthodes, les seuils, les notes et les liens utiles.

#### Ingestion
Contient les mécanismes par lesquels une donnée entre dans le système :
- saisie manuelle ;
- API ;
- page HTML ;
- QR code ;
- plus tard MQTT, GUI avancée, etc.

#### Persistance
Contient les intrants vivants à jour.

#### Évaluation
Contient la logique qui transforme un intrant en état Life-NOC.

---

### 2.2 Philosophie générale

Le système suit cette logique :

- le **domaine** organise ;
- la **méthode** évalue ;
- l’**item** fait le lien entre les deux ;
- l’**intrant** fournit la valeur vivante ;
- la **page item** réduit la friction d’action ;
- **Icinga** rend les états visibles dans un cadre de supervision.

---

## 3. États Life-NOC

Life-NOC utilise une sémantique propre des états.

### 3.1 États

- **UNKNOWN** : pas encore dû, pas encore à faire ;
- **OK** : actionnable maintenant ;
- **WARNING** : il faut se presser ;
- **CRITICAL** : en retard, anormal, ou impossible à évaluer.

### 3.2 Différence avec l’usage classique de Nagios/Icinga

Dans Life-NOC :

- le vert ne signifie pas seulement « tout va bien » ;
- le vert signifie souvent « c’est le bon moment pour agir » ;
- le gris signifie que l’item n’est pas encore entré dans sa fenêtre d’action.

### 3.3 Politique d’erreur

Par défaut, si le système ne peut pas conclure techniquement, il retourne **CRITICAL**.

Exemples :

- fichier introuvable ;
- donnée absente ;
- format invalide ;
- parsing impossible ;
- seuil incohérent ;
- type de sonde non pris en charge.

Cette politique force la correction des faux positifs techniques plutôt que leur invisibilisation.

---

## 4. Organisation métier par domaines

Life-NOC regroupe les items dans des **domaines**.

Exemples de domaines :

- revue ;
- focus ;
- finances-personnelles ;
- fiscalite-personnelle ;
- obligations-legales-personnelles ;
- maison ;
- garage-et-rangement ;
- energie ;
- resilience ;
- stock-alimentaire ;
- sante ;
- voiture ;
- jardin ;
- informatique-personnelle ;
- infrastructure-chezlepro ;
- reseau-chezlepro ;
- securite-chezlepro ;
- exploitation-chezlepro ;
- projets ;
- communaute ;
- documentation ;
- animaux.

Le domaine est une unité d’organisation métier, pas nécessairement une unité de calcul.

Un même domaine peut contenir plusieurs méthodes de sonde.

---

## 5. Taxonomie des méthodes de sonde

Le modèle conceptuel v1 de Life-NOC prévoit cinq méthodes principales.

### 5.1 elapsed_time

Mesure le temps écoulé depuis un événement ou une exécution précédente.

Exemples :
- revue hebdomadaire ;
- inspection trimestrielle ;
- test périodique.

Intrant attendu :
- date de dernière exécution.

Unité typique :
- jours.

---

### 5.2 days_until_due

Mesure le temps restant avant une échéance fixe.

Exemples :
- renouvellement du permis ;
- passeport ;
- assurance ;
- obligation légale.

Intrant attendu :
- date d’échéance.

Unité typique :
- jours.

---

### 5.3 elapsed_distance

Mesure la distance écoulée depuis une action passée.

Exemples :
- vidange ;
- entretien pneus ;
- entretien freins.

Intrants attendus :
- compteur courant ;
- compteur au dernier entretien.

Unité typique :
- kilomètres.

---

### 5.4 current_value

Évalue une valeur instantanée contre des seuils.

Exemples :
- tension batterie ;
- température ;
- humidité ;
- espace libre.

Intrant attendu :
- valeur actuelle.

Unité typique :
- variable selon le cas.

---

### 5.5 remaining_quantity

Évalue ce qu’il reste d’un stock ou d’une réserve.

Exemples :
- nourriture chats ;
- réserve d’eau ;
- carburant ;
- consommables.

Intrant attendu :
- quantité restante.

Unité typique :
- jours, litres, unités, pourcentage, etc.

---

## 6. Portée actuellement validée

Au stade actuel, les méthodes réellement validées dans le système sont :

- `elapsed_time` ;
- `days_until_due`.

Les autres méthodes sont conceptuellement définies, mais pas encore consolidées de la même manière dans le dépôt.

---

## 7. Définition des items

Les items supervisés sont définis dans :

```text
domains.yaml
```

Chaque item peut contenir :

- `name` ;
- `date` ;
- `notes` ;
- `notes_url` ;
- `instructions_url` ;
- `action_url` ;
- `probe` ;
- `thresholds` ;
- `policy`.

### 7.1 Rôle des champs descriptifs

- `notes` : résumé humain court ;
- `notes_url` : contexte / référence ;
- `instructions_url` : quoi faire / procédure ;
- `action_url` : où agir concrètement.

### 7.2 Champ probe

Le champ `probe` décrit :

- la méthode ;
- la source ;
- l’unité ;
- les seuils ;
- la politique d’erreur.

Exemple :

```yaml
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
```

---

## 8. Store des intrants

### 8.1 Principe

Les intrants vivants ne sont pas mélangés à la définition des items.

Ils sont stockés sous :

```text
data/inputs/<domaine>.yaml
```

Exemples :

- `data/inputs/revue.yaml`
- `data/inputs/obligations-legales-personnelles.yaml`

### 8.2 Contenu minimal d’un intrant

Un intrant contient en général :

- `value` ;
- `captured_at` ;
- `origin`.

Exemple :

```yaml
revue-hebdomadaire-priorites:
  value: "2026-03-14"
  captured_at: "2026-03-14T23:16:41Z"
  origin: manual
```

### 8.3 Rôle du store

Le store d’intrants permet :

- de changer une valeur sans toucher à `domains.yaml` ;
- d’alimenter les sondes avec des valeurs vivantes ;
- de préparer les futures interfaces GUI, API, QR et autres.

---

## 9. CLI de gestion des intrants

Life-NOC dispose d’une CLI de gestion des intrants.

### 9.1 Commandes principales

- `list`
- `get`
- `set`
- `complete`

### 9.2 Exemples

```bash
life-noc-input list revue
life-noc-input get revue revue-hebdomadaire-priorites
life-noc-input set revue revue-hebdomadaire-priorites 2026-03-14
life-noc-input complete revue revue-hebdomadaire-priorites
```

### 9.3 Rôle de complete

`complete` est particulièrement utile pour les items de type `elapsed_time/manual_date`.

Il inscrit automatiquement :

- `value = date du jour`
- `captured_at = maintenant`
- `origin = manual`

---

## 10. API locale des intrants

Life-NOC expose une API locale sur :

```text
http://127.0.0.1:8787
```

### 10.1 Endpoints JSON

- `GET /health`
- `GET /inputs/{domain}`
- `GET /inputs/{domain}/{item_key}`
- `POST /inputs/{domain}/{item_key}`
- `POST /inputs/{domain}/{item_key}/complete`

### 10.2 Exemple

```bash
curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/inputs/revue
curl http://127.0.0.1:8787/inputs/revue/revue-hebdomadaire-priorites
curl -X POST http://127.0.0.1:8787/inputs/revue/revue-hebdomadaire-priorites \
  -H 'Content-Type: application/json' \
  -d '{"value":"2026-03-14","origin":"manual"}'
```

### 10.3 Dépendances importantes

Le service FastAPI nécessite notamment :

- `python3-fastapi`
- `python3-uvicorn`
- `python3-multipart`

---

## 11. Pages HTML Life-NOC

Le serveur Life-NOC sert aussi des pages HTML simples destinées à l’action humaine.

### 11.1 URL d’item

Format :

```text
/life-noc/item/<domaine>/<item_key>
```

Exemple :

```text
/life-noc/item/revue/revue-hebdomadaire-priorites
```

### 11.2 Contenu de la page

La page affiche :

- titre humain ;
- état actuel ;
- type de sonde ;
- dernier intrant ;
- domaine ;
- item key ;
- notes ;
- lien `notes_url` ;
- lien `instructions_url` ;
- lien `action_url` ;
- bouton `Compléter`.

### 11.3 Route d’action HTML

Le bouton `Compléter` utilise :

```text
POST /life-noc/item/<domaine>/<item_key>/complete
```

Puis redirige vers la page de l’item.

---

## 12. Intégration Icinga

Life-NOC s’appuie sur Icinga 2 / Icinga Web 2 pour la visualisation des états supervisés.

### 12.1 Ce que le système sait faire

- déployer les définitions de services ;
- exposer les custom variables ;
- rendre les états lisibles dans Icinga ;
- supporter `Check Now` ;
- intégrer les BPM natifs ;
- générer des servicegroups cohérents.

### 12.2 Informations visibles dans Icinga

Selon l’item, on peut voir notamment :

- l’état calculé ;
- les variables de seuil ;
- les variables de source ;
- les liens utiles ;
- `instructions_url` en variable personnalisée.

---

## 13. BPM et servicegroups

Life-NOC génère :

- des services Icinga ;
- des groupes de services ;
- une configuration BPM native.

L’objectif est de rendre visibles à la fois :

- les items unitaires ;
- les regroupements par domaine ;
- la vision d’ensemble hiérarchisée.

---

## 14. Flux de fonctionnement complet

Le fonctionnement complet suit le chemin suivant :

1. l’item est défini dans `domains.yaml` ;
2. l’intrant vivant est stocké dans `data/inputs/<domaine>.yaml` ;
3. la CLI, l’API ou la page HTML modifient cet intrant ;
4. la sonde lit le store ;
5. la sonde calcule l’état ;
6. Icinga l’affiche ;
7. l’usager agit ;
8. l’intrant est mis à jour ;
9. le cycle recommence.

---

## 15. Déploiement et reproductibilité

Le dépôt doit permettre de reproduire le système sans correctifs manuels cachés.

### 15.1 Principes

- les correctifs doivent vivre dans le dépôt ;
- les dépendances nécessaires doivent être installées automatiquement ;
- les scripts de chantier temporaires doivent être supprimés une fois les changements intégrés proprement.

### 15.2 Déploiement habituel

```bash
make check
make deploy-with-bpm
```

---

## 16. Documentation pour les usagers

# Guide usager Life-NOC

## 16.1 À quoi sert Life-NOC pour l’usager

Life-NOC aide une personne à voir rapidement ce qui mérite son attention, sans tout garder dans sa tête.

Il sert à suivre des choses comme :

- des revues régulières ;
- des dates importantes ;
- des entretiens ;
- des vérifications ;
- des obligations.

## 16.2 Ce que signifient les états

- **UNKNOWN** : pas encore le temps d’agir ;
- **OK** : c’est le bon moment pour s’en occuper ;
- **WARNING** : il faut accélérer ;
- **CRITICAL** : c’est urgent ou il y a un problème.

## 16.3 Comment consulter un item

Un item peut être consulté :

- dans Icinga ;
- via une page Life-NOC ;
- plus tard via QR code.

La page Life-NOC affiche :

- le nom du suivi ;
- son état ;
- la dernière valeur enregistrée ;
- les notes ;
- les instructions ;
- un bouton pour marquer l’action comme faite.

## 16.4 Comment marquer une action comme faite

Quand l’item le permet, il suffit de cliquer sur **Compléter**.

Cela met à jour la valeur de l’intrant avec la date du jour.

## 16.5 Quand utiliser les liens utiles

- **Notes** : pour comprendre le contexte ;
- **Instructions** : pour savoir quoi faire ;
- **Action** : pour aller directement au bon outil ou à la bonne page.

## 16.6 Ce que l’usager n’a pas besoin de faire

L’usager n’a normalement pas besoin de comprendre :

- le moteur de sonde ;
- les fichiers YAML ;
- la structure technique ;
- l’architecture Icinga.

Il lui suffit de :

- voir l’état ;
- consulter les instructions ;
- marquer l’action effectuée.

---

## 17. Documentation d’exploitation

### 17.1 Vérifications utiles

#### Vérifier l’API

```bash
curl http://127.0.0.1:8787/health
```

#### Vérifier un intrant

```bash
curl http://127.0.0.1:8787/inputs/revue/revue-hebdomadaire-priorites
```

#### Vérifier une page item

```bash
curl http://127.0.0.1:8787/life-noc/item/revue/revue-hebdomadaire-priorites
```

### 17.2 Cas fréquent : l’intrant change mais pas l’état dans Icinga

Cela signifie souvent qu’Icinga n’a pas encore refait le check.

Il faut alors :

- lancer un `Check Now` ;
- ou attendre le prochain check ;
- ou tester directement le plugin à la main.

### 17.3 Cas fréquent : route HTML absente après déploiement

Vérifier :

- que le service API tourne ;
- que le fichier déployé contient bien les routes HTML ;
- que les dépendances FastAPI sont installées, notamment `python3-multipart`.

---

## 18. QR codes — direction prévue

Life-NOC est conçu pour pouvoir pointer des QR codes vers des pages item.

Format visé :

```text
/life-noc/item/<domaine>/<item_key>
```

Le scan permettrait :

- d’ouvrir l’item ;
- de lire les instructions ;
- de confirmer l’action ;
- de mettre à jour le système facilement.

---

## 19. État actuel du projet

Le système a déjà validé en pratique :

- Icinga Web 2 fonctionnel ;
- BPM natif fonctionnel ;
- servicegroups fonctionnels ;
- `Check Now` fonctionnel ;
- store d’intrants séparé ;
- CLI des intrants ;
- API locale ;
- pages HTML d’item ;
- méthodes réelles `elapsed_time` et `days_until_due`.

---

## 20. Conclusion

Life-NOC dispose désormais d’un noyau opératoire réel.

Il ne s’agit plus seulement d’un concept ou d’une maquette.
Le système sait déjà :

- définir des suivis ;
- stocker des intrants ;
- évaluer des états ;
- exposer ces états ;
- fournir des instructions ;
- permettre l’action ;
- réintégrer cette action dans la supervision.

C’est la base d’un véritable système de pilotage personnel orienté action.