Documentation Technique

Architecture et Outils du Système

Découvrez en détail les composants techniques qui garantissent l'intégrité et la traçabilité de chaque donnée.

Pilier 1

Rules - Le Code Civil du Système

Les règles définissent les contraintes immuables que le système doit respecter. Elles constituent le fondement de l'intégrité scientifique.

📋 Provenance Obligatoire

Principe : Aucune donnée ne peut exister sans source documentée et datée.

Chaque information doit être liée à sa source bibliographique avec :

  • ID de la source (ex: bensky2015, usda_sr28)
  • Localisation précise (page, chapitre, NDB No)
  • Date d'intégration (format ISO 8601)
  • Nom de l'intégrateur
  • Méthode d'extraction
  • Niveau de certitude évalué

🔢 Versioning Sémantique

Format : MAJEURE.MINEURE.PATCH (ex: 2.1.3)

Règles d'incrémentation :

  • MAJEURE : Validation d'expert, restructuration majeure
  • MINEURE : Ajout de données, nouvelles sections
  • PATCH : Corrections mineures, typos

Interdit : Sauter des versions, réduire le numéro, modifier l'historique passé.

📚 Historique Immuable

Principe : On ne réécrit jamais l'histoire, on ajoute de nouvelles entrées.

Chaque modification génère une entrée dans historique_versions[] avec :

  • Numéro de version
  • Date et heure (ISO 8601)
  • Type de modification
  • Auteur complet (nom, rôle, affiliation)
  • Description détaillée des changements
  • Liste des éléments modifiés (chemins JSON)

✓ Intégrité du Schéma

Standard : Conformité stricte à schema_tracabilite_v2.json

Avant chaque sauvegarde, validation automatique avec :

  • Vérification de la structure JSON
  • Contrôle des types de données
  • Validation des champs requis
  • Vérification des références (sources, validations)
ajv validate -s schema_tracabilite_v2.json -d fiche.json

Fichier de référence

.windsurf/rules/traceability-modifications.md

Ce fichier contient l'ensemble des règles, contraintes et bonnes pratiques à respecter lors de toute modification d'une fiche de traçabilité.

Pilier 2

Agents - Les Acteurs Spécialisés

Six agents autonomes orchestrent les opérations complexes de traçabilité. Chacun possède une responsabilité unique et interagit avec les autres.

🎯

ValidationManager

Le Chef d'Orchestre des Validations

Responsabilités :

  • Enregistrer les validations d'experts
  • Mettre à jour les métadonnées
  • Orchestrer les autres agents
  • Générer les rapports de validation

Inputs : Expert, Date, Statut, Domaines validés, Commentaires

Outputs : Fiche mise à jour, Rapport de validation

📝

VersionManager

Le Notaire du Système

Responsabilités :

  • Calculer le nouveau numéro de version
  • Créer l'entrée d'historique
  • Identifier les éléments modifiés
  • Documenter les changements

Règles : Versioning sémantique strict (Majeure/Mineure/Patch)

📊

ConfidenceCalculator

Le Statisticien

Formule de calcul :

Confiance = 0.40 × Validations_Experts + 0.30 × Qualité_Sources + 0.20 × Complétude_Données + 0.10 × Fraîcheur_Données

Outputs : Score 0.0 à 1.0, Statut de validation

🔍

SourceExtractor

Le Bibliothécaire

Responsabilités :

  • Extraire métadonnées depuis DOI, ISBN, URL
  • Formater selon standard CSL-JSON
  • Attribuer un ID unique
  • Évaluer le niveau de fiabilité
✅

SchemaValidator

Le Gardien de l'Intégrité

Responsabilités :

  • Valider la structure JSON
  • Vérifier les types de données
  • Contrôler les champs requis
  • Signaler les erreurs avec suggestions
📄

ReportGenerator

Le Communicateur

Responsabilités :

  • Créer rapports de validation
  • Générer historique de modifications
  • Produire rapports de confiance
  • Exporter en Markdown, PDF, HTML

Workflow d'interaction des agents

1. Réception validation expert ↓ 2. ValidationManager - Crée l'objet validation - Appelle VersionManager ↓ 3. VersionManager - Calcule nouvelle version - Crée entrée historique ↓ 4. ConfidenceCalculator - Recalcule confiance globale - Met à jour statut validation ↓ 5. SchemaValidator - Valide la fiche modifiée ↓ 6. ReportGenerator - Génère rapport de validation ↓ 7. Sauvegarde fiche mise à jour

Fichier de référence : Tracabilite/agents.md

Pilier 3

Workflows - Les Procédures Standard

Des workflows documentés étape par étape garantissent la cohérence et l'absence d'erreurs lors des opérations de traçabilité.

Workflow 1 : Ajouter une validation d'expert

  1. Identifier la fiche à mettre à jour
  2. Lire la fiche actuelle
  3. Créer l'objet validation avec ID unique
  4. Calculer la nouvelle version (Majeure/Mineure/Patch)
  5. Créer l'entrée d'historique
  6. Recalculer le niveau de confiance global
  7. Mettre à jour le statut de validation
  8. Mettre à jour les métadonnées
  9. Ajouter la validation à la liste
  10. Valider le schéma JSON
  11. Sauvegarder la fiche mise à jour
  12. Générer un rapport de validation

Fichier : .windsurf/workflows/add-expert-validation.md

Workflow 2 : Mettre à jour des données

  1. Identifier la donnée à modifier
  2. Vérifier si la source existe
  3. Créer l'objet provenance complet
  4. Mettre à jour la donnée avec sa provenance
  5. Calculer la nouvelle version
  6. Créer l'entrée d'historique
  7. Mettre à jour les métadonnées
  8. Valider le schéma
  9. Sauvegarder

Fichier : .windsurf/workflows/update-traceability-data.md

Avantages des workflows documentés

✓

Cohérence

Chaque opération suit le même processus standardisé

✓

Réduction d'erreurs

Les étapes critiques ne sont jamais oubliées

✓

Formation facilitée

Nouveaux membres formés rapidement

✓

Auditabilité

Processus transparent et vérifiable

Pilier 4

Skills - L'Intelligence Pratique

Les skills permettent l'automatisation via langage naturel. L'IA comprend vos demandes et exécute automatiquement les workflows appropriés.

Skill : add-expert-validation

Entrée (Langage Naturel)

"Aujourd'hui, 26 janvier 2026, j'ai reçu la validation de la fiche sur l'abricot par un expert en diététique chinoise et MTC qui a déjà écrit des livres. Elle m'a confirmé que toute la fiche était correcte."

Sortie (Actions Automatiques)

  • Extraction des entités (Expert, Date, Aliment, Statut)
  • Lecture de la fiche actuelle
  • Création de l'objet validation
  • Calcul de la nouvelle version (1.1.0 → 2.0.0)
  • Recalcul du niveau de confiance (0.92 → 0.95)
  • Mise à jour des métadonnées
  • Sauvegarde de la fiche
  • Génération du rapport

✓ Résultat

Fiche mise à jour automatiquement avec nouvelle validation, versioning correct, confiance recalculée et rapport généré. Aucune ligne de code à écrire.

Fichier de référence : .windsurf/skills/add-expert-validation-skill.md

Avantages de l'Automatisation par Skills

⚡ Rapidité

Une phrase suffit pour déclencher un processus complet de 12 étapes.

🎯 Précision

Aucune erreur de saisie, calculs automatiques, conformité garantie.

🔄 Reproductibilité

Même processus à chaque fois, résultats cohérents et prévisibles.

Comprendre l'Impact Scientifique

Découvrez comment ce système technique se traduit en crédibilité scientifique exceptionnelle.

Crédibilité Scientifique Voir un Cas Pratique