FabNum/Code
4
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs(evolution): spécifications FabNum v2 — brainstorming complet

Browse Source 
12 points d'évolution identifiés couvrant :
- Recentrage moteur + API + rôles (abandon Streamlit)
- Gestion rigoureuse des sources et modèle de données structuré
- Amorçage et qualification du corpus existant
- Refonte des fiches par templates (niveau × usage)
- Migration DOT → base de données graphe
- Validation du modèle de niveaux
- Services, sécurisation, profils de visibilité
- Multi-sectoriel, ressources transversales, géo fine
- Stocks et projection temporelle

Inclut : macro-planification (4 phases + horizon), MVP,
diagrammes d'architecture (globale, DAF, DAT, temporelle).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Stéphan Peccini 2026-04-02 16:52:41 +02:00
parent e77cb09bca
commit 302ab4524d
No known key found for this signature in database
8 changed files with 1215 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -7,6 +7,7 @@ __pycache__/
*.pyo
*.pyd
*.dot
!docs/*.dot
prompt.md
.gitignore

242
docs/EVOLUTIONS-PLANIFICATION.md Normal file
View File

@ -0,0 +1,242 @@
# FabNum — Planification macro
Vues synthétiques dérivées de [EVOLUTIONS.md](EVOLUTIONS.md).
**Date** : 2026-04-02
---
## 1. Présentation synthétique temporelle
```
T0 T1 T2 T3 Horizon
│ │ │ │ │
│ PHASE 1 │ PHASE 2 │ PHASE 3 │ PHASE 4 │
│ Fondations │ Modèle & Stockage │ Données & Sources │ Fiches & API │
│ │ │ │ │
│ ┌─────────────────┐ │ ┌─────────────────┐ │ ┌─────────────────┐ │ ┌───────────────┐ │ ┌──────────────┐
│ │ P7 Validation │ │ │ P3 Modèle de │ │ │ P2 Gestion des │ │ │ P5 Templates │ │ │ P10 Énergie │
│ │ niveaux (revue │→│ │ données │→│ │ sources (//P2 │→│ │ et génération │ │ │ et eau │
│ │ littérature) │ │ │ structuré │ │ │ dès phase 2) │ │ │ fiches │ │ │ │
│ └─────────────────┘ │ └─────────────────┘ │ └─────────────────┘ │ └───────────────┘ │ │ P11 Géo fine │
│ ┌─────────────────┐ │ ┌─────────────────┐ │ ┌─────────────────┐ │ ┌───────────────┐ │ │ │
│ │ P6 Spike techno │ │ │ P6 Implém. │ │ │ P4 Amorçage │ │ │ P1 API REST │ │ │ P9 Multi- │
│ │ base données │ │ │ stockage retenu │ │ │ 3M+1C+1PF │ │ │ + rôles │ │ │ sectoriel │
│ │ (Docker/serveur)│ │ │ │ │ │ + audit exhaust. │ │ │ │ │ └──────────────┘
│ └─────────────────┘ │ └─────────────────┘ │ └─────────────────┘ │ ├───────────────┤ │
│ │ │ │ │ P8 Services, │ │
│ │ │ │ │ sécu, profils │ │
│ ║ │ ║ │ ║ │ └───────────────┘ │
│ parallèle │ séquentiel │ P2 // dès Ph.2 │ │
│ │ │ │ │
├─────────────────────┼─────────────────────┼─────────────────────┤ │
│ MVP = Phases 1+2+3 │ │ │
└─────────────────────┴─────────────────────┴─────────────────────┘ │
```
**Légende** : M = minerai, C = composant, PF = produit final, // = parallèle
---
## 2. Macro-DAF (Diagramme d'Activités Fonctionnel)
Vue par **fonctions métier** — ce que fait le système, pour qui, et dans quel ordre.
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ FABNUM — ACTIVITÉS FONCTIONNELLES │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F1. MODÉLISER LA CHAÎNE DE VALEUR │ │
│ │ ├─ F1.1 Valider les niveaux de décomposition (revue litt.) │ │
│ │ ├─ F1.2 Définir les intitulés génériques des niveaux │ │
│ │ ├─ F1.3 Définir les critères d'arrêt (profondeur) │ │
│ │ └─ F1.4 Gérer les chaînes principales et connexes │ │
│ │ Acteurs : Admin │ │
│ └──────────────┬───────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F2. STRUCTURER ET QUALIFIER LES DONNÉES │ │
│ │ ├─ F2.1 Spécifier les données (essentielles / informationnelles)│ │
│ │ ├─ F2.2 Définir le périmètre mesuré de chaque donnée │ │
│ │ ├─ F2.3 Identifier et catégoriser les sources │ │
│ │ ├─ F2.4 Attribuer les tiers de confiance (par source/domaine) │ │
│ │ ├─ F2.5 Qualifier les données (filtres qualité) │ │
│ │ ├─ F2.6 Arbitrer les divergences entre sources │ │
│ │ └─ F2.7 Calculer l'indice de fiabilité par donnée │ │
│ │ Acteurs : Admin │ │
│ └──────────────┬───────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F3. SURVEILLER ET MAINTENIR │ │
│ │ ├─ F3.1 Veiller sur les sources (huginn) │ │
│ │ ├─ F3.2 Détecter les variations anormales (alertes) │ │
│ │ ├─ F3.3 Contrôler les citations/affirmations (verify-citations)│ │
│ │ ├─ F3.4 Historiser les données et les indices │ │
│ │ └─ F3.5 Auditer l'exhaustivité des minerais │ │
│ │ Acteurs : Admin (gouvernance), Services internes (automatisé) │ │
│ └──────────────┬───────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F4. CALCULER LES INDICES DE CRITICITÉ │ │
│ │ ├─ F4.1 Calculer IHH, ICS, IVC, ISG (+ futurs : eau, énergie) │ │
│ │ ├─ F4.2 Pré-calculer à chaque mise à jour du graphe │ │
│ │ ├─ F4.3 Calculer les méta-indices dynamiques (sur sélection) │ │
│ │ └─ F4.4 Rétro-analyser sur des crises passées (backtesting) │ │
│ │ Acteurs : Services internes (automatisé) │ │
│ └──────────────┬───────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F5. PRODUIRE LES FICHES │ │
│ │ ├─ F5.1 Générer depuis les données via templates │ │
│ │ ├─ F5.2 Adapter par niveau (minerai, composant, opération...) │ │
│ │ └─ F5.3 Adapter par usage (expertise, synthèse, API/JSON) │ │
│ │ Acteurs : Services internes (automatisé) │ │
│ └──────────────┬───────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F6. EXPOSER ET SERVIR │ │
│ │ ├─ F6.1 Requêtage du graphe (expert / simplifié) │ │
│ │ ├─ F6.2 Consultation des fiches (tous formats) │ │
│ │ ├─ F6.3 Analyse de vulnérabilité et scénarios │ │
│ │ ├─ F6.4 Export (PDF, JSON, DOT) │ │
│ │ ├─ F6.5 Personnalisation client (projection SI) │ │
│ │ └─ F6.6 Intégration écosystème veille 360° │ │
│ │ Acteurs : Expert, Service, COMEX, Métiers, DSI │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ F7. SÉCURISER ET CONTRÔLER (transversal)│ │
│ │ ├─ F7.1 Authentifier (utilisateur / clé API) │ │
│ │ ├─ F7.2 Autoriser par rôle (admin, expert, service) │ │
│ │ ├─ F7.3 Filtrer par profil de visibilité │ │
│ │ ├─ F7.4 Rate limiting │ │
│ │ └─ F7.5 Monitoring / observabilité │ │
│ │ Acteurs : Admin (configuration), Système (exécution) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
Flux principal : F1 → F2 → F3 → F4 → F5 → F6
F3 tourne en continu (veille)
F4 se déclenche à chaque mise à jour du graphe
F7 est transversal à F5 et F6
```
---
## 3. Macro-DAT (Diagramme d'Activités Technique)
Vue par **composants techniques** — ce qu'il faut construire et comment ça s'articule.
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ FABNUM — ARCHITECTURE TECHNIQUE │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ COUCHE STOCKAGE │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌───────────────────────────┐ │ │
│ │ │ Base graphe │ │ Historisation │ │ │
│ │ │ (Neo4j / PG+AGE │ │ (snapshots horodatés │ │ │
│ │ │ / ArangoDB) │ │ données + indices) │ │ │
│ │ │ │ │ │ │ │
│ │ │ • Nœuds (N0-N12)│ │ • Versions des données │ │ │
│ │ │ • Arêtes + attrs│ │ • Versions des indices │ │ │
│ │ │ • Multi-graphes │ │ • Audit trail │ │ │
│ │ │ • Schéma évolutif│ │ │ │ │
│ │ └────────┬─────────┘ └─────────────┬─────────────┘ │ │
│ └───────────┼──────────────────────────┼────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ COUCHE MOTEUR │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ │
│ │ │ Calcul │ │ Arbitrage │ │ Qualification │ │ │
│ │ │ indices │ │ sources │ │ données │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • IHH, ICS │ │ • Tier 1 win │ │ • Filtres │ │ │
│ │ │ • IVC, ISG │ │ • Convergence│ │ qualité │ │ │
│ │ │ • Méta-ind. │ │ • Alertes │ │ • Indice de │ │ │
│ │ │ • Extensible │ │ • Seuils │ │ fiabilité │ │ │
│ │ └──────────────┘ └──────────────┘ └───────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │ │
│ │ │ Requêtage │ │ Génération │ │ Import/Export │ │ │
│ │ │ graphe │ │ fiches │ │ │ │ │
│ │ │ │ │ │ │ • DOT (legacy)│ │ │
│ │ │ • Chemins │ │ • Templates │ │ • JSON │ │ │
│ │ │ • Filtrage │ │ niveau× │ │ • PDF │ │ │
│ │ │ • Sous-graphe│ │ usage │ │ • Backup/ │ │ │
│ │ │ • Projection │ │ • Rendu MD/ │ │ restore │ │ │
│ │ │ SI client │ │ JSON/PDF │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └───────────────┘ │ │
│ └────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────┴────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────────────────┐ │
│ │ SERVICES INTERNES │ │ API REST │ │
│ │ (non exposés) │ │ (point d'accès unique) │ │
│ │ │ │ │ │
│ │ ┌───────────────┐ │ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Veille huginn │ │ │ │ Auth │ │ Rate │ │ │
│ │ │ sources │ │ │ │ + rôles │ │ limiting │ │ │
│ │ ├───────────────┤ │ │ ├────────────┤ ├────────────┤ │ │
│ │ │ Vérification │ │ │ │ Profils │ │ Monitoring │ │ │
│ │ │ citations │ │ │ │ visibilité │ │ logging │ │ │
│ │ ├───────────────┤ │ │ └────────────┘ └────────────┘ │ │
│ │ │ Recalcul │ │ │ │ │
│ │ │ indices │ │ │ Endpoints : │ │
│ │ ├───────────────┤ │ │ • /graphe/* (requêtage) │ │
│ │ │ Alertes │ │ │ • /fiches/* (consultation) │ │
│ │ │ (variations, │ │ │ • /analyse/* (vulnérabilités) │ │
│ │ │ convergence) │ │ │ • /indices/* (méta-indices) │ │
│ │ └───────────────┘ │ │ • /export/* (PDF, JSON, DOT) │ │
│ └─────────────────────┘ │ • /admin/* (CRUD, scripts) │ │
│ └──────────────┬──────────────────┘ │
│ │ │
│ ┌───────────────────────────┬┴──────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ │
│ │ FRONTEND EXPERT │ │ SERVICES EXTERNES │ │ ÉCOSYSTÈME 360° │ │
│ │ (consomme l'API) │ │ (consomment l'API) │ │ (consomme l'API) │ │
│ │ │ │ │ │ │ │
│ │ • COMEX : synthèses│ │ • Génération IA │ │ • Veille strat. │ │
│ │ • Métiers : analyse│ │ rapports │ │ • IRON │ │
│ │ • DSI : dépend. SI│ │ • Agent local │ │ • Alertes │ │
│ │ │ │ client │ │ croisées │ │
│ └─────────────────────┘ └──────────────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ ADMIN (scripts) │ Accès direct au moteur + API /admin/* │
│ │ • CRUD graphe │ │
│ │ • Gestion sources │ │
│ │ • Tiers, arbitrage │ │
│ │ • Backup/restore │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────┘
Composants à construire par phase :
Phase 1 : Revue littérature (P7) + Spike base données (P6)
Phase 2 : Couche stockage + Moteur (calcul, arbitrage, qualification)
Phase 3 : Services internes (veille, vérification) + Import données
Phase 4 : API REST + Frontend expert + Génération fiches
```
---
## Dépendances critiques
```
P7 (niveaux) ──→ P3 (modèle) ──→ P6 impl (stockage) ──→ P4 (amorçage) ──→ P5 (fiches)
│
P6 spike ─────────────────────→ P6 impl ▼
P1 (API) ──→ P8 (services)
P2 (sources) ─────────────────────────────→ P4 (amorçage)
Parallélisations possibles :
• P7 // P6 spike (phase 1)
• P2 identification // P3 + P6 impl (phase 2→3)
```

485
docs/EVOLUTIONS.md Normal file
View File

@ -0,0 +1,485 @@
# FabNum — Evolutions envisagées
Document de brainstorming — capture les réflexions et décisions prises lors de la phase de conception.
**Date** : 2026-04-02
**Statut** : En cours de réflexion (quoi/pourquoi, pas encore le comment)
## Contraintes transversales
- **Budget : zéro en phase de démarrage** — tout est auto-hébergé et auto-financé. Briques technologiques open source et gratuites. Si le projet trouve son marché, cette contrainte sera réévaluée (ex : Neo4j Enterprise si justifié).
- **Vocation commerciale à terme** — FabNum est un outil de recherche aujourd'hui, un produit commercial demain si le marché est présent.
- **Big bang assumé** — peu d'utilisateurs actuels, deux environnements (prod/dev), possibilité de travailler en local. Pas de stratégie de migration progressive nécessaire.
- **Bus factor = 1** — développement assuré par Claude Code avec validation humaine. Qualité maintenue par outillage (ruff, SonarQube, skills quality-gate, linters IDE).
- **Équipe** — Stéphan : vision, arbitrage, validation des spécifications. Claude Code : conception technique, implémentation, agents spécialisés.
- **Intégration écosystème** — FabNum est un composant d'un écosystème plus large de veille stratégique 360° sur la polycrise. Il sera requêté par d'autres outils pour fournir des analyses et rapports.
- **Couplage** — FabNum se couple avec la méthodologie [IRON](https://conseil.peccini.fr/iron/) et le livre blanc "Voyage vers la robustesse".
- **Personas cibles** — COMEX (vision stratégique, synthèses), Métiers (analyse opérationnelle), DSI (dépendances SI).
- **Open source** — la question de ce qui sera open source (moteur, graphe des essentiels) reste à trancher.
- **Choix technologiques structurants** — base de données, framework API, frontend expert : à définir rapidement en début d'implémentation.
---
## Point 1 — Recentrage de FabNum : moteur + API + séparation des rôles
### Quoi
- **Retrait des modules IA embarqués** (batch_ia/, pgpt/, IA/, page ia_nalyse) : FabNum n'est plus responsable de la génération de rapports IA.
- **Exposition d'une API REST** : les capacités du moteur (graphe, indices de criticité, chemins critiques, filtrage) deviennent des endpoints consommables par des services externes.
- **Séparation en trois rôles** :
- **Admin** — gestion du graphe, des fiches, de la configuration
- **Expert** — analyse de criticité, visualisations, plan d'action
- **Service** — consommation de l'API par des services externes (ex : génération de rapports IA)
- Les rôles sont **assignables par utilisateur** et **cumulables** (un utilisateur peut être admin + expert).
### Pourquoi
- FabNum a plus de valeur en tant que **moteur d'analyse + interface experte** qu'en tant qu'application monolithique.
- Séparer le moteur de ses usages permet à d'autres services de consommer les mêmes données/calculs sans couplage.
- Les modules IA actuels sont peu testés (~1500 lignes exclues du linting) et leur évolution ne doit pas être liée à celle du moteur.
- Tous les experts ne seront pas administrateurs à terme : la gestion des droits est nécessaire.
**Distinction services internes / externes :**
- **Services internes** (côté moteur, non exposés via l'API) — veille sur les sources, mise à jour des données, vérification des affirmations, calcul des indices. Peuvent utiliser de l'IA, du Python, huginn.
- **Services externes** (exposés via l'API) — requêtage, consultation des fiches, analyse. L'API expose les résultats du moteur, pas ses processus internes.
### Décisions prises
- **Streamlit abandonné** — l'interface experte sera un frontend consommant l'API (un seul chemin d'accès aux données, pas deux).
- **Administration par scripts** — pas de frontend admin dédié, scripts + accès direct au moteur. Interface admin envisageable plus tard si le besoin se précise.
- **API-first** — architecture à un seul point d'accès pour tous les consommateurs (experts, services externes).
- Le système d'authentification actuel (connexion Gitea simple) devra évoluer pour supporter les rôles.
- Monitoring et observabilité de l'API : à traiter en implémentation, mentionné comme service d'administration.
---
## Point 2 — Gestion rigoureuse des sources de données
### Quoi
Les données (chiffres de production, parts de marché, réserves, projections) sont aujourd'hui enfouies dans le texte Markdown des fiches, sans existence structurée indépendante. Trois chantiers pour y remédier :
- **a. Identification et catégorisation des sources** — typer chaque source (rapport périodique, base de données, article académique, etc.), établir un lien explicite source ↔ donnée. Approche académique privilégiée (Scholar Gateway, Consensus).
- **b. Veille sur les sources** — service de surveillance pour détecter les mises à jour des sources (nouvelles éditions de rapports, apparition/disparition de sources). S'appuie sur un service huginn déjà actif pour un sujet connexe.
- **c. Contrôle strict citations/affirmations** — vérifier que chaque affirmation dans les fiches est effectivement contenue dans la ou les sources référencées. S'appuie sur le skill verify-citations existant (à faire évoluer).
### Pourquoi
- Les données générées par IA n'ont pas de traçabilité : on ne peut pas vérifier, mettre à jour ou contester une donnée individuellement.
- Les sources sont listées en vrac sans lien vers les données qu'elles justifient (ex : `12-sources.md`).
- Les rapports (USGS, Statista, etc.) sont mis à jour annuellement : sans veille, les données deviennent obsolètes silencieusement.
- La crédibilité de l'outil dépend de la rigueur des sources — approche académique nécessaire.
### Décisions prises
- Trois chantiers identifiés (sources, veille, contrôle) ; le modèle de données structuré et la génération des fiches seront traités dans des points séparés.
- Réutilisation de l'infrastructure huginn existante pour la veille.
- Évolution du skill verify-citations pour le contrôle des affirmations.
---
## Point 3 — Modèle de données structuré
### Quoi
Définir les spécifications de toutes les données nécessaires aux fiches et au moteur, organisées en deux niveaux :
- **Données essentielles** — celles qui alimentent les indices et le moteur d'analyse (productions, parts de marché, réserves, etc.)
- **Données informationnelles** — contexte, descriptions, projections — utiles aux fiches mais pas directement au calcul
Chaque donnée doit porter :
- Une **définition précise du périmètre mesuré** (ex : "extraction minière de lithium, hors raffinage, en tonnes de Li contenu")
- Des **liens explicites vers ses sources**, avec gestion de la multiplicité
- Les **dimensions de divergence** entre sources : valeur, temporalité, périmètre mesuré
Le modèle doit inclure un **système de tiers de confiance** pour les sources :
- Chaque source a un **tier** (niveau de fiabilité) assorti d'une **pondération** pour les arbitrages
- Le tier peut **varier selon le domaine** couvert (ex : une source tier 1 sur l'extraction peut être tier 2 sur le raffinage)
Des **scénarios d'arbitrage** doivent être spécifiés pour trancher quand les sources divergent :
- **Règle de base** : le tier 1 l'emporte par défaut.
- **Exception** : si N sources de tier inférieur convergent vers une autre valeur → alerte pour arbitrage humain.
- **Seuil de variation** : si une valeur évolue trop fortement entre deux mises à jour → alerte.
- **Principe directeur** : on travaille avec des estimations, pas des mesures exactes. La précision relative suffit.
Un **indice de fiabilité de la donnée** agrège plusieurs facteurs : granularité géographique disponible, tier de confiance de la source, ancienneté de la donnée, couverture du périmètre. Il permet à l'utilisateur de savoir à quel point il peut se fier à un résultat.
**Historisation** — chaque donnée, chaque valeur d'indice, chaque état du graphe est horodaté et conservé. Nécessaire pour la détection de tendances, les alertes de variation, et la rétro-analyse (backtesting des indices sur des crises passées : Spruce Pine, quotas chinois, etc.).
Les spécifications servent aussi de **cahier des charges pour la recherche de sources** : si une donnée essentielle n'a pas de source, on sait précisément ce qu'on cherche.
### Pourquoi
- Sans définition précise du périmètre, l'arbitrage entre sources divergentes n'a pas de sens.
- La multiplicité des sources est la norme, pas l'exception — le modèle doit la gérer nativement.
- Les spécifications permettent d'identifier les trous (données sans source) et de piloter la recherche.
### Contraintes de conception
- **Système ouvert et modulable** — de nouveaux indices sont prévus (eau, énergie, logistique). Le modèle ne doit pas câbler les 4 indices actuels (IHH, ICS, IVC, ISG) en dur.
- Le tier de confiance par domaine est une hypothèse à valider, mais le modèle doit pouvoir le supporter.
### Décisions prises
- Deux niveaux de données : essentielles (moteur) et informationnelles (fiches).
- Tier de confiance par source, variable selon le domaine, avec pondération pour l'arbitrage.
- Scénarios d'arbitrage automatisables (tier 1 par défaut, convergence → alerte).
- Indice de fiabilité par donnée (agrégation multi-facteurs).
- Historisation native de toutes les données et indices.
- **Gouvernance** : un seul rôle admin couvre toute la gouvernance (tiers, arbitrage, sources). Pas de segmentation tant qu'il n'y a pas d'équipe pour le justifier.
---
## Point 4 — Amorçage de la base avec le corpus existant
### Quoi
Alimenter la base de données structurée (point 3) à partir des fiches actuelles, puis utiliser ce jeu de données réel pour **tester en grandeur réelle** les processus des points 2 et 3 (sources, veille, contrôle citations, arbitrage).
- **Extraction des données** depuis les fiches Markdown existantes vers le modèle structuré (tout ou partie du corpus, périmètre à décider).
- **Raccordement affirmations ↔ sources** via une table de correspondance externe (sans modifier les fiches), même si certains liens seront des hypothèses.
- **Test d'évolution des sources** — exercer le cycle complet : détection de mise à jour d'une source, impact sur les données, arbitrage, propagation.
### Pourquoi
- Le corpus existant (~30+ minerais) constitue un terrain d'essai réel avec toutes ses imperfections (sources obsolètes, périmètres flous, données non vérifiées).
- Valider les processus sur des données imparfaites garantit qu'ils fonctionneront avec de meilleures sources.
- De nombreuses sources actuelles sont intéressantes et à conserver.
### Décisions prises
- **Qualification progressive** — chaque donnée et chaque source est passée au crible des filtres qualité (tier de confiance, vérification citation, périmètre). Ce qui passe est conservé comme donnée de référence, ce qui ne passe pas est remplacé ou supprimé. Ce n'est pas "test puis jeter", c'est un processus de qualification.
- Le périmètre d'amorçage (tout le corpus ou un sous-ensemble) reste à décider.
- Les fiches existantes ne sont pas modifiées à cette étape.
- Cet amorçage sert aussi de validation des chantiers précédents.
---
## Point 5 — Refonte des fiches : templates et génération
### Quoi
Les fiches ne sont plus rédigées manuellement ni générées en bloc par IA. Elles deviennent un **rendu généré** à partir des données structurées (point 3) via un système de templates.
- **Templates par niveau du graphe** — chaque niveau (minerai, composant, opération, pays, etc.) a ses sections propres, adaptées à la nature des données.
- **Templates par usage** — plusieurs rendus possibles pour un même niveau :
- **Expertise** — fiche complète avec toutes les sections, sources détaillées
- **Synthèse** — données essentielles uniquement, vue condensée
- **API/machine** — format structuré (JSON) pour les services externes
- La combinaison **niveau × usage** détermine le template appliqué.
- L'ordre et la composition des sections sont définis dans le template : modifier le template régénère les fiches en conséquence.
- Les sources sont intégrées nativement dans le rendu (rattachées aux données, pas listées en vrac).
### Pourquoi
- Le format actuel (narration Markdown avec sections numérotées) mélange structure et contenu, rendant les fiches difficiles à maintenir et à faire évoluer.
- Les fiches actuelles ne reflètent pas le mécanisme de sources structurées (points 2 et 3).
- Pouvoir changer l'ordre des sections ou le format de rendu sans toucher aux données est essentiel pour un outil qui doit servir différents profils (admin, expert, service).
### Décisions prises
- Génération des fiches depuis les données via templates (inversion du flux actuel).
- Deux axes de templates : par niveau du graphe et par usage.
- L'affichage est piloté par le modèle associé au contexte d'affichage.
---
## Point 6 — Stockage : du DOT vers une base de données
### Quoi
Remplacer le fichier DOT (Graphviz) comme stockage primaire du graphe par une **base de données** capable de supporter :
- Les données structurées rattachées aux nœuds et arêtes (indices, sources, tiers de confiance, périmètres)
- Le requêtage (filtrage par indice, par minerai, par pays, etc.)
- Un schéma évolutif (ajout d'indices eau, énergie, logistique sans refonte)
- Les rôles d'accès (point 1)
- L'exposition via API (point 1)
Le format DOT peut rester comme **format d'import/export** mais n'est plus le stockage de référence.
### Pourquoi
- Le DOT ne supporte pas le requêtage, la gestion de versions des données, ni les relations entre graphes.
- L'ajout d'un indice ou d'un attribut implique aujourd'hui de modifier le parsing du DOT.
- Les évolutions prévues (multi-graphes, sources structurées, API) dépassent les capacités du format fichier.
### Contexte : architecture multi-graphes (à détailler dans un point futur)
Le graphe unique actuel (4 niveaux, chaîne minerai → produit final) sera complété par :
- **Chaînes connexes** — dépendances indirectes nécessaires à la fabrication mais non constitutives du produit (ex : quartz ultra-pur → creuset → wafer).
- **Chaînes de composants détaillés** — un composant (résistance, condensateur) a sa propre chaîne de valeur complète, connectée au graphe principal via un lien au nœud composant.
Cette architecture composable permet de gérer la complexité sans surcharger le graphe principal : on "zoome" sur un composant en suivant le lien vers sa chaîne dédiée. La base de données doit supporter nativement cette interconnexion de graphes.
### Décisions prises
- Le DOT n'est plus le stockage primaire.
- Le choix technologique (base graphe type Neo4j Community, PostgreSQL+AGE, ArangoDB, ou autre) reste ouvert. Toutes les options sont open source.
- **Backup** : stratégie de sauvegarde à définir, mais simplifiée par la cadence d'évolution modérée du graphe.
- **Cadence de mise à jour** : mensuelle au démarrage (pour roder le workflow), puis trimestrielle une fois stabilisé. Alertes veille hors cadence pour les événements critiques.
- L'architecture multi-graphes (essentiel/connexe) est identifiée comme point futur à part entière.
---
## Point 7 — Validation du modèle de niveaux
### Quoi
Revoir et valider les niveaux de décomposition de la chaîne de valeur. Deux axes de réflexion :
- **Les étapes de la chaîne (axe vertical)** — les niveaux actuels (Extraction, Réserves, Traitement, Fabrication, Assemblage) ne sont pas universels. Certains minerais sautent des étapes (hélium : pas de raffinage), d'autres ne sont pas des minerais classiques (dérivés pétroliers). Piste privilégiée : des **intitulés génériques** (ex : "Transformation primaire" plutôt que "Raffinage") pour que tous les matériaux se positionnent aux mêmes niveaux, facilitant la comparaison et le requêtage.
- **La profondeur des dépendances (axe horizontal)** — jusqu'où remonte-t-on ? L'excavatrice qui extrait le minerai a sa propre chaîne de valeur. Critère d'arrêt : si une partie du graphe réel est identifiée comme pertinente, elle est intégrée en **chaîne connexe** (cf. point 6) sous forme de graphe minimum associé au bon niveau.
### Méthode de validation
La validation doit être **argumentée**, par au moins une des approches suivantes :
- **Revue de littérature** — benchmark avec les modèles de chaînes d'approvisionnement existants, incluant les standards du domaine (SCOR model, ISO 28000, Open Supply Hub, Responsible Minerals Initiative).
- **Démonstration par les marges d'erreur** — montrer qu'avec les niveaux d'erreur cumulés le long de la chaîne, ajouter des niveaux n'améliorerait pas la précision des résultats.
### Pourquoi
- Le modèle de niveaux conditionne toute la structure du graphe, les indices, les templates de fiches et l'API.
- Un modèle mal calibré (trop simple ou trop détaillé) compromet soit la pertinence soit l'utilisabilité.
- La crédibilité scientifique du projet nécessite des choix de modélisation justifiés.
### Questions ouvertes
- Quels intitulés génériques pour les niveaux ? (à définir après revue de littérature)
- Le nombre de niveaux doit-il être fixe ou configurable par chaîne ?
---
## Point 8 — Services, sécurisation et profils de visibilité
### Quoi
Définir les services exposés par l'API, leur sécurisation et les niveaux de visibilité.
**Familles de services identifiées :**
- **Requêtage du graphe** — chemins critiques, filtrage, sous-graphes. Deux niveaux : expert (complet) et simplifié (clients).
- **Méta-indices dynamiques** — indices agrégés calculés sur un sous-graphe sélectionné (ex : IHH agrégé de la chaîne cobalt → smartphones). Les indices de base sont pré-calculés à chaque mise à jour du graphe et servis comme données.
- **Analyse** — vulnérabilités, comparaison de scénarios. Deux niveaux (expert / simplifié).
- **Administration** — CRUD graphe, gestion des sources, import/export (rôle admin uniquement).
- **Données structurées** — fiches (tous templates/usages), données brutes, sources associées.
- **Génération** — rapports, exports (PDF, JSON, DOT) — consommateurs externes.
- **Personnalisation client** — un client fournit son SI / sa nomenclature, on le projette sur le graphe FabNum pour obtenir :
- Sa carte de risques propre (minerais critiques pour *son* SI)
- De la veille/alertes ciblées sur *ses* dépendances
- Des rapports contextualisés
**Sécurisation :**
- **Authentification** — utilisateur (Streamlit) vs service externe (clé API / token).
- **Autorisation par rôle** (admin, expert, service) — cf. point 1.
- **Profils de visibilité** — complémentaires aux rôles, définissent *ce qu'on peut voir* :
- Chaîne principale seule vs chaîne + connexes
- Tous les indices vs un sous-ensemble
- Graphe complet vs sous-graphe filtré
- Profils prédéfinis (ex : gratuit/standard/complet) ou sur mesure par client
- **Rate limiting** — protection du moteur contre les abus.
- **Monitoring / observabilité** — logging structuré, métriques, alerting (service d'administration).
**Données client et RGPD :**
- **Principe : moteur stateless côté client** — le client envoie son SI, le moteur croise avec le graphe, renvoie le résultat, rien ne persiste sur le serveur. Faisabilité à valider selon les traitements (veille ciblée → nécessite potentiellement du stockage).
- **Alternative : agent local chez le client** — un agent déployé côté client consomme l'API et stocke les résultats localement. Les données client ne quittent jamais leur périmètre.
- **Action manuelle** — export/import pour les cas simples.
- **RGPD** — à garder à l'esprit pour la phase commerciale.
**Documentation utilisateur :**
- Prématurée mais importante. À produire quand le système sera stabilisé (API, fiches, services).
### Pourquoi
- L'API sans services définis et sécurisés est inutilisable.
- La personnalisation client transforme FabNum d'un outil générique en **plateforme de services à valeur ajoutée**.
- Les profils de visibilité permettent de proposer des niveaux de service différenciés et de protéger les données sensibles.
### Décisions prises
- Les indices de base sont pré-calculés (pas de service de calcul à la volée), sauf les méta-indices dynamiques sur sélection.
- La personnalisation client (projection de SI sur le graphe) est identifiée comme service à forte valeur.
- Rôles (ce qu'on peut faire) et profils (ce qu'on peut voir) sont deux axes distincts.
- Moteur stateless côté données client (objectif), agent local client ou export manuel comme alternatives.
---
## Point 9 — Multi-sectoriel et architecture des graphes
### Quoi
FabNum ne se limite pas nécessairement au numérique. Le moteur pourrait servir d'autres secteurs (embarqué, automobile, énergie...) avec la même mécanique.
- Chaque **secteur** a son graphe principal (sa chaîne de valeur propre).
- Les secteurs peuvent devenir des **connexes les uns des autres** (l'embarqué est un connexe de l'automobile ; le numérique est un connexe de l'embarqué).
- Les **minerais sont partagés** entre les graphes — le cobalt apparaît dans le numérique, l'automobile et l'embarqué.
- Le moteur reste le même, seuls les graphes et leurs interconnexions changent.
Ce point englobe et généralise la réflexion essentiel/connexe mentionnée au point 6.
### Pourquoi
- L'architecture multi-graphes (point 6) prend tout son sens à l'échelle multi-sectorielle.
- Les minerais critiques sont par nature transversaux — les analyser secteur par secteur sans voir les interdépendances est réducteur.
- Ça renforce le besoin d'un modèle de niveaux générique (point 7) et d'une base de données capable de gérer ces relations (point 6).
### Décisions prises
- La vision multi-sectorielle est retenue comme horizon, pas comme priorité immédiate.
- L'architecture doit la rendre possible sans la requérir dès le départ.
---
## Point 10 — Intégration des ressources transversales (énergie, eau)
### Quoi
Énergie et eau ne sont pas des niveaux de la chaîne de valeur mais des **ressources transversales** consommées à chaque opération (extraction, transformation, fabrication, assemblage). Il faut :
- Définir **comment les modéliser** dans le graphe — attributs d'opération, nœuds de ressource connectés aux opérations, ou autre approche.
- Résoudre le **problème de granularité** — il faut pouvoir rattacher la consommation au bon niveau de chaque opération, avec une dimension géographique (disponibilité eau/énergie par pays).
- Travailler sur le **sourçage** de données aujourd'hui parcellaires — les consommations énergétiques et hydriques par opération et par pays sont mal documentées. Il faudra probablement travailler avec des fourchettes et estimations, en s'appuyant sur le système de tiers de confiance (point 3).
L'objectif est de pouvoir détecter des **croisements de risques** : pays instable (ISG) + stress hydrique + concentration d'une opération (IHH) = alerte.
### Pourquoi
- L'énergie est un facteur de risque majeur et croissant (cf. détroit d'Ormuz et impact sur la chaîne numérique : [Impact du détroit d'Ormuz sur la chaîne numérique](https://conseil.peccini.fr/articles/impact-ormuz-chaine-numerique/)).
- L'eau est un facteur de risque émergent, en particulier pour l'extraction et la transformation (lithium au Chili, semi-conducteurs à Taïwan).
- Sans ces données, le modèle est aveugle à des scénarios de rupture réalistes.
### Difficultés identifiées
- Données très parcellaires — pas de base de données globale "consommation énergie/eau par opération minière par pays".
- Granularité hétérogène des sources (données pays vs données site vs données sectorielles).
- Les données devront être intégrées progressivement, au fur et à mesure de leur disponibilité.
### Décisions prises
- Identifié comme chantier nécessaire mais difficile — la réflexion sur le sourçage et la modélisation est à mener.
- Le modèle de données (point 3) et la base de données (point 6) doivent être conçus pour accueillir ces ressources transversales, même si les données ne sont pas disponibles immédiatement.
---
## Point 11 — Granularité géographique fine et risques climatiques
### Quoi
Passer d'une géographie au niveau pays à une **localisation fine des opérations** (région, province, site) pour croiser avec des données de risques climatiques et environnementaux (stress hydrique, inondation, canicule, sécheresse).
- **Localisation fine des opérations** — identifier où se trouvent physiquement les sites de production, et idéalement la part de production de chaque site.
- **Croisement avec des données de risques** — stress hydrique (WRI Aqueduct, données ouvertes), risques d'inondation/canicule (ND-GAIN), événements historiques.
- **Alertes contextualisées** — un événement climatique dans une zone → alerte automatique sur les opérations concernées (lien avec la veille, point 2b).
**Niveaux d'approximation envisagés :**
| Niveau | Granularité | Données nécessaires | Faisabilité |
| --- | --- | --- | --- |
| 1 | Pays | Risque climatique moyen pays | Disponible (ISG actuel) |
| 2 | Région/province | Données climatiques régionales | Faisable (WRI Aqueduct, ND-GAIN) |
| 3 | Site exact + part de production | Géolocalisation + répartition production | Difficile, partiel |
Le niveau 3 ne sera pas atteignable pour tous les opérateurs, mais peut l'être pour les **nœuds les plus critiques** — ceux à IHH élevé où un incident aurait un impact systémique (exemples : Spruce Pine pour le quartz ultra-pur, Bayan Obo pour les terres rares, triangle du lithium).
### Pourquoi
- Spruce Pine (2024) : une seule mine de quartz ultra-pur, un ouragan, et toute la chaîne des semi-conducteurs menacée.
- 40% des nouvelles fabs de semi-conducteurs sont construites dans des zones en stress hydrique.
- Le risque climatique au niveau pays est trop grossier — la Chine a des zones arides et des zones inondables, un risque moyen pays n'a pas de sens.
- L'utilité est certaine ; c'est la faisabilité du sourçage qui doit être évaluée.
### Difficultés identifiées
- **Opacité** — les opérateurs (surtout chinois et petits producteurs) ne publient pas toujours la localisation de leurs sites.
- **Répartition de production** — même quand on connaît les sites d'un opérateur, la part de chaque site dans sa production totale est rarement publique.
- **Hétérogénéité des sources** — données de géolocalisation minière (S&P Global, USGS mineral facilities) vs données climatiques (WRI, ND-GAIN) vs rapports annuels d'entreprises — formats et granularités différents.
### Décisions prises
- L'utilité est validée, la faisabilité est à évaluer.
- Approche par niveaux d'approximation — on ne vise pas le niveau 3 partout, mais en priorité sur les nœuds critiques (IHH élevé, impact systémique).
- Lien fort avec la veille (point 2b) pour les alertes événementielles.
---
## Point 12 — Stocks et projection temporelle
### Quoi
Intégrer les **niveaux de stock** comme donnée du graphe pour permettre des **scénarios de projection temporelle** : en cas de rupture d'approvisionnement, estimer le délai d'impact le long de la chaîne de valeur.
- **Stock comme attribut de nœud** — chaque nœud pertinent (opération, composant) porte une estimation de stock (en mois de consommation, tonnes, unités).
- **Moteur de projection** — simulation de rupture à un point du graphe et propagation temporelle : "la Chine coupe le germanium → les fibres optiques sont impactées dans X mois, les serveurs dans Y mois".
- **Scénarios what-if** — un service de calcul dynamique, pas juste une requête sur le graphe.
### Pourquoi
- Passe FabNum de l'analyse **statique** (photo de la criticité à un instant T) à l'analyse **dynamique** (projection temporelle en cas de rupture).
- Valeur très forte pour les clients : "votre SI dépend du germanium via les fibres optiques, vous avez ~8 mois avant impact en cas de coupure chinoise".
- Les crises récentes (quotas chinois, Spruce Pine) montrent que le délai d'impact est une information critique pour la prise de décision.
### Difficultés identifiées
- **Données extrêmement sensibles** — les niveaux de stock sont la donnée la plus confidentielle pour les entreprises. Quasiment jamais publiée.
- **Niveau de confiance faible** — on travaillera avec des estimations sectorielles, des moyennes, des fourchettes. L'indice de fiabilité (point 3) sera particulièrement bas sur ces données.
- **Variabilité rapide** — les stocks évoluent beaucoup plus vite que les parts de marché. La cadence trimestrielle pourrait ne pas suffire pour cette donnée.
### Décisions prises
- Point identifié comme horizon — forte valeur, faisabilité difficile (sourçage).
- Le stock est un attribut de nœud comme les autres — pas de refonte du modèle de données.
- Le moteur de projection est un nouveau service de calcul à spécifier.
---
## Ordre de réalisation logique
L'ordre des points dans ce document reflète l'ordre de la discussion, pas l'ordre de réalisation. L'analyse des dépendances donne :
**Phase 1 — Fondations (parallélisable) :**
- **Point 7** — Validation du modèle de niveaux (fondation théorique, prérequis au modèle de données)
- **Point 6 (spike)** — Spike technique sur 2-3 bases candidates (Neo4j Community, PostgreSQL+AGE, ArangoDB) avec un mini-graphe de test. En parallèle du point 7 car les critères de sélection (multi-graphes, schéma évolutif, requêtage, historisation, open source) sont indépendants du nombre exact de niveaux. Tests sur le serveur via Docker (16 Go RAM), installation native ensuite.
**Phase 2 — Modèle et stockage :**
1. **Point 3** — Modèle de données structuré (dépend des niveaux validés). Énergie et eau ne nécessitent pas de modélisation spéciale — ce sont des attributs d'opération comme les parts de marché, couverts nativement par le modèle extensible.
2. **Point 6 (implémentation)** — Mise en place du stockage retenu après le spike.
**Phase 3 — Données et sources :**
1. **Point 2** — Gestion des sources (peut démarrer en parallèle dès la phase 2 pour l'identification/catégorisation)
2. **Point 4** — Amorçage et qualification sur un échantillon représentatif : 3 minerais + 1 composant + 1 produit final (couvre tous les niveaux du graphe). Puis audit d'exhaustivité des minerais après l'amorçage.
**Phase 4 — Fiches et API :**
1. **Point 5** — Templates et génération des fiches
2. **Point 1** — API REST et rôles
3. **Point 8** — Services, sécurisation, profils (sous-spécification dédiée pour la personnalisation client)
*Horizon (l'architecture doit les rendre possibles sans les implémenter d'emblée) :*
- **Point 10** — Ressources transversales (énergie, eau)
- **Point 11** — Granularité géographique fine
- **Point 9** — Multi-sectoriel
## MVP (jalon interne)
**Définition** : moteur fonctionnel avec données réelles dans une vraie base, requêtable, données sourcées avec indice de fiabilité. Pas de frontend, pas de produit fini — un jalon de validation interne.
**Périmètre** : phases 1 + 2 + 3 (validation niveaux → spike techno → modèle de données → base → amorçage 3 minerais + 1 composant + 1 produit final).
**Critère de succès** : on peut requêter la base et retrouver les mêmes analyses qu'aujourd'hui (ex : Sankey du germanium), avec des données sourcées et un indice de fiabilité.
**Rétro-analyse** : valider les indices sur des crises passées (Spruce Pine, quotas chinois) comme preuve de concept.
**Tests** : toute logique métier est testée (calculs d'indices, requêtage, arbitrage des sources, import/export). Pas de seuil de couverture arbitraire — on teste ce qui compte.

124
docs/architecture-globale.dot Normal file
View File

@ -0,0 +1,124 @@
digraph architecture_fabnum {
// Configuration générale
rankdir=TB;
fontname="Arial";
fontsize=18;
label="FabNum — Architecture globale\n\n";
labelloc=t;
splines=true;
nodesep=0.8;
ranksep=1.0;
node [fontname="Arial", fontsize=12, style="filled,rounded", shape=box, penwidth=1.5];
edge [fontname="Arial", fontsize=10, penwidth=1.5];
// ==================== UTILISATEURS ====================
admin [
label="Administrateur\n\nGère le graphe, les sources,\nles tiers de confiance\net les arbitrages"
fillcolor="#FFE082"
shape=house
fontsize=11
];
expert [
label="Expert\n\nAnalyse les risques,\nqualifie les données,\nalimente la connaissance"
fillcolor="#A5D6A7"
shape=house
fontsize=11
];
client [
label="Client\n(COMEX, Métiers, DSI)\n\nConsulte les analyses,\nles fiches, les alertes.\nPeut contextualiser\nses requêtes."
fillcolor="#EF9A9A"
shape=house
fontsize=11
];
ecosysteme [
label="Écosystème\nveille 360°\n\nInterroge FabNum\net alimente\nles sources"
fillcolor="#CE93D8"
shape=house
fontsize=11
];
// ==================== API ====================
api [
label="API\n\nPoint d'accès unique\nAuthentification, rôles,\nprofils de visibilité"
fillcolor="#B39DDB"
fontsize=12
penwidth=2
];
// ==================== MOTEUR ====================
moteur [
label="Moteur FabNum\n\nCalcul des indices (IHH, ICS, IVC, ISG...)\nRequêtage du graphe, chemins critiques\nGénération des fiches (templates)\nArbitrage des sources"
fillcolor="#90CAF9"
fontsize=12
penwidth=2
];
// ==================== BASE DE DONNÉES ====================
bdd [
label="Base de données\n(graphe)\n\nNœuds, relations, indices\nSources rattachées\nHistorique des données"
fillcolor="#80CBC4"
fontsize=12
penwidth=2
];
// ==================== VEILLE ====================
veille [
label="Veille\n\nSurveillance des sources (huginn)\nVérification des citations\nAlertes (variations, événements)"
fillcolor="#FFAB91"
fontsize=12
penwidth=2
];
// ==================== SOURCES ====================
sources [
label="Sources externes\n\nUSGS, Statista, BRGM,\nScholar Gateway, Consensus,\nWRI Aqueduct, ND-GAIN..."
fillcolor="#E0E0E0"
shape=cylinder
fontsize=11
];
// ==================== DISPOSITION ====================
{ rank=same; admin; expert; client; ecosysteme; }
{ rank=same; veille; moteur; }
// ==================== RELATIONS ====================
// Expert → API
expert -> api [label="consulte\nanalyse", color="#2E7D32"];
// Client → API
client -> api [label="consulte\nles résultats", color="#C62828"];
// Écosystème ↔ API + Sources (bidirectionnel)
ecosysteme -> api [label="requête\nanalyses", color="#6A1B9A"];
ecosysteme -> sources [label="alimente\nles sources", color="#6A1B9A", style=dashed];
// Admin → Moteur (accès direct par scripts, pas via API)
admin -> moteur [label="administre\n(scripts)", color="#E65100", style=bold, penwidth=2];
// API ↔ Moteur
api -> moteur [label="transmet\nles requêtes", color="#4527A0", dir=both];
// Moteur ↔ Base de données
moteur -> bdd [label="lit et écrit\nles données", color="#00695C", dir=both];
// Veille → Sources
sources -> veille [label="surveille\nles mises à jour", color="#BF360C"];
// Veille → Moteur / BDD
veille -> moteur [label="signale les\nchangements\net vérifie\nles citations", color="#E65100"];
veille -> bdd [label="met à jour\nles sources", color="#E65100", style=dashed];
// Sources → BDD (alimentation)
sources -> bdd [label="alimente\nles données", color="#546E7A", style=dashed];
}

BIN
docs/architecture-globale.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 392 KiB

124
docs/macro-daf.dot Normal file
View File

@ -0,0 +1,124 @@
digraph macro_daf {
rankdir=TB;
fontname="Arial";
node [fontname="Arial", fontsize=10, style=filled, shape=record];
edge [fontname="Arial", fontsize=9];
label="FabNum — Macro-DAF (Diagramme d'Activités Fonctionnel)\n\n";
labelloc=t;
fontsize=16;
compound=true;
// Fonctions métier — flux principal
subgraph cluster_F1 {
label="F1. MODÉLISER LA CHAÎNE DE VALEUR";
style=filled; color="#E3F2FD"; fontsize=12; fontcolor="#1565C0";
F1_1 [label="F1.1\nValider les niveaux\nde décomposition", fillcolor="#BBDEFB"];
F1_2 [label="F1.2\nDéfinir les intitulés\ngénériques", fillcolor="#BBDEFB"];
F1_3 [label="F1.3\nDéfinir les critères\nd'arrêt (profondeur)", fillcolor="#BBDEFB"];
F1_4 [label="F1.4\nGérer chaînes\nprincipales / connexes", fillcolor="#BBDEFB"];
F1_1 -> F1_2 -> F1_3 -> F1_4;
acteur_F1 [label="Acteur : Admin", shape=ellipse, fillcolor="#E3F2FD", fontsize=9];
}
subgraph cluster_F2 {
label="F2. STRUCTURER ET QUALIFIER LES DONNÉES";
style=filled; color="#E8F5E9"; fontsize=12; fontcolor="#2E7D32";
F2_1 [label="F2.1\nSpécifier données\n(essentielles / info)", fillcolor="#C8E6C9"];
F2_2 [label="F2.2\nDéfinir périmètre\nmesuré", fillcolor="#C8E6C9"];
F2_3 [label="F2.3\nIdentifier et catégoriser\nles sources", fillcolor="#C8E6C9"];
F2_4 [label="F2.4\nAttribuer tiers\nde confiance", fillcolor="#C8E6C9"];
F2_5 [label="F2.5\nQualifier données\n(filtres qualité)", fillcolor="#C8E6C9"];
F2_6 [label="F2.6\nArbitrer divergences\nentre sources", fillcolor="#C8E6C9"];
F2_7 [label="F2.7\nCalculer indice\nde fiabilité", fillcolor="#C8E6C9"];
F2_1 -> F2_2 -> F2_3 -> F2_4 -> F2_5 -> F2_6 -> F2_7;
acteur_F2 [label="Acteur : Admin", shape=ellipse, fillcolor="#E8F5E9", fontsize=9];
}
subgraph cluster_F3 {
label="F3. SURVEILLER ET MAINTENIR";
style=filled; color="#FFF3E0"; fontsize=12; fontcolor="#E65100";
F3_1 [label="F3.1\nVeiller sur\nles sources\n(huginn)", fillcolor="#FFE0B2"];
F3_2 [label="F3.2\nDétecter variations\nanormales (alertes)", fillcolor="#FFE0B2"];
F3_3 [label="F3.3\nContrôler\ncitations", fillcolor="#FFE0B2"];
F3_4 [label="F3.4\nHistoriser données\net indices", fillcolor="#FFE0B2"];
F3_5 [label="F3.5\nAuditer exhaustivité\ndes minerais", fillcolor="#FFE0B2"];
F3_1 -> F3_2;
F3_3 -> F3_4;
acteur_F3 [label="Acteurs : Admin (gouv.)\nServices internes (auto.)", shape=ellipse, fillcolor="#FFF3E0", fontsize=9];
}
subgraph cluster_F4 {
label="F4. CALCULER LES INDICES DE CRITICITÉ";
style=filled; color="#FCE4EC"; fontsize=12; fontcolor="#C62828";
F4_1 [label="F4.1\nCalculer IHH, ICS\nIVC, ISG\n(+ futurs)", fillcolor="#F8BBD0"];
F4_2 [label="F4.2\nPré-calculer à\nchaque MAJ graphe", fillcolor="#F8BBD0"];
F4_3 [label="F4.3\nMéta-indices\ndynamiques\n(sur sélection)", fillcolor="#F8BBD0"];
F4_4 [label="F4.4\nRétro-analyser\n(backtesting)", fillcolor="#F8BBD0"];
F4_1 -> F4_2;
F4_3 -> F4_4 [style=dashed];
acteur_F4 [label="Acteur : Services internes", shape=ellipse, fillcolor="#FCE4EC", fontsize=9];
}
subgraph cluster_F5 {
label="F5. PRODUIRE LES FICHES";
style=filled; color="#F3E5F5"; fontsize=12; fontcolor="#6A1B9A";
F5_1 [label="F5.1\nGénérer depuis\ndonnées via templates", fillcolor="#E1BEE7"];
F5_2 [label="F5.2\nAdapter par niveau\n(minerai, composant...)", fillcolor="#E1BEE7"];
F5_3 [label="F5.3\nAdapter par usage\n(expertise, synthèse,\nAPI/JSON)", fillcolor="#E1BEE7"];
F5_1 -> F5_2 -> F5_3;
acteur_F5 [label="Acteur : Services internes", shape=ellipse, fillcolor="#F3E5F5", fontsize=9];
}
subgraph cluster_F6 {
label="F6. EXPOSER ET SERVIR";
style=filled; color="#E0F2F1"; fontsize=12; fontcolor="#00695C";
F6_1 [label="F6.1\nRequêtage graphe\n(expert / simplifié)", fillcolor="#B2DFDB"];
F6_2 [label="F6.2\nConsultation\nfiches", fillcolor="#B2DFDB"];
F6_3 [label="F6.3\nAnalyse vulnérabilité\net scénarios", fillcolor="#B2DFDB"];
F6_4 [label="F6.4\nExport\n(PDF, JSON, DOT)", fillcolor="#B2DFDB"];
F6_5 [label="F6.5\nPersonnalisation\nclient (projection SI)", fillcolor="#B2DFDB"];
F6_6 [label="F6.6\nIntégration\nécosystème 360°", fillcolor="#B2DFDB"];
acteur_F6 [label="Acteurs : Expert, Service\nCOMEX, Métiers, DSAI", shape=ellipse, fillcolor="#E0F2F1", fontsize=9];
}
// Transversal
subgraph cluster_F7 {
label="F7. SÉCURISER ET CONTRÔLER (transversal)";
style=filled; color="#ECEFF1"; fontsize=12; fontcolor="#37474F";
F7_1 [label="F7.1 Auth\n(user / API key)", fillcolor="#CFD8DC"];
F7_2 [label="F7.2 Rôles\n(admin/expert/service)", fillcolor="#CFD8DC"];
F7_3 [label="F7.3 Profils\nvisibilité", fillcolor="#CFD8DC"];
F7_4 [label="F7.4 Rate\nlimiting", fillcolor="#CFD8DC"];
F7_5 [label="F7.5 Monitoring\nobservabilité", fillcolor="#CFD8DC"];
F7_1 -> F7_2 -> F7_3;
acteur_F7 [label="Acteurs : Admin (config)\nSystème (exécution)", shape=ellipse, fillcolor="#ECEFF1", fontsize=9];
}
// Flux principal
F1_4 -> F2_1 [lhead=cluster_F2, ltail=cluster_F1, penwidth=2, color="#333333"];
F2_7 -> F3_1 [lhead=cluster_F3, ltail=cluster_F2, penwidth=2, color="#333333"];
F3_4 -> F4_1 [lhead=cluster_F4, ltail=cluster_F3, penwidth=2, color="#333333"];
F4_2 -> F5_1 [lhead=cluster_F5, ltail=cluster_F4, penwidth=2, color="#333333"];
F5_3 -> F6_1 [lhead=cluster_F6, ltail=cluster_F5, penwidth=2, color="#333333"];
// F3 en continu
F3_2 -> F3_1 [style=dashed, color="#E65100", label="boucle\ncontinue"];
// F7 transversal
F7_3 -> F5_1 [style=dotted, color="#37474F", lhead=cluster_F5, label="filtre"];
F7_3 -> F6_1 [style=dotted, color="#37474F", lhead=cluster_F6, label="filtre"];
}

147
docs/macro-dat.dot Normal file
View File

@ -0,0 +1,147 @@
digraph macro_dat {
rankdir=TB;
fontname="Arial";
node [fontname="Arial", fontsize=10, style=filled, shape=record];
edge [fontname="Arial", fontsize=9];
label="FabNum — Macro-DAT (Diagramme d'Activités Technique)\n\n";
labelloc=t;
fontsize=16;
compound=true;
// ==================== COUCHE STOCKAGE ====================
subgraph cluster_stockage {
label="COUCHE STOCKAGE";
style=filled; color="#E3F2FD"; fontsize=13; fontcolor="#1565C0";
base_graphe [label="Base graphe\n(Neo4j / PG+AGE / ArangoDB)|• Nœuds (tous niveaux)\n• Arêtes + attributs\n• Multi-graphes\n• Schéma évolutif\n• Open source", fillcolor="#BBDEFB"];
historisation [label="Historisation|• Snapshots horodatés\n• Versions données\n• Versions indices\n• Audit trail", fillcolor="#BBDEFB"];
sources_db [label="Référentiel sources|• Sources catégorisées\n• Tiers de confiance\n (par domaine)\n• Liens source↔donnée", fillcolor="#BBDEFB"];
}
// ==================== COUCHE MOTEUR ====================
subgraph cluster_moteur {
label="COUCHE MOTEUR (Python)";
style=filled; color="#E8F5E9"; fontsize=13; fontcolor="#2E7D32";
subgraph cluster_calcul {
label="Calcul";
style=filled; color="#C8E6C9";
calcul_indices [label="Calcul indices|IHH, ICS, IVC, ISG\n+ futurs (eau, énergie)\nPré-calcul à chaque MAJ", fillcolor="#A5D6A7"];
meta_indices [label="Méta-indices|Calcul dynamique\nsur sous-graphe\nsélectionné", fillcolor="#A5D6A7"];
}
subgraph cluster_qualite {
label="Qualité données";
style=filled; color="#C8E6C9";
arbitrage [label="Arbitrage sources|Tier 1 par défaut\nConvergence → alerte\nSeuils variation", fillcolor="#A5D6A7"];
qualification [label="Qualification|Filtres qualité\nIndice fiabilité\nPérimètre mesuré", fillcolor="#A5D6A7"];
}
subgraph cluster_requetage {
label="Requêtage";
style=filled; color="#C8E6C9";
chemins [label="Traversée graphe|Chemins critiques\nFiltrage multi-critères\nSous-graphes", fillcolor="#A5D6A7"];
projection [label="Projection SI|Mapping SI client\nsur graphe FabNum\n(stateless)", fillcolor="#A5D6A7"];
}
subgraph cluster_generation {
label="Génération";
style=filled; color="#C8E6C9";
templates [label="Templates fiches|Niveau × usage\nExpertise / Synthèse\nAPI / JSON", fillcolor="#A5D6A7"];
import_export [label="Import / Export|DOT (legacy)\nJSON\nPDF\nBackup / Restore", fillcolor="#A5D6A7"];
}
}
// ==================== SERVICES INTERNES ====================
subgraph cluster_services_internes {
label="SERVICES INTERNES (non exposés)";
style=filled; color="#FFF3E0"; fontsize=13; fontcolor="#E65100";
veille [label="Veille sources\n(huginn)|Détection MAJ\nNouvelles sources\nDisparitions", fillcolor="#FFE0B2"];
verif_citations [label="Vérification\ncitations|verify-citations\n(à faire évoluer)", fillcolor="#FFE0B2"];
recalcul [label="Recalcul\nindices|Déclenché par\nMAJ graphe\n(mensuel → trim.)", fillcolor="#FFE0B2"];
alertes [label="Alertes|Variations anormales\nConvergence sources\nÉvénements climat.", fillcolor="#FFE0B2"];
}
// ==================== API REST ====================
subgraph cluster_api {
label="API REST (point d'accès unique)";
style=filled; color="#F3E5F5"; fontsize=13; fontcolor="#6A1B9A";
subgraph cluster_securite {
label="Sécurité";
style=filled; color="#E1BEE7";
auth [label="Authentification|User / API key\nRôles (admin/expert/service)", fillcolor="#CE93D8"];
profils [label="Profils visibilité|Chaîne principale / +connexes\nIndices complets / partiels\nPrédéfinis / sur mesure", fillcolor="#CE93D8"];
rate_limit [label="Rate limiting\n+ Monitoring|Logging structuré\nMétriques\nAlerting", fillcolor="#CE93D8"];
}
subgraph cluster_endpoints {
label="Endpoints";
style=filled; color="#E1BEE7";
ep_graphe [label="/graphe/*|Requêtage\n(expert / simplifié)", fillcolor="#CE93D8"];
ep_fiches [label="/fiches/*|Consultation\n(tous formats)", fillcolor="#CE93D8"];
ep_analyse [label="/analyse/*|Vulnérabilités\nScénarios", fillcolor="#CE93D8"];
ep_indices [label="/indices/*|Méta-indices\ndynamiques", fillcolor="#CE93D8"];
ep_export [label="/export/*|PDF, JSON, DOT", fillcolor="#CE93D8"];
ep_admin [label="/admin/*|CRUD graphe\nGestion sources\nTiers, arbitrage", fillcolor="#CE93D8"];
}
}
// ==================== CONSOMMATEURS ====================
subgraph cluster_consommateurs {
label="CONSOMMATEURS";
style=filled; color="#ECEFF1"; fontsize=13; fontcolor="#37474F";
frontend [label="Frontend expert|COMEX : synthèses\nMétiers : analyse opérat.\nDSAI : dépendances SI", fillcolor="#CFD8DC", shape=house];
services_ext [label="Services externes|Génération IA rapports\nAgent local client\nExport manuel", fillcolor="#CFD8DC", shape=house];
ecosysteme [label="Écosystème 360°|Veille stratégique\nIRON\nAlertes croisées", fillcolor="#CFD8DC", shape=house];
}
// Admin
admin [label="Admin (scripts)|CRUD graphe\nGestion sources\nTiers, arbitrage\nBackup / restore", fillcolor="#FFCC80", shape=hexagon];
// ==================== LIENS ====================
// Stockage → Moteur
base_graphe -> chemins [color="#1565C0"];
base_graphe -> calcul_indices [color="#1565C0"];
historisation -> meta_indices [style=dashed, color="#1565C0"];
sources_db -> arbitrage [color="#1565C0"];
sources_db -> qualification [color="#1565C0"];
// Moteur → Services internes
calcul_indices -> recalcul [color="#E65100"];
arbitrage -> alertes [color="#E65100"];
qualification -> verif_citations [color="#E65100", style=dashed];
// Moteur → API
chemins -> ep_graphe [color="#6A1B9A"];
meta_indices -> ep_indices [color="#6A1B9A"];
templates -> ep_fiches [color="#6A1B9A"];
import_export -> ep_export [color="#6A1B9A"];
projection -> ep_graphe [color="#6A1B9A", style=dashed];
calcul_indices -> ep_analyse [color="#6A1B9A"];
// Sécurité → Endpoints
auth -> ep_graphe [style=dotted, color="#6A1B9A"];
profils -> ep_graphe [style=dotted, color="#6A1B9A"];
// API → Consommateurs
ep_graphe -> frontend [color="#37474F", penwidth=1.5];
ep_fiches -> frontend [color="#37474F", penwidth=1.5];
ep_analyse -> frontend [color="#37474F", penwidth=1.5];
ep_export -> services_ext [color="#37474F", penwidth=1.5];
ep_graphe -> ecosysteme [color="#37474F", penwidth=1.5];
ep_indices -> ecosysteme [color="#37474F", penwidth=1.5];
ep_graphe -> services_ext [color="#37474F", penwidth=1.5];
// Admin
admin -> ep_admin [color="#E65100", penwidth=2];
admin -> base_graphe [color="#E65100", penwidth=2, label="accès\ndirect"];
// Services internes → Stockage (boucle)
veille -> sources_db [color="#E65100", style=dashed, label="MAJ\nsources"];
recalcul -> base_graphe [color="#E65100", style=dashed, label="MAJ\nindices"];
alertes -> admin [color="#E65100", style=dashed, label="notification"];
}

92
docs/planification-temporelle.dot Normal file
View File

@ -0,0 +1,92 @@
digraph planification_temporelle {
rankdir=LR;
fontname="Arial";
node [fontname="Arial", fontsize=11, style=filled, shape=record];
edge [fontname="Arial", fontsize=9];
label="FabNum — Planification temporelle\n\n";
labelloc=t;
fontsize=16;
// Phases
subgraph cluster_phase1 {
label="Phase 1 — Fondations";
style=filled;
color="#E3F2FD";
fontsize=13;
fontcolor="#1565C0";
P7 [label="P7\nValidation\nniveaux|Revue littérature\nSCOR, ISO 28000\nOpen Supply Hub", fillcolor="#BBDEFB"];
P6spike [label="P6 spike\nTest bases\ndonnées|Neo4j Community\nPostgreSQL+AGE\nArangoDB\n(Docker/serveur)", fillcolor="#BBDEFB"];
}
subgraph cluster_phase2 {
label="Phase 2 — Modèle & Stockage";
style=filled;
color="#E8F5E9";
fontsize=13;
fontcolor="#2E7D32";
P3 [label="P3\nModèle de\ndonnées|Essentielles / Info\nTiers confiance\nArbitrage\nHistorisation\nIndice fiabilité", fillcolor="#C8E6C9"];
P6impl [label="P6 impl\nStockage|Base retenue\nInstallation native\nBackup", fillcolor="#C8E6C9"];
}
subgraph cluster_phase3 {
label="Phase 3 — Données & Sources";
style=filled;
color="#FFF3E0";
fontsize=13;
fontcolor="#E65100";
P2 [label="P2\nGestion\nsources|Identification\nCatégorisation\nVeille (huginn)\nVérification citations", fillcolor="#FFE0B2"];
P4 [label="P4\nAmorçage|3 minerais\n1 composant\n1 produit final\nQualification\n+ audit exhaustivité", fillcolor="#FFE0B2"];
}
subgraph cluster_phase4 {
label="Phase 4 — Fiches & API";
style=filled;
color="#F3E5F5";
fontsize=13;
fontcolor="#6A1B9A";
P5 [label="P5\nTemplates\nfiches|Niveau × usage\nExpertise\nSynthèse\nAPI/JSON", fillcolor="#E1BEE7"];
P1 [label="P1\nAPI REST\n+ rôles|Admin / Expert / Service\nAuth + tokens\nAPI-first", fillcolor="#E1BEE7"];
P8 [label="P8\nServices\nsécu profils|Personnalisation client\nProfils visibilité\nRate limiting\nRGPD / stateless", fillcolor="#E1BEE7"];
}
subgraph cluster_horizon {
label="Horizon";
style=filled;
color="#EFEBE9";
fontsize=13;
fontcolor="#4E342E";
P10 [label="P10\nÉnergie / Eau|Attributs opération\nSourçage parcellaire\nCroisements risques", fillcolor="#D7CCC8"];
P11 [label="P11\nGéo fine|Région / site\nWRI Aqueduct\nAlertes climatiques", fillcolor="#D7CCC8"];
P9 [label="P9\nMulti-\nsectoriel|Graphes par secteur\nConnexes inter-secteurs\nMinerais partagés", fillcolor="#D7CCC8"];
}
// MVP
MVP [label="MVP\nJalon interne|Moteur requêtable\nDonnées sourcées\nIndice fiabilité\nRétro-analyse", shape=doubleoctagon, fillcolor="#FFF9C4", style="filled,bold"];
// Dépendances principales
P7 -> P3 [label="niveaux\nvalidés", color="#2E7D32", penwidth=2];
P6spike -> P6impl [label="techno\nretenue", color="#2E7D32", penwidth=2];
P3 -> P6impl [label="schéma", color="#2E7D32"];
P6impl -> P4 [label="base\nprête", color="#E65100", penwidth=2];
P2 -> P4 [label="sources\ncatégorisées", color="#E65100"];
P4 -> P5 [label="données\nqualifiées", color="#6A1B9A"];
P5 -> P1 [label="fiches\ngénérables", color="#6A1B9A"];
P1 -> P8 [label="API\nfonctionnelle", color="#6A1B9A"];
// Parallélisations
P7 -> P6spike [style=dashed, color="#1565C0", label="parallèle", constraint=false];
P3 -> P2 [style=dashed, color="#E65100", label="P2 démarre\nen parallèle", constraint=false];
// MVP
P4 -> MVP [style=bold, color="#F9A825", penwidth=2, label="MVP atteint"];
// Horizon (dépendances faibles)
P8 -> P10 [style=dotted, color="#795548"];
P8 -> P11 [style=dotted, color="#795548"];
P8 -> P9 [style=dotted, color="#795548"];
}