diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d29cb22..cb719d0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,440 +1,619 @@ # Architecture -Version : 2.0 - -Dernière mise à jour : 2026-07-14 - -Auteur : fy59 +> **Version :** 3.0 +> **Dernière mise à jour :** 2026-07-24 +> **Schéma SQLite courant :** V10 +> **Statut :** architecture courante --- -# Objectif +## 1. Objectif -Ce document décrit l'architecture logicielle de **Labfy Investigation**. +Ce document décrit l'architecture logicielle actuelle de Labfy Investigation. -Il constitue le document de référence du projet. +Il définit : -Son objectif est de : +- les responsabilités des couches ; +- la direction autorisée des dépendances ; +- le cycle de vie d'une enquête ; +- la place de SQLite et du système de fichiers ; +- le fonctionnement des tâches asynchrones ; +- l'intégration des outils externes ; +- la projection graphique des données ; +- les règles de sécurité et de traçabilité. -- définir les responsabilités de chaque module ; -- garantir une architecture cohérente ; -- limiter le couplage entre les composants ; -- faciliter les évolutions futures ; -- permettre la réalisation de tests unitaires indépendants de l'interface graphique. - ---- - -# Vision - -Labfy Investigation est un logiciel libre d'investigation numérique, -développé en **C17** avec **GTK4**. - -Le projet a pour objectif de fournir un environnement professionnel -permettant de gérer une enquête numérique de bout en bout : - -- création d'une enquête ; -- collecte des preuves ; -- organisation des informations ; -- analyse ; -- génération de rapports. - -L'application est conçue pour être utilisée aussi bien par : - -- des particuliers ; -- des journalistes ; -- des analystes OSINT ; -- des experts judiciaires ; -- des forces de l'ordre. - ---- - -# Principes fondamentaux - -## Une enquête = un dossier autonome - -Chaque enquête contient tout ce qui est nécessaire à son fonctionnement. +La documentation détaillée du schéma SQLite se trouve dans : +```text +docs/database/DATABASE_ARCHITECTURE.md +docs/database/SCHEMA_AUDIT_CURRENT.md ``` -MonEnquete/ +--- + +## 2. Vision + +Labfy Investigation est un poste de travail local d'investigation numérique et +d'OSINT développé en C17 avec GTK4. + +Une enquête doit pouvoir être : + +- créée ; +- ouverte ; +- copiée ; +- sauvegardée ; +- archivée ; +- transmise ; + +avec son dossier et sa base SQLite. + +Le logiciel n'est pas encore prêt pour un usage opérationnel en production. +Les formats et interfaces peuvent évoluer tant que le projet reste en +développement actif. + +--- + +## 3. Sources de vérité + +Pour déterminer l'état réel d'une fonction : + +1. code de `main` ; +2. tests ; +3. migrations SQL ; +4. commits ; +5. tickets Forgejo ; +6. documentation. + +Les documents historiques ne décrivent pas l'état courant. + +SQLite est la source de vérité des données structurées d'une enquête. + +Le système de fichiers est la source de vérité des fichiers originaux et +dérivés référencés par la base. + +Le graphe, la barre latérale et les autres vues ne possèdent pas leur propre +copie métier indépendante. + +--- + +## 4. Principes fondamentaux + +### 4.1 Une enquête est autonome + +```text +MonEnquete/ ├── 00_BaseDeDonnees/ │ └── Enquete.sqlite -│ ├── 01_Preuves_Originales/ ├── 02_Preuves_Traitees/ ├── 03_Chronologie/ ├── 04_Entites/ -├── 05_Rapports/ -│ -└── ... +└── 05_Rapports/ ``` -Une enquête peut être : +Aucune donnée métier d'une enquête ne doit être stockée dans une base globale. -- copiée ; -- déplacée ; -- synchronisée ; -- sauvegardée ; -- archivée ; -- transmise. +Les préférences générales de l'application, lorsqu'elles seront ajoutées, +resteront séparées des données d'enquête. -Aucune dépendance externe ne doit être nécessaire. +### 4.2 Les preuves originales sont immuables + +L'application ne modifie jamais un fichier original importé. + +Toute annotation, conversion, extraction, analyse ou expurgation produit un +objet dérivé. + +### 4.3 Le cœur ne dépend pas de GTK + +Les modèles, DAO et services métier doivent pouvoir être testés sans lancer +l'interface graphique. + +### 4.4 Les widgets ne contiennent pas la logique métier + +Un widget : + +- affiche un état ; +- collecte une intention utilisateur ; +- déclenche une action de l'application ; +- présente le résultat. + +Il ne : + +- construit pas de requête SQL ; +- ne déplace pas directement une preuve ; +- ne lance pas une commande shell ; +- ne décide pas seul de la validation métier d'une donnée. + +### 4.5 Les traitements longs sont asynchrones + +Le thread GTK principal ne réalise pas les opérations longues. + +### 4.6 Les résultats automatiques restent révisables + +Une donnée OCR, OSINT ou dérivée ne devient pas un fait confirmé sans action +explicite lorsque le domaine l'exige. --- -## Les preuves originales sont immuables +## 5. Architecture en couches -Les preuves originales ne doivent jamais être modifiées. - -Toute opération produisant : - -- une annotation ; -- une conversion ; -- une extraction ; -- une analyse ; - -doit produire un nouveau fichier dans un espace dédié. - ---- - -## Le Core est indépendant de GTK - -La logique métier ne dépend jamais de l'interface graphique. - -Le Core doit pouvoir être testé sans lancer GTK. - ---- - -## Les Widgets ne connaissent pas le métier - -Les widgets affichent uniquement les informations fournies. - -Ils ne manipulent jamais : - -- SQLite ; -- le système de fichiers ; -- les preuves. - ---- - -## Développement incrémental - -Chaque ticket doit : - -- compiler sans warning ; -- être documenté ; -- être testé ; -- ne pas casser les fonctionnalités existantes. - ---- - -# Architecture générale - -``` - Utilisateur - │ - ▼ - +-----------------+ - | GTK4 | - | Views / Widgets | - +-----------------+ - │ - ▼ - +-----------------+ - | Application | - +-----------------+ - │ - ▼ - +---------------------------+ - | InvestigationProject | - +---------------------------+ - │ │ - ▼ ▼ - FileSystem Database - │ │ - └────────┬────────┘ - ▼ - Investigation - │ - ▼ - Models +```text +┌──────────────────────────────────────────────┐ +│ Interface GTK4 │ +│ views / widgets │ +└──────────────────────┬───────────────────────┘ + │ intentions et affichage +┌──────────────────────▼───────────────────────┐ +│ Application et contrôleurs │ +│ cycle de vie, session, navigation, messages │ +└──────────────────────┬───────────────────────┘ + │ orchestration +┌──────────────────────▼───────────────────────┐ +│ Services métier et tâches │ +│ import, relations, OSINT, EML, graphe │ +└───────────────┬───────────────────┬──────────┘ + │ │ +┌───────────────▼────────────┐ ┌────▼─────────────────┐ +│ DAO │ │ Adaptateurs │ +│ requêtes métier SQLite │ │ fichiers / CLI / API│ +└───────────────┬────────────┘ └────┬─────────────────┘ + │ │ +┌───────────────▼───────────────────▼──────────┐ +│ Infrastructure │ +│ SQLite / transactions / système de fichiers │ +└──────────────────────────────────────────────┘ ``` -Cette architecture permet une séparation claire entre : - -- l'interface graphique ; -- la logique métier ; -- le stockage. +Les modèles métier circulent entre ces couches sans dépendre de GTK ni de +SQLite. --- -# Organisation du projet +## 6. Organisation du dépôt -``` -labfy-investigation/ - -include/ -src/ - -database/ -docs/ -resources/ -tests/ -tools/ - -README.md -LICENSE -CHANGELOG.md -CONTRIBUTING.md -Makefile +```text +database/ scripts SQL versionnés et schéma courant +docs/ architecture, conventions et procédures +include/core/ interfaces des services et du cœur +include/dao/ interfaces d'accès métier aux données +include/database/ interfaces de l'infrastructure SQLite +include/models/ modèles métier +include/views/ fenêtres et dialogues GTK +include/widgets/ widgets réutilisables +resources/ ressources de l'application +src/core/ services, tâches et orchestration métier +src/dao/ requêtes métier SQLite +src/database/ connexion, schéma, statements, transactions, erreurs +src/models/ implémentation des modèles +src/views/ fenêtres et dialogues GTK +src/widgets/ composants GTK réutilisables +tests/ tests unitaires et d'intégration ciblée ``` --- -# Organisation du code +## 7. Responsabilités des modules -``` -src/ +### 7.1 Point d'entrée et application -core/ -database/ -models/ -views/ -widgets/ -utils/ +`src/main.c` démarre l'application. + +La couche application : + +- gère le cycle de vie GTK ; +- crée la fenêtre principale ; +- ouvre ou crée une enquête ; +- remplace la session active uniquement après succès ; +- coordonne les messages utilisateur ; +- relie les services métier aux vues ; +- ferme proprement les ressources. + +Une erreur d'ouverture ne doit pas détruire une session valide déjà active. + +### 7.2 Core et services métier + +`src/core` contient notamment : + +- représentation et validation d'une enquête ; +- session et projet d'enquête ; +- construction de l'arborescence ; +- tâches d'arrière-plan ; +- gestionnaire de tâches ; +- registre et catalogue d'outils ; +- exécution de processus ; +- hachage et copie de fichiers ; +- import et intégrité des preuves ; +- services d'entités et de relations ; +- chargement du graphe ; +- actions OSINT ; +- analyse EML, IBAN, OCR, métadonnées et PDF ; +- vocabulaire contrôlé ; +- pipeline EML. + +Un service métier peut coordonner plusieurs DAO, une transaction et une +opération de fichier. + +### 7.3 Modèles + +`src/models` représente les données manipulées par l'application. + +Les modèles : + +- ne lancent pas de requête SQL ; +- ne dépendent pas de GTK ; +- valident leurs invariants lorsque cela leur appartient ; +- exposent une API claire de création, lecture et destruction. + +### 7.4 Infrastructure Database + +`src/database` gère : + +- ouverture et fermeture de SQLite ; +- activation des clés étrangères ; +- lecture de la version ; +- installation du schéma ; +- migrations ; +- statements préparés ; +- transactions ; +- traduction structurée des erreurs. + +Cette couche ne contient pas l'orchestration complète d'une fonctionnalité +utilisateur. + +### 7.5 DAO + +`src/dao` contient les requêtes métier. + +Un DAO : + +- transforme des lignes SQLite en modèles ; +- utilise des statements préparés ; +- ne dépend pas de GTK ; +- ne lance pas d'outil externe ; +- ne décide pas seul d'un workflow multi-étapes ; +- expose des erreurs exploitables par le service appelant. + +### 7.6 Vues et widgets + +`src/views` contient les fenêtres et dialogues complets. + +`src/widgets` contient les composants réutilisables, notamment : + +- barre latérale ; +- arborescence ; +- panneau de tâches ; +- listes ; +- espace de travail ; +- graphe. + +Les vues et widgets ne deviennent pas propriétaires des données persistées. + +--- + +## 8. Cycle de vie d'une enquête + +### 8.1 Création + +```text +sélection du dossier + ↓ +validation du chemin + ↓ +création de l'arborescence + ↓ +initialisation transactionnelle de SQLite V10 + ↓ +création de l'identité de l'enquête + ↓ +ouverture d'une session + ↓ +construction des vues ``` ---- +Un échec laisse l'application dans un état cohérent et nettoie les artefacts +partiels prévus par le service. -# Description des modules +### 8.2 Ouverture -## Core +```text +sélection du dossier + ↓ +validation de l'arborescence + ↓ +ouverture de SQLite + ↓ +lecture de schema_version + ↓ +migration éventuelle + ↓ +chargement de l'enquête + ↓ +construction de l'arborescence et du graphe + ↓ +remplacement atomique de la session active +``` -Le Core pilote l'application. +Une base plus récente que l'application doit être refusée. -Il ne dépend jamais de GTK. +### 8.3 Fermeture -Il gère : - -- le cycle de vie de l'application ; -- l'ouverture d'une enquête ; -- la fermeture d'une enquête ; -- les interactions entre les modules. - ---- - -## InvestigationProject - -InvestigationProject est le point d'entrée métier. - -Il est responsable de : - -- créer une enquête ; -- ouvrir une enquête ; -- fermer une enquête ; -- valider une enquête ; -- initialiser SQLite ; -- gérer le système de fichiers. - -Toute manipulation d'une enquête passe obligatoirement par ce module. - ---- - -## Database - -Le module Database est responsable du stockage. - -Il gère : +La fermeture libère : +- les tâches ; +- les références de modèles ; - la connexion SQLite ; -- le schéma ; -- les migrations ; -- les transactions. - -Aucune requête SQL ne doit apparaître ailleurs. +- la session ; +- les widgets dépendants ; +- les ressources externes. --- -## Models +## 9. Gestion des preuves -Les modèles représentent les objets métier. +### 9.1 Import -Par exemple : +Le flux d'import vise à garantir l'intégrité : -- InvestigationNode -- Preuve -- Entité -- Relation -- Chronologie - -Ils ne connaissent ni GTK ni SQLite. - ---- - -## Views - -Les vues représentent les fenêtres de l'application. - -Elles ne contiennent aucune logique métier. - ---- - -## Widgets - -Les widgets sont des composants GTK réutilisables. - -Par exemple : - -- Sidebar -- Workspace -- InvestigationTreeView -- Toolbar -- Statusbar - ---- - -## Utils - -Fonctions génériques. - -Exemples : - -- SHA-256 -- Dates -- Gestion des fichiers -- Journalisation - -Les utilitaires ne doivent dépendre d'aucun module métier. - ---- - -# Flux de données - -Lorsqu'un utilisateur ouvre une enquête : - -``` -Utilisateur - -↓ - -GTK - -↓ - -Application - -↓ - -InvestigationProject - -↓ - -FileSystem - -↓ - -Database - -↓ - -Investigation - -↓ - -GUI +```text +validation de la source + ↓ +SHA-256 source + ↓ +copie vers une destination contrôlée + ↓ +SHA-256 destination + ↓ +écriture SQLite + ↓ +validation ou nettoyage ``` -Le flux est toujours unidirectionnel. +L'import groupé traite les fichiers de manière contrôlée et produit un bilan +détaillé. + +### 9.2 Reclassement + +Un changement de type peut impliquer : + +- vérification préalable de l'intégrité ; +- déplacement cohérent du fichier interne ; +- mise à jour SQLite ; +- rollback et restauration en cas d'échec. + +L'UUID, l'empreinte et l'historique ne doivent pas être recréés silencieusement. + +### 9.3 Dérivés + +Les extractions, OCR, pièces jointes EML et versions traitées restent reliés à +leur preuve source. --- -# Dépendances +## 10. Tâches asynchrones -Les dépendances suivent toujours cette règle : +Les tâches longues utilisent l'infrastructure de tâche d'arrière-plan et le +gestionnaire de tâches. -``` -Widgets - │ - ▼ -Views - │ - ▼ -Application - │ - ▼ -InvestigationProject - │ - ┌──┴───────┐ - ▼ ▼ -Database FileSystem - │ - ▼ -Models +Une tâche expose selon ses besoins : + +```text +pending +running +completed +failed +cancelled ``` -Les dépendances inverses sont interdites. +Elle doit : + +- éviter l'accès direct à GTK depuis un thread de travail ; +- transférer le résultat vers le thread principal ; +- conserver une erreur structurée ; +- libérer ses ressources même après annulation ; +- ne pas laisser une transaction ouverte ; +- ne pas écrire simultanément dans SQLite sans coordination. --- -# Gestion de la mémoire +## 11. Outils externes et OSINT -Chaque allocation possède une fonction de libération correspondante. +### 11.1 Registre et catalogue -Les responsabilités de libération sont clairement définies. +Le registre détecte la présence et la version des outils. -Aucun module ne libère une ressource qu'il n'a pas créée. +Le catalogue décrit les capacités et les actions compatibles avec une +sélection. + +Une dépendance absente désactive l'action concernée sans empêcher le démarrage. + +### 11.2 Exécution + +Les outils sont lancés avec `GSubprocess`. + +Les arguments sont transmis séparément. + +Aucune commande shell dynamique n'est construite. + +Les exécutions persistées peuvent conserver : + +- outil et version ; +- cible et paramètres ; +- dates ; +- code de retour ; +- sorties brutes ; +- empreintes ; +- statut d'analyse ; +- objets intégrés. + +### 11.3 Intégration + +Une action OSINT suit le modèle : + +```text +sélection + ↓ +validation de l'action + ↓ +tâche asynchrone + ↓ +sortie brute + ↓ +propositions normalisées + ↓ +révision + ↓ +intégration transactionnelle + ↓ +rafraîchissement des vues +``` --- -# Gestion des erreurs +## 12. Graphe d'enquête -Les erreurs remontent toujours jusqu'à Application. +Le graphe est une projection de SQLite. -L'interface graphique est uniquement responsable de leur affichage. +Il représente notamment : + +- entités ; +- relations ; +- preuves ou extractions lorsque le modèle le prévoit ; +- positions et viewport persistés séparément des données métier. + +Les coordonnées et le zoom sont un état de présentation. + +Une modification du graphe qui change le métier doit passer par un service et +être persistée dans SQLite avant d'être considérée comme acquise. + +Le graphe ne doit jamais inventer une relation seulement parce que deux nœuds +sont proches visuellement. --- -# Tests +## 13. Pivot EML -Chaque nouveau module doit pouvoir être testé indépendamment. +Statut : -Les tests unitaires ne doivent jamais dépendre de GTK. +```text +PARTIEL +``` + +La branche contient des briques d'analyse EML, d'extraction MIME, d'IBAN, OCR, +ExifTool, vocabulaire contrôlé, propositions bancaires et pipeline de tâche. + +Le flux cible est : + +```text +EML original + ↓ +en-têtes et MIME + ↓ +pièces jointes dérivées + ↓ +empreintes et métadonnées + ↓ +OCR et indicateurs + ↓ +valeurs brutes + normalisées + dérivées + ↓ +révision humaine + ↓ +intégration transactionnelle +``` + +Les valeurs brutes restent immuables. + +Une IP de relais SMTP ne doit pas être présentée comme l'adresse personnelle +d'un suspect. + +Une donnée bancaire observée ne prouve pas l'identité de l'auteur d'une fraude. + +Le ticket Forgejo #107 reste la référence fonctionnelle du chantier. --- -# Évolutivité +## 14. Erreurs et journalisation -L'architecture doit permettre l'ajout de nouveaux modules sans modifier les composants existants. +Les couches basses produisent des erreurs structurées. -Les nouvelles fonctionnalités doivent privilégier l'extension plutôt que la modification. +Les services ajoutent le contexte métier. + +L'application décide : + +- du journal technique ; +- du message utilisateur ; +- du maintien ou du remplacement de la session ; +- de la possibilité de réessayer. + +Les messages ne doivent pas divulguer inutilement : + +- chemins absolus sensibles ; +- données personnelles ; +- contenu complet d'une preuve ; +- secrets ou jetons. --- -# Objectifs à long terme +## 15. Sécurité -Le projet doit permettre : +Règles obligatoires : -- la gestion complète d'une enquête numérique ; -- la conservation de la chaîne de preuve ; -- l'intégration de modules OSINT ; -- l'analyse de fichiers ; -- la génération de rapports professionnels ; -- le packaging multiplateforme. - -Le logiciel doit rester : - -- libre ; -- documenté ; -- modulaire ; -- testable ; -- maintenable. +- requêtes préparées pour les données variables ; +- clés étrangères activées ; +- chemins contrôlés ; +- neutralisation des traversées `../` ; +- aucune ouverture automatique de pièce jointe ; +- aucun chargement automatique de ressource distante d'un e-mail ; +- limites de taille et de profondeur pour les formats complexes ; +- aucune commande shell dynamique ; +- aucune installation automatique d'outil ; +- aucune donnée réelle d'enquête dans les tests ou le dépôt ; +- aucune action intrusive non autorisée. --- -# Conclusion +## 16. Tests -Toute nouvelle fonctionnalité doit respecter cette architecture. +Le cœur, les modèles, DAO, migrations et tâches possèdent des tests ciblés. -En cas de dérogation, celle-ci devra être documentée et justifiée. +Les tests GTK restent limités aux composants qui nécessitent réellement GTK. -L'objectif est de garantir la stabilité du projet tout en facilitant son évolution sur le long terme. +Les scénarios critiques incluent : + +- base neuve ; +- migration ; +- rollback ; +- import interrompu ; +- annulation ; +- erreur d'outil ; +- donnée malformée ; +- doublon ; +- intégrité ; +- clés étrangères ; +- conservation de la valeur brute ; +- absence d'une dépendance optionnelle. + +Validation : + +```sh +make clean +make -j8 +make -j8 test +git diff --check +``` + +--- + +## 17. Règles d'évolution + +Une nouvelle fonctionnalité doit : + +1. respecter la direction des dépendances ; +2. réutiliser les services existants avant d'en créer un concurrent ; +3. définir clairement la propriété mémoire ; +4. ajouter les tests nécessaires ; +5. documenter les formats persistés ; +6. utiliser des fixtures synthétiques ; +7. préserver les données brutes ; +8. maintenir la branche compilable ; +9. mettre à jour l'architecture lorsque ses responsabilités changent. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 8ab7432..7b42cfa 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -1,302 +1,616 @@ # Conventions de développement -Version : 1.0 +> **Version :** 2.0 +> **Dernière mise à jour :** 2026-07-24 +> **Projet :** Labfy Investigation --- -# Philosophie +## 1. Objectif -Labfy Investigation est développé comme un logiciel d'enquête numérique. +Ces conventions définissent les règles communes du dépôt. -Les choix d'architecture privilégient : +Elles visent à garantir : -- la lisibilité ; -- la maintenabilité ; -- la robustesse ; -- la traçabilité ; -- la simplicité. +- un code lisible et maintenable ; +- une séparation claire des responsabilités ; +- la traçabilité des données d'enquête ; +- la stabilité des formats persistés ; +- des tests reproductibles ; +- une documentation qui distingue l'état réel du projet de son historique. -Une solution simple et cohérente est toujours préférée à une solution -complexe. +Lorsqu'une convention contredit le code courant, le problème doit être résolu : +soit le code est corrigé, soit la convention est mise à jour. La divergence ne +doit pas devenir permanente. --- -# Langue +## 2. Hiérarchie des sources -Le domaine métier est écrit en français. +Pour déterminer l'état réel du projet, utiliser cet ordre de confiance : + +1. code présent sur la branche `main` ; +2. tests automatisés ; +3. scripts SQL et migrations ; +4. commits ; +5. tickets Forgejo fermés ; +6. tickets Forgejo ouverts ; +7. documentation courante ; +8. documents historiques et anciennes roadmaps. + +Un ticket ouvert décrit un chantier, pas une fonctionnalité terminée. + +Un audit nommé `SCHEMA_AUDIT_V1.md` ou `SCHEMA_AUDIT_V9.md` décrit uniquement +la version indiquée. La référence courante est : + +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` + +--- + +## 3. Langue et terminologie + +### 3.1 Code et identifiants techniques + +Le code C, les noms de fichiers, les fonctions, les structures, les constantes +et les codes persistés utilisent un anglais technique cohérent. Exemples : -- preuve -- entite -- personne -- source -- chronologie -- journal -- hypothese -- recherche +```text +evidence_record +entity_dao +relation_service +bank_proposal +controlled_vocab +eml_pipeline_task +created_at +verification_status +``` -Les standards techniques conservent leur nom d'origine. +Les identifiants persistés doivent être stables et indépendants des libellés +affichés. + +Exemple : + +```text +code persistant : proposed +libellé français : Proposé +``` + +Un libellé peut être traduit ou reformulé sans modifier le code persistant. + +### 3.2 Interface et documentation + +L'interface utilisateur et la documentation destinée aux utilisateurs sont +rédigées en français. + +Les termes juridiques ou métier restent en français dans les textes lorsque +cela améliore la précision. + +### 3.3 Abréviations + +Les abréviations sont limitées aux formes techniques reconnues : + +```text +UUID +SHA-256 +MIME +UTC +SQL +DAO +OCR +EML +IBAN +BIC +``` + +Les noms de variables raccourcis sans nécessité sont interdits. + +Préférer : + +```c +relative_path +verification_status +evidence_record +created_at +``` + +Éviter : + +```c +path +stat +rec +crt +``` + +--- + +## 4. Organisation et dépendances entre couches + +Le projet suit une architecture en couches : + +```text +Interface GTK4 + ↓ +Application et contrôleurs + ↓ +Services métier et tâches + ↓ +DAO et adaptateurs + ├── SQLite + ├── système de fichiers + ├── outils externes + └── futures API + ↓ +Modèles métier +``` + +Règles obligatoires : + +- le cœur métier ne dépend pas de GTK ; +- les modèles ne connaissent ni GTK ni SQLite ; +- les vues et widgets n'exécutent aucune requête SQL ; +- les vues et widgets ne manipulent pas directement les preuves sur disque ; +- les migrations, connexions, statements et transactions appartiennent à la + couche Database ; +- les requêtes métier appartiennent aux DAO ; +- les services orchestrent les opérations impliquant plusieurs DAO ou + adaptateurs ; +- les opérations longues sont exécutées dans des tâches asynchrones ; +- le graphe est une projection de SQLite, jamais une seconde source de vérité. + +Chaque module possède une responsabilité clairement identifiable. + +--- + +## 5. Code C + +### 5.1 Standard + +Le projet utilise exclusivement : + +```text +C17 +``` + +Le Makefile principal compile avec : + +```text +-std=c17 -Wall -Wextra -Werror +``` + +Plusieurs cibles de tests ajoutent également `-Wpedantic`. + +Aucun avertissement ne doit être ignoré sans justification documentée. + +### 5.2 Nommage + +- fichiers : `snake_case.c` et `snake_case.h` ; +- fonctions : `snake_case` ; +- variables : noms explicites ; +- constantes : `UPPER_SNAKE_CASE` ; +- types publics : `PascalCase` lorsque cela correspond aux conventions GLib ; +- fonctions publiques préfixées par leur module. Exemples : -- uuid -- sha256 -- mime_type -- sqlite -- created_at -- updated_at -- relative_path +```c +database_open() +evidence_dao_insert() +relation_service_create() +eml_pipeline_task_new() +``` ---- +### 5.3 Structures -# Architecture - -Le projet est organisé par domaine métier. +Les structures publiques sont opaques lorsque cela protège les invariants du +module. Exemple : -``` -preuve - ↓ -preuve.h -preuve.c - -entite - ↓ -entite.h -entite.c +```c +typedef struct EvidenceRecord EvidenceRecord; ``` -Chaque module possède une responsabilité unique. +Un champ ne doit être public que lorsque l'accès direct est réellement prévu +par l'API. + +### 5.4 Mémoire + +Toute allocation possède un propriétaire clair. + +Chaque API doit permettre de déterminer : + +- qui alloue ; +- qui libère ; +- si une chaîne est empruntée ou copiée ; +- si une structure peut survivre au module qui l'a créée ; +- si un callback transfère la propriété. + +Les conventions GLib sont utilisées de manière cohérente : + +```text +_new() retourne généralement une nouvelle référence +_ref() ajoute une référence +_unref() retire une référence +_free() libère un objet non référencé +_dup_*() retourne une copie possédée +_peek_*() retourne une valeur empruntée +``` + +### 5.5 Erreurs + +Les erreurs attendues sont remontées avec `GError` ou l'abstraction d'erreur du +module concerné. + +Une fonction ne doit pas : + +- masquer une erreur importante ; +- transformer silencieusement un échec en succès partiel ; +- afficher directement une boîte de dialogue depuis le cœur métier ; +- journaliser des données sensibles sans nécessité. + +Les erreurs techniques sont journalisées. L'application décide de leur +présentation graphique. --- -# SQL +## 6. SQLite -Une table représente un objet métier. +### 6.1 Version courante -Une table importante possède : +La version courante du schéma est : -- une structure C ; -- un module C ; -- des tests. - -Les objets métier utilisent : - -``` -TEXT PRIMARY KEY +```text +V10 ``` -contenant un UUID. +Les scripts versionnés sont conservés dans : -Les tables de référence utilisent : - -``` -INTEGER PRIMARY KEY +```text +database/schema_v1.sql +... +database/schema_v10.sql ``` ---- +Le complément idempotent du schéma courant est : -# UUID - -Tous les objets métier utilisent un UUID. - -Exemple : - -``` -preuve -entite -personne -source -chronologie -journal +```text +database/schema_current.sql ``` -Il n'existe pas simultanément : +### 6.2 Identifiants -``` -id -uuid +Les objets métier utilisent généralement : + +```sql +id TEXT PRIMARY KEY ``` -La colonne : +avec un UUID généré par l'application. -``` -id -``` +Les tables de référence peuvent utiliser un identifiant entier lorsque cela +correspond à leur rôle. -contient directement l'UUID. +La convention doit être vérifiée table par table : aucune généralisation ne +doit remplacer la lecture du schéma réel. ---- +### 6.3 Dates -# Dates +Les dates persistées utilisent l'UTC. -Toutes les dates sont enregistrées en UTC. +Format attendu lorsque la table impose une date complète : -Format : - -``` +```text YYYY-MM-DDTHH:MM:SSZ ``` +La conversion vers l'heure locale est réservée à l'affichage. + +### 6.4 Requêtes + +Toute valeur variable utilise une requête préparée : + +```c +sqlite3_prepare_v2() +sqlite3_bind_*() +sqlite3_step() +``` + +La concaténation de données utilisateur dans une requête SQL est interdite. + +Les requêtes SQL statiques peuvent être exécutées avec `sqlite3_exec()` lorsque +cela reste adapté. + +### 6.5 Transactions + +Toute opération portant sur plusieurs écritures liées doit être atomique. + +Exemples : + +- création d'une enquête ; +- import d'une preuve ; +- reclassement d'une preuve ; +- création d'une relation avec ses preuves ; +- intégration de propositions OSINT ; +- migration de schéma ; +- validation finale d'un pivot EML. + +En cas d'échec, les écritures partielles sont annulées et les modifications du +système de fichiers sont restaurées ou nettoyées. + +### 6.6 Migrations + +Toute évolution persistante doit : + +1. définir une nouvelle version ; +2. ajouter un script `schema_vN.sql` ; +3. ajouter ou adapter la fonction d'installation ; +4. raccorder la migration depuis la version précédente ; +5. mettre à jour la version courante ; +6. tester une base neuve ; +7. tester une ancienne base migrée ; +8. exécuter `PRAGMA integrity_check` ; +9. exécuter `PRAGMA foreign_key_check` ; +10. mettre à jour l'audit courant et la documentation. + +Une ancienne migration publiée ne doit pas être réécrite pour modifier son +sens historique. + +### 6.7 Accès par couche + +- `src/database` : infrastructure SQLite, schéma, statements, transactions, + erreurs et migrations ; +- `src/dao` : requêtes métier ; +- `src/core` : orchestration métier ; +- `src/views` et `src/widgets` : aucun SQL direct. + --- -# Chemins +## 7. Fichiers et preuves -Les chemins sont toujours relatifs à la racine de l'enquête. +### 7.1 Chemins + +Les chemins persistés dans une enquête sont relatifs à sa racine. Autorisé : -``` +```text 01_Preuves_Originales/Documents/facture.pdf ``` Interdit : +```text +/home/utilisateur/Documents/facture.pdf ``` -/home/user/Documents/... + +Une entrée externe peut être absolue pendant l'import, mais le chemin enregistré +dans l'enquête doit respecter le modèle prévu par le schéma. + +### 7.2 Immutabilité des preuves originales + +Une preuve originale n'est jamais modifiée. + +Toute opération produisant : + +- une annotation ; +- une conversion ; +- une extraction ; +- un OCR ; +- une analyse ; +- une version expurgée ; + +crée un nouvel objet ou un nouveau fichier dérivé. + +### 7.3 Valeurs brutes et valeurs interprétées + +Les données suivantes restent distinctes : + +```text +valeur brute +valeur normalisée +valeur dérivée +correction utilisateur +statut de vérification +confiance +provenance ``` +Une valeur brute ne doit jamais être réécrite pour correspondre à une +interprétation ultérieure. + +Un résultat OCR ou OSINT est une proposition à vérifier, pas un fait confirmé. + +### 7.4 Suppression + +La suppression logique est privilégiée pour les objets de traçabilité, mais la +règle exacte dépend de chaque table et de chaque DAO. + +Une suppression physique n'est autorisée que lorsque : + +- le schéma la permet explicitement ; +- le service métier l'encadre ; +- les conséquences sur les clés étrangères et les fichiers sont testées ; +- la traçabilité requise est préservée. + --- -# Suppression +## 8. Outils externes et réseau -Les objets métier importants ne sont jamais supprimés immédiatement. +Les outils externes sont optionnels sauf décision explicite contraire. -Une suppression est une modification d'état. - -Exemple : - -``` -active -archived -deleted -``` - -Une purge physique éventuelle devra être explicite. - ---- - -# Nommage - -Le SQL utilise : - -- snake_case -- minuscules -- aucun accent -- aucun espace - ---- - -# Code C - -Norme : - -``` -C17 -``` - -Variables : - -Toujours explicites. - -Autorisé : - -```c -relative_path -description -commentaire -created_at -``` +Ils sont lancés avec `GSubprocess` et une liste d'arguments séparés. Interdit : ```c -path -desc -comm -crt +system(dynamic_command); ``` -Les fonctions utilisent le nom du module. +Interdit également : + +- construire une commande shell par concaténation ; +- ouvrir automatiquement une pièce jointe ; +- charger automatiquement une ressource distante d'un e-mail HTML ; +- installer automatiquement un outil ; +- utiliser un secret découvert ; +- contourner une authentification ; +- effectuer une action intrusive non autorisée. + +Chaque exécution doit pouvoir conserver : + +- l'outil ; +- sa version ; +- les arguments ; +- la date UTC ; +- la cible ; +- le code de retour ; +- `stdout` et `stderr` lorsque nécessaire ; +- les empreintes des sorties persistées ; +- les objets créés ou réutilisés. + +--- + +## 9. Asynchronisme + +Toute opération susceptible de bloquer l'interface doit être exécutée hors du +thread GTK principal. + +Exemples : + +- copie ou hachage de fichiers ; +- import massif ; +- chargement du graphe ; +- interrogation réseau ; +- lancement d'un outil ; +- OCR ; +- extraction de métadonnées ; +- analyse EML ; +- génération de rapport. + +Une tâche longue doit prévoir, lorsque cela est possible : + +- un état ; +- une progression ; +- une annulation ; +- un résultat ; +- une erreur ; +- une date de début ; +- une date de fin. + +Les écritures SQLite concurrentes doivent être évitées ou sérialisées par +l'architecture prévue. + +--- + +## 10. Tests + +Toute fonctionnalité importante possède des tests adaptés. + +Les tests couvrent selon le cas : + +- arguments invalides ; +- cas nominal ; +- échecs ; +- annulation ; +- rollback ; +- responsabilités mémoire ; +- limites de taille ; +- entrées malformées ; +- anciennes versions de base ; +- intégrité et clés étrangères ; +- régressions. + +Les tests utilisent uniquement des données synthétiques. + +Il est interdit de placer dans le dépôt ou de fournir à un agent de +développement : + +- une base `Enquete.sqlite` réelle ; +- des captures réelles ; +- des e-mails réels ; +- des RIB réels ; +- des pièces jointes réelles ; +- toute donnée personnelle issue d'une enquête. + +Validation recommandée : + +```sh +make clean +make -j8 +make -j8 test +git diff --check +``` + +Une exécution séquentielle est utilisée seulement si la parallélisation +provoque un échec réel et identifié : + +```sh +make +make test +``` + +--- + +## 11. Git et tickets + +Forgejo est la source de vérité du suivi. + +À partir des tickets postérieurs à l'historique numéroté manuellement, le titre +ne contient pas de numéro ajouté à la main : Forgejo attribue le numéro. + +Un ticket peut nécessiter plusieurs commits. + +Chaque commit doit : + +- porter un changement cohérent ; +- compiler ; +- conserver la branche stable ; +- inclure ou adapter les tests nécessaires ; +- ne contenir aucune donnée réelle d'enquête. + +Les messages de commit sont rédigés en anglais. Exemple : -```c -preuve_create() -preuve_load() -preuve_update() -preuve_delete() +```text +feat(database): add bank account entities ``` +Aucun commit n'est effectué tant que la fonction concernée ne marche pas et que +la validation prévue n'a pas été réalisée. + --- -# Structures +## 12. Documentation -Une structure représente un objet métier. +Toute décision importante est documentée. -Exemple : +Une modification doit mettre à jour les documents concernés dans le même +chantier, notamment pour : -```c -typedef struct Preuve Preuve; +- l'architecture ; +- les conventions ; +- les dépendances ; +- le schéma SQLite ; +- les migrations ; +- les formats persistés ; +- les procédures de compilation et de test ; +- les limitations légales ou techniques. + +La documentation doit indiquer clairement l'un des statuts suivants lorsque +cela évite une ambiguïté : + +```text +IMPLÉMENTÉ +PARTIEL +PRÉVU +HISTORIQUE ``` -Les structures publiques sont opaques lorsque cela est possible. - ---- - -# Tests - -Toute nouvelle fonctionnalité importante possède un test. - -Le développement suit toujours l'ordre : - -``` -Conception - -↓ - -Implémentation - -↓ - -Tests - -↓ - -Commit -``` - ---- - -# Git - -Un ticket terminé correspond à un commit. - -Le message de commit est rédigé en anglais. - -Exemple : - -``` -feat(database): initialize investigation database -``` - ---- - -# Documentation - -Les décisions importantes sont documentées. - -Les changements de schéma SQLite sont précédés d'un audit. - -Aucune décision importante ne doit exister uniquement dans le code. - ---- - -# Objectif - -Le projet doit rester compréhensible plusieurs années après sa création. - -La priorité est donnée à la qualité du code plutôt qu'à la rapidité de -développement. +La priorité reste la qualité, la traçabilité et la compréhension durable du +projet. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 7fae127..d8cf68e 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,722 +1,568 @@ -# Développement +# Guide de développement -Version : 1.0 - -Dernière mise à jour : 2026-07-06 - -Auteur : fy59 - -# Sommaire - -1. Objet -2. Objectif -3. Technologies -4. Outils -5. Commandes -6. Revue de code -7. Philosophie -8. Architecture -9. Règles de codage -10. Documentation -11. Organisation des fichiers -12. Gestion mémoire -13. Base de données -14. Git -15. Développement -16. Tests -17. Gestion des erreurs -18. Convention de nommage - - Fichiers - - Fonctions - - Variables - - Types - - Constantes - - Énumérations -19. Principes de conception - - Simplicité - - Lisibilité - - Responsabilité unique - - Zéro surprise - - Style de code - - Le compilateur est notre premier relecteur - - Documentation - - Boy Scout Rule - - Robustesse avant optimisation - - Une fonctionnalité = un commit -20. Décisions techniques -21. Branche principale -22. Dépendances ---- - -## Objet - -Ce document définit les règles de développement du projet **Labfy Investigation**. - -L'objectif est de garantir un code : - -- lisible ; -- maintenable ; -- documenté ; -- portable ; -- simple à faire évoluer. - -Ces règles s'appliquent à l'ensemble du projet. +> **Version :** 2.0 +> **Dernière mise à jour :** 2026-07-24 +> **Projet :** Labfy Investigation --- -# Objectif +## 1. Objet -L'objectif du projet est de produire un logiciel libre, robuste et documenté destiné à faciliter la gestion d'enquêtes OSINT, tout en constituant un support d'apprentissage du langage C, de GTK4, de SQLite et des bonnes pratiques de développement logiciel. +Ce document décrit l'environnement et le workflow de développement. +Les règles d'architecture se trouvent dans : +```text +docs/ARCHITECTURE.md +docs/CONVENTIONS.md +docs/database/DATABASE_ARCHITECTURE.md +``` + +Forgejo est la source de vérité des tickets : + +```text +https://git.labfytools.com/fy59/labfy-investigation/issues +``` --- -# Technologies +## 2. Environnements -Le projet repose sur les technologies suivantes : +### 2.1 Environnement principal -| Technologie | Version | -|-------------|----------| -| Langage | C17 | -| Interface graphique | GTK 4.10+ | -| Base de données | SQLite 3.45+ | -| Compilateur | GCC 15+ | -| Build | Make | -| Documentation | Doxygen | -| Gestion de version | Git | +Le développement courant est réalisé sous Arch Linux. + +### 2.2 Cible de distribution + +Ubuntu est la cible principale de distribution, notamment pour un futur +déploiement dans des environnements institutionnels. + +Le code ne doit pas dépendre d'un paquet AUR. + +Les dépendances optionnelles doivent se désactiver proprement lorsqu'elles sont +absentes. + +### 2.3 Interface graphique + +Le projet utilise GTK4 et doit rester compatible avec Wayland et X11 lorsque +GTK le permet. + +Aucune hypothèse ne doit dépendre de la présence d'une barre de titre fournie +par le gestionnaire de fenêtres. --- -# Outils +## 3. Dépendances de compilation -Les outils suivants sont utilisés pendant le développement : +Le Makefile utilise `pkg-config` pour GTK4 et SQLite. -- gcc -- clang -- clang-format -- clang-tidy -- cppcheck -- valgrind -- doxygen -- graphviz -- make -- Git +### Arch Linux + +```sh +sudo pacman -S --needed \ + base-devel \ + pkgconf \ + gtk4 \ + glib2 \ + sqlite +``` + +### Ubuntu + +```sh +sudo apt update +sudo apt install \ + build-essential \ + pkg-config \ + libgtk-4-dev \ + libglib2.0-dev \ + libsqlite3-dev +``` + +Les versions minimales exactes doivent correspondre aux API réellement utilisées +dans le code. Elles ne doivent pas être inventées dans la documentation si le +système de build ne les impose pas. + +Les outils OSINT, OCR, métadonnées ou PDF sont documentés séparément et restent +optionnels sauf décision explicite. --- -# Commandes +## 4. Récupération du dépôt -Compilation : +```sh +git clone https://git.labfytools.com/fy59/labfy-investigation.git +cd labfy-investigation +``` +Avant de commencer : + +```sh +git status +git pull --ff-only +``` + +Ne pas écraser un travail local non validé. + +--- + +## 5. Compilation + +### 5.1 Compilation recommandée + +```sh +make -j8 +``` + +Le projet utilise globalement : + +```text +-std=c17 +-Wall +-Wextra +-Werror +``` + +Plusieurs cibles de tests ajoutent `-Wpedantic`. + +### 5.2 Compilation séquentielle + +Utiliser une compilation séquentielle seulement lorsque l'exécution parallèle +provoque un échec réel et identifié : + +```sh make +``` -Exécution : +Une erreur de code ne doit pas être masquée en supprimant simplement `-j8`. -make run - -Nettoyage : +### 5.3 Nettoyage +```sh make clean +``` -Documentation : +### 5.4 Lancement -make docs +```sh +make run +``` -Tests : +ou : +```sh +./labfy-investigation +``` + +### 5.5 Documentation générée + +Le Makefile courant ne fournit pas de cible `make docs`. + +Ne pas documenter ou utiliser cette commande tant qu'une cible réelle n'a pas +été ajoutée et testée. + +--- + +## 6. Tests + +### 6.1 Suite complète + +```sh +make -j8 test +``` + +En cas de problème réellement causé par la parallélisation : + +```sh make test - ---- - -# Revue de code - -Avant chaque commit important, le code doit être vérifié selon les critères suivants : - -- respecte les conventions de nommage ; -- compile sans warning ; -- est documenté ; -- respecte l'architecture MVC ; -- ne duplique pas de code ; -- gère correctement les erreurs ; -- libère correctement les ressources. - ---- - -# Philosophie - -Labfy Investigation est développé comme un logiciel professionnel. - -Les priorités sont les suivantes : - -1. Simplicité. -2. Lisibilité. -3. Robustesse. -4. Documentation. -5. Évolutivité. - -Un code plus simple est toujours préféré à un code plus complexe. - ---- - -# Architecture - -Le projet suit une architecture de type MVC. - -``` -Vue (GTK) - │ - ▼ -Contrôleur - │ - ▼ -DAO - │ - ▼ -SQLite ``` -Les responsabilités sont clairement séparées. +### 6.2 Test ciblé -Une couche ne doit jamais accéder directement à une couche qui ne lui appartient pas. +Les tests sont des exécutables dans `tests/`. ---- - -# Règles de codage - -Le projet est développé en **C17**. - -Les options de compilation sont : - -- `-std=c17` -- `-Wall` -- `-Wextra` -- `-Wpedantic` -- `-Werror` - -Aucun warning n'est accepté. - -Le projet doit compiler sans erreur ni avertissement. - ---- - -# Documentation - -Chaque fichier possède un en-tête. - -Chaque fonction publique est documentée avec Doxygen. - -Les commentaires expliquent : - -- pourquoi un choix a été fait ; -- les contraintes techniques ; -- les hypothèses. - -Les commentaires ne doivent jamais simplement répéter le code. - ---- - -# Organisation des fichiers - -Chaque fichier possède une responsabilité unique. - -Une fonction ne doit réaliser qu'une seule tâche. - -Lorsque cela devient nécessaire, le code est découpé en plusieurs modules. - ---- - -# Gestion mémoire - -Toute allocation mémoire possède une fonction de libération correspondante. - -Les fuites mémoire sont considérées comme des bugs. - -Les vérifications sont réalisées régulièrement avec Valgrind. - ---- - -# Base de données - -Toutes les opérations sur SQLite passent par la couche DAO. - -Le reste de l'application ne manipule jamais directement SQLite. - ---- - -# Git - -Le dépôt Git contient uniquement : - -- le code source ; -- la documentation ; -- les modèles ; -- les scripts. - -Les enquêtes réelles ne sont jamais versionnées. - -Chaque commit : - -- compile ; -- fonctionne ; -- correspond à une seule fonctionnalité. - -Les messages de commit suivent la convention : +Exemple : +```sh +make tests/test_database +./tests/test_database ``` + +Autre exemple : + +```sh +make tests/test_eml_pipeline_task +./tests/test_eml_pipeline_task +``` + +Le nom exact d'une cible doit être vérifié dans le Makefile. + +### 6.3 Validation avant intégration + +```sh +make clean +make -j8 +make -j8 test +git diff --check +``` + +Vérifier également : + +```sh +git status --short +``` + +Aucun fichier de preuve réel, base réelle ou artefact temporaire ne doit +apparaître. + +--- + +## 7. Workflow d'un ticket + +### 7.1 Avant de coder + +1. lire le ticket Forgejo ; +2. vérifier l'état de la branche `main` ; +3. identifier les modules concernés ; +4. lire les tests existants ; +5. vérifier les migrations si SQLite est concerné ; +6. distinguer clairement ce qui est déjà implémenté de ce qui est seulement + demandé ; +7. préparer uniquement des données synthétiques. + +### 7.2 Pendant le développement + +1. limiter le changement à un objectif cohérent ; +2. compiler régulièrement ; +3. ajouter les tests au fur et à mesure ; +4. conserver une API claire ; +5. respecter les propriétaires mémoire ; +6. éviter toute logique métier dans GTK ; +7. ne pas créer une seconde architecture concurrente ; +8. ne pas toucher aux données réelles d'enquête. + +### 7.3 Avant le commit + +1. lancer la validation complète ; +2. relire le diff ; +3. vérifier les erreurs et chemins de rollback ; +4. vérifier la documentation ; +5. vérifier l'absence de données sensibles ; +6. demander la validation manuelle prévue par le workflow. + +Aucun commit n'est effectué tant que la fonction ne marche pas. + +--- + +## 8. Organisation des modules + +```text +include/core/ interfaces du cœur et des services +include/dao/ interfaces des DAO +include/database/ interfaces SQLite +include/models/ interfaces des modèles +include/views/ interfaces des vues GTK +include/widgets/ interfaces des widgets + +src/core/ services, tâches et orchestration +src/dao/ accès métier à SQLite +src/database/ connexion, schéma, statements, transactions +src/models/ modèles métier +src/views/ fenêtres et dialogues GTK +src/widgets/ widgets réutilisables +``` + +### Ajouter un modèle + +Un modèle doit généralement fournir : + +- un header dans `include/models/` ; +- une implémentation dans `src/models/` ; +- des constructeurs et destructeurs clairs ; +- des validations ; +- un test dans `tests/`. + +Il ne dépend pas de GTK ni de SQLite. + +### Ajouter un DAO + +Un DAO doit généralement fournir : + +- une interface dans `include/dao/` ; +- une implémentation dans `src/dao/` ; +- des statements préparés ; +- une transformation explicite ligne ↔ modèle ; +- des tests sur une base temporaire ; +- des erreurs structurées. + +Il ne contient pas de logique GTK ni d'exécution d'outil. + +### Ajouter un service + +Un service est approprié lorsqu'une opération combine : + +- plusieurs DAO ; +- une transaction ; +- le système de fichiers ; +- une validation métier ; +- un résultat composé. + +Le service définit la frontière transactionnelle. + +### Ajouter une tâche + +Une tâche est appropriée lorsque l'opération peut bloquer l'interface. + +Elle doit définir : + +- ses entrées copiées ou référencées clairement ; +- son annulation ; +- son résultat ; +- son erreur ; +- son nettoyage ; +- la remise du résultat au thread principal. + +### Ajouter une vue ou un widget + +Une vue GTK : + +- collecte l'intention de l'utilisateur ; +- appelle un contrôleur ou un service ; +- présente le résultat ; +- ne manipule pas directement SQLite ; +- ne lance pas de processus ; +- ne déplace pas directement les preuves. + +--- + +## 9. Développement SQLite + +### 9.1 Avant toute modification + +Lire : + +```text +docs/database/DATABASE_ARCHITECTURE.md +docs/database/SCHEMA_AUDIT_CURRENT.md +database/schema_current.sql +database/schema_v10.sql +src/database/database.c +src/database/schema.c +tests/test_database.c +``` + +### 9.2 Nouvelle version de schéma + +Pour créer V11, par exemple : + +1. ajouter `database/schema_v11.sql` ; +2. déclarer et implémenter `schema_install_v11()` ; +3. ajouter `database_migrate_v10_to_v11()` ; +4. raccorder la migration dans la boucle vers la version courante ; +5. mettre à jour les constantes de version ; +6. installer V11 lors de la création d'une base neuve ; +7. adapter `schema_current.sql` si nécessaire ; +8. ajouter une fixture V10 vers V11 ; +9. tester une base neuve ; +10. tester le rollback ; +11. vérifier l'intégrité et les clés étrangères ; +12. mettre à jour l'audit courant ; +13. créer l'audit versionné de V11. + +Ne pas réécrire une ancienne migration publiée pour changer sa signification. + +### 9.3 Vérifications SQLite + +Sur une base synthétique : + +```sql +PRAGMA integrity_check; +PRAGMA foreign_key_check; +SELECT value +FROM metadata +WHERE key = 'schema_version'; +``` + +### 9.4 Transactions et fichiers + +Lorsqu'une opération combine SQLite et le système de fichiers : + +- préparer les fichiers temporaires ; +- vérifier les empreintes ; +- ouvrir la transaction au moment approprié ; +- ne valider qu'après toutes les étapes critiques ; +- nettoyer ou restaurer les fichiers en cas d'échec ; +- tester explicitement le rollback. + +--- + +## 10. Outils externes + +Avant d'intégrer un outil : + +1. vérifier sa licence ; +2. vérifier son usage légal ; +3. vérifier sa disponibilité Arch et Ubuntu ; +4. documenter son caractère obligatoire ou optionnel ; +5. ajouter sa détection au registre si nécessaire ; +6. utiliser `GSubprocess` ; +7. transmettre les arguments séparément ; +8. définir un délai maximal ; +9. gérer l'annulation ; +10. limiter la taille des sorties ; +11. conserver la provenance ; +12. tester son absence. + +Interdit : + +```c +system(command); +``` + +Interdit également de construire une chaîne puis de l'exécuter via un shell. + +Une dépendance absente doit produire un statut clair, pas un plantage. + +--- + +## 11. GTK4 + +### 11.1 Thread principal + +Seul le thread GTK principal modifie les widgets. + +Les résultats d'une tâche sont transférés vers ce thread par les mécanismes +GLib adaptés. + +### 11.2 Dialogues + +Un dialogue : + +- valide ses entrées ; +- ne conserve pas de pointeur vers une session détruite ; +- permet l'annulation ; +- ne réalise pas une opération longue directement ; +- présente un résumé avant une écriture importante. + +### 11.3 Messages utilisateur + +Les détails techniques restent dans les journaux. + +Le message graphique indique : + +- ce qui a échoué ; +- les conséquences ; +- ce qui a été conservé ou annulé ; +- l'action possible. + +--- + +## 12. Mémoire et diagnostic + +Compiler avec les avertissements activés est obligatoire. + +Pour une erreur mémoire, utiliser les outils disponibles localement sans +modifier durablement les options du dépôt. + +Exemple avec Valgrind lorsque l'application et l'environnement le permettent : + +```sh +valgrind \ + --leak-check=full \ + --show-leak-kinds=all \ + ./tests/test_cible +``` + +Les faux positifs provenant de bibliothèques externes doivent être distingués +des allocations du projet. + +Une tâche annulée, une erreur SQLite et un échec de processus doivent tous +libérer leurs ressources. + +--- + +## 13. Données de test et sécurité + +Le dépôt et les agents de développement utilisent uniquement des fixtures +synthétiques. + +Ne jamais fournir à un agent local ou versionner : + +```text +Enquete.sqlite réelle +captures réelles +conversations réelles +e-mails réels +RIB ou IBAN réels +pièces jointes réelles +documents d'identité réels +sorties OSINT contenant des données personnelles réelles +``` + +Les tests doivent utiliser : + +- domaines réservés comme `example.com` ; +- adresses IP de documentation ; +- noms fictifs ; +- IBAN de test explicitement synthétiques ; +- fichiers générés pendant le test ; +- bases SQLite temporaires. + +Avant chaque commit : + +```sh +git diff --check +git status --short +``` + +Inspecter tout nouveau fichier inhabituel à la racine du dépôt. + +--- + +## 14. Git + +Les messages de commit sont en anglais. + +Format recommandé : + +```text type(scope): description ``` Exemples : -``` -feat(gui): create main window - -feat(database): add evidence dao - -fix(core): close sqlite connection - -docs: update architecture -``` - ---- - -# Développement - -Avant toute nouvelle fonctionnalité : - -1. Définir le besoin. -2. Concevoir l'architecture. -3. Développer. -4. Tester. -5. Documenter. -6. Commit. - -Aucune fonctionnalité n'est considérée comme terminée tant que ces six étapes ne sont pas réalisées. - ---- - -# Tests - -Chaque fonctionnalité doit être testée avant son intégration. - -Lorsque cela est possible : - -- tests unitaires ; -- tests fonctionnels ; -- vérification sous Valgrind ; -- compilation sans warning. - -Un correctif est toujours accompagné d'un test permettant de vérifier que le problème est résolu. - ---- - -# Gestion des erreurs - -Aucune erreur ne doit être ignorée. - -Les valeurs de retour des fonctions sont systématiquement vérifiées. - -Les messages d'erreur doivent être explicites et permettre d'identifier rapidement l'origine du problème. - -Les ressources ouvertes doivent toujours être libérées, même en cas d'erreur. - ---- - -# Convention de nommage - -Afin de garantir la cohérence du projet, une convention de nommage stricte est appliquée. - -Toute dérogation à cette convention doit être justifiée. - ---- - -## Fichiers - -Les noms de fichiers sont écrits en **snake_case**. - -Exemples : - ```text -database.c -database.h - -preuve.c -preuve.h - -main_window.c -main_window.h - -types_entite.c -types_entite.h +feat(email): add MIME attachment extraction +fix(database): rollback failed V10 migration +test(relations): cover canonical type reuse +docs(architecture): align documentation with V10 ``` -Les noms doivent être explicites et refléter la responsabilité du module. +Un ticket peut être découpé en plusieurs commits cohérents. + +Ne pas ajouter manuellement un numéro dans le titre d'un nouveau ticket : +Forgejo le fournit. + +Ne pas effectuer de commit ou de push avant la validation manuelle prévue par +le workflow du projet. --- -## Fonctions - -Les fonctions sont toujours préfixées par le nom du module auquel elles appartiennent. - -Exemples : - -```c -db_open(); -db_close(); - -preuve_new(); -preuve_free(); - -main_window_create(); -main_window_destroy(); -``` - -Les fonctions génériques telles que : - -```c -create(); -init(); -run(); -``` - -sont interdites, car elles deviennent rapidement ambiguës lorsque le projet grandit. - ---- - -## Variables - -Les variables utilisent également la convention **snake_case**. - -Exemples : - -```c -preuve_id - -type_id - -main_window - -database - -source_id - -date_collecte -``` - -Les noms doivent décrire clairement le contenu de la variable. - -Les noms suivants sont à proscrire : - -```c -x - -tmp - -toto - -test -``` - -à l'exception des variables locales très courtes utilisées dans une boucle ou un contexte limité : - -```c -for (size_t i = 0; i < count; ++i) -``` - ---- - -## Types - -Les structures représentent des objets métiers et utilisent le **PascalCase**. - -Exemples : - -```c -typedef struct -{ - ... -} Preuve; - -typedef struct -{ - ... -} Entite; - -typedef struct -{ - ... -} Personne; -``` - ---- - -## Constantes - -Les constantes et macros sont écrites en majuscules avec des underscores. - -Exemples : - -```c -MAX_PATH_LENGTH - -SHA256_LENGTH - -DEFAULT_WINDOW_WIDTH -``` - ---- - -## Énumérations - -Les énumérations utilisent un préfixe correspondant au type. - -Exemple : - -```c -typedef enum -{ - PREUVE_CAPTURE, - PREUVE_EMAIL, - PREUVE_VIDEO -} PreuveType; -``` - ---- - -## Objectif - -Le nom d'un fichier, d'une fonction ou d'une variable doit permettre de comprendre immédiatement son rôle, sans avoir à consulter son implémentation. - -Le code doit être explicite avant d'être concis. - ---- - -# Principes de conception - -Les principes suivants guident le développement de l'ensemble du projet. - -Ils doivent être respectés avant toute considération d'optimisation. - ---- - -## Simplicité - -La solution la plus simple est privilégiée. - -Un code plus court n'est pas forcément un meilleur code. - -La lisibilité prime toujours. - ---- - -## Lisibilité - -Le code doit pouvoir être compris plusieurs mois après son écriture. - -Les noms des fichiers, fonctions, variables et structures doivent être explicites. - ---- - -## Responsabilité unique - -Chaque module possède une responsabilité unique. - -Chaque fonction réalise une seule tâche. - -Si une fonction devient difficile à expliquer, elle doit probablement être découpée. - ---- - -## Zéro surprise - -Le comportement d'une fonction doit être prévisible. - -Le nom d'une fonction doit permettre de comprendre ce qu'elle réalise sans avoir à lire son implémentation. - -Exemple : - -```c -preuve_save(); -``` - -est préférable à : - -```c -save(); -``` - ---- - -# Style de code - -- Indentation : 4 espaces. -- Largeur maximale : 100 colonnes. -- Accolades sur une nouvelle ligne (style Allman). -- Une déclaration par ligne. -- Une instruction par ligne. - ---- - -## Le compilateur est notre premier relecteur - -Les warnings sont considérés comme des erreurs. - -Le projet compile toujours avec : - -- `-Wall` -- `-Wextra` -- `-Wpedantic` -- `-Werror` - ---- - -## Documentation - -Le code explique **comment** fonctionne une fonctionnalité. - -Les commentaires expliquent **pourquoi** elle existe. - -Les commentaires ne doivent jamais simplement répéter le code. - ---- - -## Boy Scout Rule - -À chaque modification d'un fichier, celui-ci doit être laissé dans un état au moins aussi propre qu'avant la modification. - -Cela peut être : - -- améliorer un nom de variable ; -- corriger un commentaire ; -- supprimer du code mort ; -- simplifier une fonction. - ---- - -## Robustesse avant optimisation - -Les optimisations ne sont réalisées que lorsqu'un besoin est identifié et mesuré. - -La robustesse et la lisibilité sont prioritaires. - ---- - -## Une fonctionnalité = un commit - -Chaque commit correspond à une seule fonctionnalité. - -Chaque commit : - -- compile ; -- est testé ; -- est documenté. - -Les messages de commit suivent la convention : - -``` -type(scope): description -``` - -Exemples : - -``` -feat(gui): create main window -feat(database): add evidence dao -fix(core): close sqlite connection -docs: update development guide -``` - ---- - -# Décisions techniques - -Toute décision technique importante doit être documentée. - -Le projet privilégie les choix simples, documentés et facilement maintenables. - -Lorsque plusieurs solutions existent, la préférence est donnée à celle qui facilite la compréhension du code par un nouveau développeur. - ---- - -## Gestion de la mémoire - -Le projet applique une règle unique concernant la propriété des ressources. - -> Le propriétaire crée. -> Le propriétaire détruit. - -Lorsqu'une ressource est transmise à un objet qui en devient propriétaire, le code appelant ne doit plus la libérer. - -Chaque module est responsable uniquement des ressources qu'il possède. - -Cette règle s'applique à toutes les structures du projet. - ---- - -## Bibliothèques autorisées - -Le projet privilégie les bibliothèques éprouvées plutôt que des réimplémentations. - -### Couche Core - -Autorisé : - -- Langage C17 -- GLib -- SQLite - -Interdit : - -- GTK - -Les structures de données fournies par GLib (GPtrArray, GHashTable, GList, etc.) doivent être privilégiées lorsqu'elles répondent au besoin du projet. - ---- - -# Branche principale - -La branche `main` est toujours stable. - -Le projet doit toujours : - -- compiler ; -- démarrer ; -- être documenté. - ---- - -# Dépendances - -Les nouvelles dépendances doivent être justifiées. - -Avant d'ajouter une bibliothèque externe, il convient de vérifier : - -- si la bibliothèque standard suffit ; -- si GTK ou GLib proposent déjà la fonctionnalité ; -- si la nouvelle dépendance apporte un réel bénéfice. - -Labfy Investigation est un projet GTK4 natif. -Aucun nouveau code ne doit utiliser une API dépréciée ou héritée de GTK3. -Les nouveaux développements utilisent exclusivement les composants modernes de GTK4. - ---- - -# Licence - -Le projet est distribué sous la licence MIT. - -Toute nouvelle contribution est considérée comme publiée sous cette même licence. - -Le texte complet de la licence est disponible dans le fichier `LICENSE` situé à la racine du projet. - ---- - -# Historique - -## Version 1.0 - -- Création du guide de développement. -- Définition des conventions de codage. -- Définition de l'architecture. -- Définition des règles Git. +## 15. Revue finale + +Avant de considérer une modification terminée : + +- [ ] le code respecte C17 ; +- [ ] les dépendances entre couches sont correctes ; +- [ ] la propriété mémoire est claire ; +- [ ] les erreurs sont remontées ; +- [ ] les opérations longues sont asynchrones ; +- [ ] les requêtes utilisent des paramètres liés ; +- [ ] les transactions possèdent un rollback testé ; +- [ ] les preuves originales restent intactes ; +- [ ] les valeurs brutes restent intactes ; +- [ ] les tests utilisent des données synthétiques ; +- [ ] `make -j8` passe ; +- [ ] `make -j8 test` passe ; +- [ ] `git diff --check` passe ; +- [ ] la documentation est à jour. diff --git a/docs/DOCUMENTATION_AUDIT_V10.md b/docs/DOCUMENTATION_AUDIT_V10.md new file mode 100644 index 0000000..a9b7577 --- /dev/null +++ b/docs/DOCUMENTATION_AUDIT_V10.md @@ -0,0 +1,781 @@ +# Audit de la documentation — état V10 + +> Projet : Labfy Investigation +> Date : 2026-07-24 +> Branche examinée : `main` +> Commit de référence : `613d2096bc5eeb2c1c4f60ae701292e19a2abe66` +> Schéma SQLite courant : V10 +> Tickets ouverts au moment de l’audit : `#107` et `#42` + +## Conclusion générale + +La documentation doit être remise à niveau. + +Le `README.md` a déjà reçu plusieurs ajouts récents et reste globalement utile. +En revanche, les documents de référence situés dans `docs/` décrivent encore +en grande partie l’architecture du premier socle ou de la V1 SQLite. + +Le problème principal n’est pas l’absence de documentation, mais le mélange +entre : + +- l’architecture historique ; +- l’architecture cible ; +- les fonctionnalités déjà implémentées ; +- les tickets encore ouverts ; +- le schéma SQLite réellement courant. + +Ce mélange a déjà provoqué une mauvaise interprétation par un agent local, qui +a présenté la V1 et le ticket #023 comme l’état actuel du dépôt. + +## Ordre de confiance à documenter + +Toute analyse du projet doit respecter cet ordre : + +1. code présent sur `main` ; +2. tests automatisés ; +3. migrations et scripts SQL ; +4. commits ; +5. tickets Forgejo fermés ; +6. tickets Forgejo ouverts ; +7. documentation générale ; +8. documents historiques et anciennes roadmaps. + +Un ticket ouvert décrit un chantier, pas une fonctionnalité terminée. + +Un audit versionné décrit la version qu’il nomme, pas automatiquement la +version courante. + +--- + +# Matrice des documents + +| Document | État | Priorité | Action | +|---|---|---:|---| +| `README.md` | Partiellement à jour | Haute | Corriger l’état courant et les commandes | +| `CHANGELOG.md` | Incomplet | Haute | Documenter V10 et le pivot EML préparatoire | +| `docs/ARCHITECTURE.md` | Obsolète | Critique | Réécrire l’architecture actuelle | +| `docs/DEVELOPMENT.md` | Partiellement faux | Critique | Aligner sur Makefile et couches réelles | +| `docs/CONVENTIONS.md` | Obsolète par endroits | Haute | Aligner langue, SQL, suppression et Git | +| `docs/ROADMAP.md` | Très obsolète | Critique | Remplacer par une roadmap vivante | +| `docs/BACKLOG.md` | Vide | Haute | Supprimer ou rediriger vers Forgejo | +| `docs/DEPENDENCE.md` | Globalement utile | Moyenne | Vérifier les outils réellement invoqués | +| `docs/database/DATABASE_ARCHITECTURE.md` | Marqué V1 | Critique | Transformer en architecture V10 | +| `docs/database/SCHEMA_AUDIT_V1.md` | Historique non signalé | Critique | Déplacer et ajouter un avertissement | +| `docs/database/SCHEMA_AUDIT_CURRENT.md` | À ajouter | Critique | Référence courante V10 | +| `docs/database/audits/SCHEMA_AUDIT_V10.md` | À ajouter | Haute | Photographie versionnée de V10 | + +--- + +# 1. README.md + +## Éléments corrects + +Le README décrit correctement : + +- le dépôt Forgejo comme source principale ; +- le caractère non opérationnel du logiciel ; +- le cadre légal et éthique ; +- l’autonomie d’une enquête ; +- l’immutabilité des preuves originales ; +- SQLite comme source de vérité ; +- l’exécution asynchrone ; +- l’interdiction de construire des commandes shell dynamiques ; +- une grande partie des fonctionnalités ajoutées jusqu’à V9/V10. + +## Mises à jour nécessaires + +### Ajouter explicitement le schéma courant + +Ajouter dans l’état du projet : + +```text +Version du schéma SQLite : V10 +``` + +avec un lien vers : + +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` + +### Mettre à jour les fonctionnalités présentes + +Ajouter dans la liste du socle actuel : + +- pipeline EML asynchrone préparatoire ; +- extraction MIME sécurisée ; +- assainissement des noms de pièces jointes ; +- propositions bancaires IBAN/BIC ; +- vocabulaire contrôlé ; +- table `bank_account_entities` ; +- types canoniques de relations liés au pivot e-mail ; +- tests `test_controlled_vocab`, `test_bank_proposal` et + `test_eml_pipeline_task`. + +Préciser que le ticket `#107` reste ouvert et que le flux complet de révision +et d’intégration n’est pas encore terminé. + +### Corriger le prochain chantier + +Le texte indiquant que le prochain chantier porte sur l’initialisation +asynchrone du registre d’outils est obsolète. + +Le chantier actif est désormais : + +```text +#107 — Pivot e-mail forensique +``` + +Le ticket `#42` reste l’inventaire permanent des outils OSINT. + +### Corriger les commandes de validation + +Utiliser : + +```sh +make clean +make -j8 +make -j8 test +git diff --check +``` + +Prévoir un retour séquentiel uniquement si l’exécution parallèle échoue pour +une raison réelle. + +--- + +# 2. CHANGELOG.md + +## Problème + +Le changelog ne reflète pas encore correctement l’ampleur du commit V10. + +## Ajouts à documenter + +Dans une section `Unreleased` ou `0.1.0-dev`, ajouter au minimum : + +- schéma SQLite V10 ; +- table `bank_account_entities` ; +- statuts de vérification et provenances contrôlés ; +- nouveaux types système de relations ; +- pipeline EML asynchrone ; +- extraction MIME sécurisée ; +- détection et proposition IBAN/BIC ; +- vocabulaire contrôlé ; +- premiers objets d’intégration EML ; +- tests associés ; +- migration V9 vers V10 ; +- mise à jour de `schema_current.sql`. + +## Règle recommandée + +Le changelog doit décrire les capacités livrées, pas seulement les premiers +modules historiques de la fenêtre GTK. + +--- + +# 3. docs/ARCHITECTURE.md + +## Problèmes observés + +Le document date du 14 juillet et décrit essentiellement le premier socle. + +Il ne représente pas correctement : + +- `src/dao` et `include/dao` ; +- les services métier ; +- les tâches asynchrones ; +- le gestionnaire de tâches ; +- le registre et le catalogue d’outils ; +- la provenance OSINT ; +- le graphe d’enquête ; +- les types canoniques de relations ; +- les extractions ; +- les comptes sociaux ; +- les personnes et leurs rôles ; +- le pipeline EML ; +- les propositions bancaires ; +- le vocabulaire contrôlé. + +La phrase suivante est désormais incorrecte : + +```text +Aucune requête SQL ne doit apparaître ailleurs. +``` + +Le dépôt possède une couche DAO contenant les requêtes métier. + +## Architecture à documenter + +```text +Interface GTK4 + ↓ +Application et contrôleurs + ↓ +Services métier / tâches + ↓ +DAO et adaptateurs + ├── SQLite + ├── système de fichiers + ├── outils externes + └── futures API + ↓ +Modèles métier +``` + +## Règle SQL correcte + +- l’infrastructure SQLite, les migrations et les transactions appartiennent à + `src/database` ; +- les requêtes métier appartiennent aux DAO ; +- les widgets et vues n’accèdent jamais directement à SQLite ; +- les modèles ne connaissent pas SQLite. + +## Organisation actuelle à ajouter + +```text +include/core/ +include/dao/ +include/database/ +include/models/ +include/views/ +include/widgets/ + +src/core/ +src/dao/ +src/database/ +src/models/ +src/views/ +src/widgets/ +``` + +## Statuts à utiliser + +Pour éviter les ambiguïtés, chaque grande capacité doit être marquée : + +```text +IMPLÉMENTÉ +PARTIEL +PRÉVU +HISTORIQUE +``` + +--- + +# 4. docs/DEVELOPMENT.md + +## Incohérences avec le Makefile + +### Cible `make docs` + +Le document mentionne : + +```sh +make docs +``` + +mais le Makefile courant ne définit pas de cible `docs`. + +Action : + +- supprimer cette commande ; +- ou créer réellement une cible Doxygen avant de la documenter. + +### Options de compilation + +Le document affirme que tout le projet utilise : + +```text +-Wpedantic +``` + +Le Makefile principal utilise globalement : + +```text +-std=c17 -Wall -Wextra -Werror +``` + +`-Wpedantic` est ajouté à plusieurs tests, mais pas aux `CFLAGS` globaux. + +Il faut choisir une seule vérité : + +- ajouter `-Wpedantic` globalement au Makefile ; +- ou corriger le document. + +### Versions minimales + +Le document annonce : + +- GTK 4.10+ ; +- SQLite 3.45+ ; +- GCC 15+. + +Ces versions ne sont pas imposées par le Makefile via `pkg-config`. + +Pour la future cible Ubuntu, annoncer GCC 15+ risque d’exclure inutilement les +postes institutionnels. + +Action : + +- documenter les versions réellement minimales requises par les API utilisées ; +- distinguer l’environnement de développement Arch de la cible minimale + Ubuntu. + +### Architecture MVC + +Le terme MVC est désormais trop réducteur. + +Utiliser plutôt : + +```text +architecture en couches +``` + +avec services, DAO, tâches et adaptateurs. + +### Accès SQLite + +Remplacer : + +```text +Toutes les opérations sur SQLite passent par la couche DAO. +``` + +par : + +```text +Les migrations, connexions, statements et transactions appartiennent à la +couche Database. Les requêtes métier passent par les DAO. Les vues, widgets et +modèles n’accèdent jamais directement à SQLite. +``` + +### Commandes + +Mettre les commandes recommandées à jour : + +```sh +make clean +make -j8 +make -j8 test +git diff --check +``` + +--- + +# 5. docs/CONVENTIONS.md + +## Langue du code + +Le document affirme que le domaine métier est écrit en français, avec des +exemples tels que `preuve.c` et `entite.c`. + +Le code actuel utilise principalement des noms techniques anglais : + +```text +evidence_record +entity_dao +relation_service +bank_proposal +controlled_vocab +eml_pipeline_task +``` + +## Convention proposée + +- code C, noms de fichiers, fonctions, structures et codes persistés : anglais + technique cohérent ; +- libellés de l’interface et documentation utilisateur : français ; +- termes juridiques et métier : français dans les textes ; +- codes persistés : anglais stable, sans dépendre du libellé affiché. + +Exemple : + +```text +code persistant : proposed +libellé français : Proposé +``` + +## Suppression + +Le document affirme que les objets importants ne sont jamais supprimés +immédiatement. + +Cette règle doit être qualifiée table par table : + +- suppression logique par défaut pour les objets de traçabilité ; +- suppression physique autorisée uniquement lorsqu’un DAO et les contraintes + métier la prévoient explicitement ; +- aucune affirmation générale non vérifiée. + +## Git + +Remplacer la règle trop stricte : + +```text +Un ticket terminé correspond à un commit. +``` + +par : + +```text +Chaque commit porte un changement cohérent et vérifiable. Un ticket peut +nécessiter plusieurs commits, mais chaque commit doit compiler, être testé et +laisser la branche stable. +``` + +## Schéma + +Ajouter : + +- toute migration possède un script versionné ; +- une base existante est migrée transactionnellement ; +- la version courante est documentée dans + `SCHEMA_AUDIT_CURRENT.md` ; +- les audits anciens sont historiques. + +--- + +# 6. docs/ROADMAP.md + +## Problème critique + +Le document conserve plusieurs générations de roadmap dans le même fichier. + +Il présente encore comme non réalisés : + +- création d’une enquête ; +- validation ; +- initialisation SQLite ; +- `InvestigationProject` ; +- preuves ; +- entités ; +- relations ; +- tâches asynchrones ; +- plusieurs fonctions déjà présentes. + +Il commence également une seconde roadmap au ticket `#031.1`. + +Cette structure est la principale source de confusion documentaire du dépôt. + +## Action recommandée + +Remplacer complètement le fichier par une roadmap courte et vivante. + +Structure proposée : + +```markdown +# Roadmap + +## Source de vérité +Les tickets Forgejo sont la source de vérité du suivi. + +## État courant +- Schéma SQLite : V10 +- Développement actif +- Logiciel non prêt pour la production + +## Chantiers actifs +- #107 — Pivot e-mail forensique + +## Inventaires permanents +- #42 — Arsenal OSINT + +## Prochains axes +- terminer le flux de révision EML ; +- persister les propositions confirmées ; +- améliorer les tests de migration V9 → V10 ; +- mettre à jour le packaging Ubuntu ; +- poursuivre le graphe et les rapports. + +## Historique +Consulter le changelog et les tickets fermés. +``` + +Déplacer l’ancienne roadmap vers : + +```text +docs/archive/ROADMAP_LEGACY.md +``` + +ou la supprimer si Forgejo conserve déjà tout l’historique utile. + +--- + +# 7. docs/BACKLOG.md + +## État + +Le fichier est vide. + +## Action + +Deux choix valables : + +### Choix recommandé + +Supprimer le fichier et utiliser uniquement Forgejo. + +### Alternative + +Conserver un simple pointeur : + +```markdown +# Backlog + +Le backlog actif est suivi dans Forgejo : + +https://git.labfytools.com/fy59/labfy-investigation/issues + +Ce fichier ne décrit pas l’état courant du projet. +``` + +Ne pas dupliquer les tickets dans un backlog Markdown. + +--- + +# 8. docs/DEPENDENCE.md + +## Éléments corrects + +Le document couvre déjà : + +- Tesseract ; +- ExifTool ; +- dig ; +- host ; +- whois ; +- curl ; +- OpenSSL ; +- qpdf ; +- John/pdf2john ; +- Sherlock ; +- Maigret ; +- Holehe. + +## Vérifications nécessaires + +Comparer les exécutables documentés avec : + +- `tool_catalog.c` ; +- `tool_registry.c` ; +- `eml_pipeline_task.c` ; +- `rib_ocr.c` ; +- `exiftool_metadata.c` ; +- `pdf_password_recovery.c`. + +Documenter pour chaque dépendance : + +- obligatoire ou optionnelle ; +- fonctionnalité concernée ; +- commande de détection ; +- commande de version ; +- comportement lorsque l’outil est absent ; +- paquet Arch ; +- paquet Ubuntu ; +- compatibilité avec dépôts institutionnels restreints. + +## Ajout recommandé + +Ajouter une matrice : + +| Outil | Fonction | Obligatoire | Dégradation si absent | +|---|---|---:|---| +| Tesseract | OCR | Non | Analyse partielle | +| ExifTool | Métadonnées | Non | Métadonnées externes absentes | +| dig | DNS | Non | Action DNS indisponible | +| John/pdf2john | PDF protégé | Non | Pas d’audit de mot de passe | + +Ne jamais présenter un outil optionnel comme condition de démarrage. + +--- + +# 9. docs/database/DATABASE_ARCHITECTURE.md + +## Problème critique + +L’en-tête indique encore : + +```text +Statut : Stable (V1) +Schéma : V1 +``` + +alors que la branche contient un schéma V10. + +Le document a reçu un ajout V10 en fin de fichier, mais son titre, son statut et +la majorité de son inventaire restent centrés sur V1. + +## Action recommandée + +Transformer le document en architecture courante V10. + +Nouvel en-tête : + +```markdown +# Architecture de la base de données + +> Statut : architecture courante +> Version du schéma : V10 +> Source de vérité détaillée : SCHEMA_AUDIT_CURRENT.md +``` + +## Éléments à ajouter à l’inventaire + +- `osint_executions` ; +- liaisons de provenance OSINT ; +- `comptes_sociaux` ; +- `person_roles` ; +- `extractions` ; +- tables de disposition et viewport du graphe ; +- `relation_types` ; +- `bank_account_entities`. + +## Accès SQL + +Remplacer la centralisation dans un unique module `database` par la séparation +réelle : + +```text +Database : connexion, statements, transactions, schémas et migrations +DAO : requêtes métier +Services : orchestration transactionnelle +GTK : aucune requête SQL +``` + +## Migrations + +Ajouter un résumé V1 → V10 et renvoyer vers l’audit courant pour les détails. + +--- + +# 10. docs/database/SCHEMA_AUDIT_V1.md + +## Problème + +Le document est facilement interprété comme l’état actuel. + +## Action + +Déplacer vers : + +```text +docs/database/audits/SCHEMA_AUDIT_V1.md +``` + +Ajouter en première ligne : + +```markdown +> [!WARNING] +> Document historique. Cet audit décrit exclusivement la V1. +> Il ne représente pas le schéma courant. +> Consulter ../SCHEMA_AUDIT_CURRENT.md. +``` + +--- + +# 11. Nouveaux documents de base + +Organisation recommandée : + +```text +docs/database/ +├── DATABASE_ARCHITECTURE.md +├── SCHEMA_AUDIT_CURRENT.md +└── audits/ + ├── SCHEMA_AUDIT_V1.md + ├── SCHEMA_AUDIT_V9.md + └── SCHEMA_AUDIT_V10.md +``` + +Règle : + +- `SCHEMA_AUDIT_CURRENT.md` est mis à jour à chaque migration ; +- l’audit versionné reste immuable après validation ; +- le ticket de migration n’est pas terminé sans mise à jour documentaire. + +--- + +# 12. Hygiène du dépôt hors documentation + +Deux éléments présents à la racine doivent être contrôlés : + +```text +meline59760.txt +watch_20260723-211101 +``` + +Ils ne ressemblent pas à des fichiers source ou de documentation standards. + +Avant de les conserver publiquement : + +1. vérifier qu’ils utilisent exclusivement des données synthétiques ; +2. vérifier qu’ils ne contiennent aucune donnée d’enquête réelle ; +3. les déplacer vers une fixture clairement nommée s’ils sont utiles aux tests ; +4. les supprimer du dépôt sinon ; +5. ajouter les motifs nécessaires dans `.gitignore`. + +Ne jamais versionner : + +- `Enquete.sqlite` réelle ; +- captures ; +- e-mails réels ; +- RIB réels ; +- pièces jointes réelles ; +- exports bruts issus d’une enquête ; +- données personnelles non synthétiques. + +--- + +# Ordre de mise à jour recommandé + +## Commit 1 — Références SQLite + +- ajouter `SCHEMA_AUDIT_CURRENT.md` ; +- ajouter l’audit V10 ; +- archiver l’audit V1 ; +- mettre à jour `DATABASE_ARCHITECTURE.md`. + +## Commit 2 — Roadmap et suivi + +- remplacer `ROADMAP.md` ; +- supprimer ou rediriger `BACKLOG.md` ; +- corriger la section suivi du README. + +## Commit 3 — Architecture et développement + +- mettre à jour `ARCHITECTURE.md` ; +- mettre à jour `DEVELOPMENT.md` ; +- mettre à jour `CONVENTIONS.md`. + +## Commit 4 — Dépendances et présentation + +- vérifier `DEPENDENCE.md` ; +- compléter `CHANGELOG.md` ; +- finaliser `README.md`. + +## Commit 5 — Hygiène du dépôt + +- auditer les fichiers isolés à la racine ; +- supprimer ou déplacer les éléments non conformes ; +- ajuster `.gitignore`. + +--- + +# Critères de validation documentaire + +La mise à jour est terminée lorsque : + +- aucun document courant ne présente V1 comme schéma actuel ; +- V10 est identifiée comme version courante ; +- les audits historiques sont explicitement marqués historiques ; +- la roadmap ne duplique plus les tickets fermés ; +- `#107` est présenté comme chantier actif ; +- `#42` est présenté comme inventaire permanent ; +- les commandes documentées existent réellement dans le Makefile ; +- `make docs` n’est plus documenté sans cible correspondante ; +- l’architecture distingue Database, DAO, services et GTK ; +- le nommage documenté correspond au code actuel ; +- les dépendances optionnelles sont clairement identifiées ; +- les données d’enquête réelles sont explicitement interdites dans le dépôt ; +- tous les liens Markdown sont valides ; +- `git diff --check` passe. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 71fc697..2be0780 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,1569 +1,319 @@ # Roadmap -# Vision - -Labfy Investigation est un logiciel libre d'investigation numérique, -développé en C17 avec GTK4. - -Le projet a pour objectif de fournir un environnement professionnel -permettant de gérer une enquête numérique de bout en bout, depuis la -collecte des preuves jusqu'à la génération d'un rapport. - -Le logiciel est conçu pour être utilisé aussi bien par des particuliers -que par des professionnels (journalistes, enquêteurs, forces de l'ordre, -experts judiciaires, analystes OSINT). +> **Dernière mise à jour :** 2026-07-24 +> **État du projet :** développement actif +> **Schéma SQLite courant :** V10 +> **Usage opérationnel :** non prêt pour la production --- -# Principes d'architecture +## 1. Source de vérité -Le développement repose sur plusieurs règles fondamentales. - -## Une enquête = un dossier autonome - -Chaque enquête contient l'ensemble des éléments nécessaires à son -fonctionnement. +La feuille de route détaillée est suivie dans Forgejo : ```text -MonEnquete/ -│ -├── 00_BaseDeDonnees/ -│ └── Enquete.sqlite -│ -├── 01_Preuves_Originales/ -├── 02_Preuves_Traitees/ -├── 03_Chronologie/ -├── 04_Entites/ -├── 05_Rapports/ -│ -└── ... +https://git.labfytools.com/fy59/labfy-investigation/issues ``` -Une enquête peut être : +Ce document donne une vue stratégique courte. Il ne duplique pas la liste +complète des tickets fermés. -- copiée ; -- sauvegardée ; -- synchronisée ; -- archivée ; -- transmise. +Pour connaître l'état d'une fonctionnalité : -Sans dépendre d'une installation particulière. +1. consulter le code et les tests sur `main` ; +2. consulter les migrations SQL ; +3. consulter les tickets Forgejo ; +4. utiliser cette roadmap comme synthèse. + +Un ticket ouvert décrit un chantier en cours. Il ne prouve pas que toutes ses +fonctions sont déjà disponibles. --- -## Séparation des responsabilités +## 2. Vision -Le Core ne dépend jamais de GTK. +Labfy Investigation doit devenir un poste de travail local d'investigation +numérique et d'OSINT capable de : -La couche graphique ne contient aucune logique métier. - -```text -GUI - │ - ▼ -Application - │ - ▼ -InvestigationProject - │ - ┌──────┴────────────┐ - │ │ - ▼ ▼ -FileSystem Database - │ - ▼ -Investigation -``` - ---- - -## Préservation des preuves - -Les preuves originales ne sont jamais modifiées. - -Toute opération produisant une version annotée, -convertie ou analysée est enregistrée dans un -espace distinct. - ---- - -## Développement incrémental - -Chaque ticket doit : - -- être autonome ; -- être testé ; -- compiler sans warning ; -- ne pas introduire de régression. - -Aucun ticket ne doit casser les fonctionnalités existantes. - ---- - -# Phases du projet - -## Phase 1 — Infrastructure ✅ - -### Architecture - -- [x] Structure du projet -- [x] Architecture C17 -- [x] Organisation des modules -- [x] Documentation Doxygen -- [x] Makefile -- [x] Tests unitaires - -### Core - -- [x] Investigation -- [x] InvestigationNode -- [x] InvestigationTreeBuilder -- [x] InvestigationTreeModel - -### Interface GTK4 - -- [x] MainWindow -- [x] Sidebar -- [x] Workspace -- [x] GtkStack -- [x] InvestigationTreeView -- [x] Sélection des nœuds -- [x] Affichage des informations -- [x] Affichage du chemin complet -- [x] Icônes selon le type de fichier - ---- - -# Phase 2 — Gestion des enquêtes - -## TICKET-020 - -- [ ] Création d'une nouvelle enquête - -### Objectifs - -- création de l'arborescence -- création de `00_BaseDeDonnees` -- création de `Enquete.sqlite` - ---- - -## TICKET-021 - -- [ ] Validation d'une enquête existante - -### Objectifs - -- vérifier l'arborescence -- vérifier la présence de la base -- détecter une enquête invalide -- import d'une enquête - ---- - -## TICKET-022 - -- [ ] Initialisation de SQLite - -### Objectifs - -- création du schéma -- table metadata -- version du schéma -- UUID de l'enquête - ---- - -## TICKET-023 - -- [ ] InvestigationProject - -### Objectifs - -- ouverture d'une enquête -- fermeture -- validation -- création - ---- - -# Phase 3 — Consultation - -- [ ] Aperçu des fichiers texte -- [ ] Aperçu des images -- [ ] Aperçu PDF -- [ ] Aperçu vidéo -- [ ] Aperçu audio - ---- - -# Phase 4 — Base de données - -- [ ] Gestion des preuves -- [ ] Gestion des entités -- [ ] Gestion des relations -- [ ] Chronologie -- [ ] Tags -- [ ] Notes - ---- - -# Phase 5 — Analyse - -- [ ] Calcul des hash -- [ ] EXIF -- [ ] OCR -- [ ] Recherche plein texte -- [ ] Analyse des métadonnées -- [ ] Import massif - ---- - -# Phase 6 — OSINT - -- [ ] Whois -- [ ] DNS -- [ ] Sous-domaines -- [ ] HTTP -- [ ] Certificats TLS -- [ ] Réseaux sociaux -- [ ] Emails -- [ ] Téléphones - ---- - -# Phase 7 — Rapports - -- [ ] Rapport HTML -- [ ] Rapport PDF -- [ ] Export ZIP -- [ ] Export dossier complet - ---- - -# Phase 8 — Qualité - -- [ ] Traductions -- [ ] Thèmes -- [ ] Tests d'intégration -- [ ] Packaging -- [ ] Installateur Linux -- [ ] Documentation utilisateur - -# Objectifs à long terme - -Le projet doit permettre : - -- la gestion complète d'une enquête numérique ; -- la conservation de la chaîne de preuve ; -- l'intégration de modules OSINT ; -- l'analyse de fichiers et de métadonnées ; -- la génération de rapports exploitables ; -- une architecture modulaire facilitant les évolutions futures. +- préserver les preuves originales ; +- organiser les données d'une enquête autonome ; +- extraire et normaliser des informations ; +- créer des entités et des relations traçables ; +- représenter les données sous forme de graphe ; +- conserver la provenance des traitements ; +- exécuter des outils externes de manière contrôlée ; +- présenter les résultats à l'enquêteur avant intégration ; +- produire des rapports compréhensibles et transmissibles. Le logiciel doit rester : - libre ; +- local ; - documenté ; -- portable ; - testable ; -- maintenable. +- maintenable ; +- utilisable avec des dépendances optionnelles ; +- compatible à terme avec une distribution Ubuntu institutionnelle. -# Feuille de route repensée — Labfy Investigation +--- -## Point de départ +## 3. Principes non négociables -Le ticket **#031.1 — Fermeture propre de l’application** termine le premier socle GTK. - -À ce stade, Labfy Investigation sait : - -- créer une enquête ; -- ouvrir une enquête existante ; -- remplacer une session active ; -- afficher son arborescence ; -- fermer proprement l’application ; -- ouvrir et initialiser la base SQLite ; -- charger l’identité persistante de l’enquête ; -- gérer les transactions et les erreurs de base. - -La suite ne doit plus être pensée comme un simple gestionnaire de fichiers. - -## Vision du logiciel - -Labfy Investigation doit devenir un **poste de travail OSINT orienté enquête** capable de : - -- conserver les preuves originales ; -- extraire et rechercher des métadonnées ; -- créer des entités ; -- relier les données entre elles ; -- afficher les relations sous forme de graphe ; -- construire une chronologie ; -- effectuer des recherches locales ; -- lancer des outils OSINT externes ; -- interroger des services Internet ; -- conserver les résultats bruts ; -- normaliser les résultats ; -- documenter la provenance de chaque information ; -- produire un rapport exploitable. - -Architecture générale : +### Une enquête est autonome ```text -Interface GTK +MonEnquete/ +├── 00_BaseDeDonnees/ +│ └── Enquete.sqlite +├── 01_Preuves_Originales/ +├── 02_Preuves_Traitees/ +├── 03_Chronologie/ +├── 04_Entites/ +└── 05_Rapports/ +``` + +### SQLite est la source de vérité + +Le graphe, la barre latérale, les tableaux et les futures vues chronologiques +sont des projections des mêmes données persistées. + +### Les preuves originales sont immuables + +Toute transformation produit un fichier ou un objet dérivé. + +### Toute donnée importante possède une provenance + +Le système doit pouvoir expliquer : + +- ce qui a été trouvé ; +- quand ; +- à partir de quelle preuve ou cible ; +- avec quel outil et quelle version ; +- avec quels paramètres ; +- quelle sortie brute a été produite ; +- quelle interprétation a été confirmée ou rejetée. + +### L'enquêteur garde le contrôle + +Une sortie OCR, une donnée OSINT ou une corrélation automatique reste une +proposition tant qu'elle n'a pas été explicitement confirmée. + +### L'interface ne doit pas être bloquée + +Les traitements longs sont exécutés en arrière-plan et restent annulables +lorsque cela est techniquement possible. + +### Les outils externes restent optionnels + +L'absence d'un outil réduit les capacités disponibles, mais ne doit pas +empêcher le lancement de l'application. + +--- + +## 4. Socle déjà implémenté + +La branche `main` contient notamment : + +- création, validation et ouverture d'enquêtes ; +- session d'enquête remplaçable proprement ; +- infrastructure SQLite et migrations jusqu'à V10 ; +- couche Database, DAO et services métier ; +- import de preuves avec copie contrôlée et SHA-256 ; +- vérification d'intégrité et reclassement des preuves ; +- modèles et DAO d'entités et de relations ; +- associations preuves–entités et preuves–relations ; +- chargement asynchrone du graphe ; +- déplacement des nœuds et persistance du viewport ; +- registre, catalogue et exécution sécurisée d'outils externes ; +- gestionnaire de tâches et panneau d'activité ; +- premiers pivots DNS avec propositions puis intégration ; +- conservation de la provenance des exécutions OSINT ; +- comptes sociaux structurés ; +- personnes, rôles d'enquête et identité usurpée ; +- extractions liées aux preuves et aux entités ; +- analyse EML, IBAN, métadonnées ExifTool et PDF ; +- types canoniques de relations ; +- vocabulaire contrôlé ; +- table V10 `bank_account_entities` ; +- premiers composants du pipeline EML. + +Cette liste est une synthèse et non un contrat de stabilité. + +--- + +## 5. Chantier actif + +### Ticket #107 — Pivot e-mail forensique + +Statut : + +```text +PARTIEL +``` + +Les briques préparatoires existent, mais le flux complet reste à terminer. + +Objectif principal : + +```text +preuve EML ↓ -Contrôleurs de l’application +vérification d'intégrité ↓ -Services métier - ├── preuves - ├── entités - ├── relations - ├── recherches - ├── tâches - └── rapports +analyse des en-têtes et de la structure MIME ↓ -Adaptateurs - ├── SQLite - ├── système de fichiers - ├── outils CLI - ├── bibliothèques - └── API Internet +extraction sécurisée des pièces jointes + ↓ +SHA-256, type MIME et métadonnées + ↓ +OCR et détection d'indicateurs + ↓ +normalisation sans perte de la valeur brute + ↓ +interface de révision + ↓ +confirmation explicite + ↓ +intégration transactionnelle + ↓ +rafraîchissement des vues et du graphe ``` +Priorités immédiates : + +1. terminer l'extraction MIME robuste ; +2. conserver les pièces jointes comme fichiers dérivés ; +3. réunir EML, OCR, IBAN et ExifTool dans un pipeline unique ; +4. terminer l'interface de révision ; +5. persister uniquement les propositions confirmées ; +6. réutiliser ou créer les entités correspondantes ; +7. créer les relations canoniques avec leur provenance ; +8. garantir un rollback complet en cas d'échec ; +9. rafraîchir la barre latérale et le graphe ; +10. compléter les tests de migration et d'intégration ; +11. mettre à jour la documentation avec l'état réellement livré. + +Le ticket reste ouvert tant que son flux complet et ses critères d'acceptation +ne sont pas validés. + --- -# Principes non négociables +## 6. Inventaire permanent -## SQLite reste la source de vérité +### Ticket #42 — Arsenal OSINT -Le graphe, les tableaux, la chronologie et les résultats de recherche sont des vues différentes des mêmes données. - -## Résultat brut et résultat normalisé sont séparés - -Chaque outil doit produire : +Statut : ```text -Sortie brute conservée et horodatée - + -Données normalisées utilisables dans Labfy +INVENTAIRE PERMANENT ``` -## Toute information doit avoir une provenance +Ce ticket sert à qualifier les outils et services potentiellement intégrables. -Une donnée exploitable doit pouvoir répondre à ces questions : +Un outil n'est pas ajouté en masse. Son intégration suit un besoin concret : -```text -Qu’a-t-on trouvé ? -Quand ? -Avec quel outil ? -Avec quelle version ? -À partir de quelle requête ? -Quelle était la réponse brute ? -Quelle preuve ou source justifie l’interprétation ? -``` +1. compréhension manuelle de la technique ; +2. vérification du cadre légal ; +3. vérification de la licence ; +4. vérification Arch Linux et Ubuntu ; +5. création d'un ticket dédié ; +6. développement d'un adaptateur ; +7. conservation des sorties brutes ; +8. normalisation des résultats ; +9. tests avec données synthétiques ; +10. documentation de ses limites. -## Les outils externes sont optionnels - -Une dépendance absente ne doit pas empêcher Labfy de démarrer. - -Chaque capacité peut être : - -```text -Disponible -Absente -Trop ancienne -Non configurée -Désactivée -En erreur -``` - -## L’interface ne doit jamais être bloquée - -Les opérations longues doivent fonctionner en arrière-plan : - -- calcul d’empreinte ; -- copie de fichiers ; -- extraction de métadonnées ; -- requêtes réseau ; -- analyse de résultats ; -- génération de rapports. - -## Aucune commande shell construite avec une chaîne - -Les outils externes doivent être lancés avec `GSubprocess` et une liste d’arguments. - -## Les données déduites restent distinctes des données observées - -Labfy doit distinguer : - -```text -Observation directe -Résultat produit par un outil -Donnée importée -Déduction de l’enquêteur -Hypothèse -``` +Le ticket #42 reste ouvert tant que l'inventaire est utile au projet. --- -# Phase 1 — Consolider le noyau d’application +## 7. Axes suivants -## Ticket #032 — Factoriser le chargement d’une enquête +L'ordre exact dépendra des tickets créés dans Forgejo. -Créer un service interne unique qui : +### 7.1 Fiabilité des données -1. ouvre une `InvestigationSession` ; -2. récupère le projet ; -3. construit l’arborescence ; -4. installe la session dans `Application` ; -5. conserve l’ancienne session en cas d’échec. +- fixture dédiée V9 vers V10 ; +- tests de rollback pour les migrations récentes ; +- `PRAGMA integrity_check` et `PRAGMA foreign_key_check` systématiques ; +- contrôle des références orphelines ; +- vérification des sorties brutes persistées ; +- journal d'audit plus complet. -Ce flux sera réutilisé par : +### 7.2 Graphe d'enquête -- création d’une enquête ; -- ouverture manuelle ; -- enquêtes récentes ; -- arguments de ligne de commande ; -- restauration de session. +- améliorer la lisibilité des grands graphes ; +- filtrer par type, date, source, statut et confiance ; +- enregistrer des vues ; +- créer et éditer des relations depuis le canvas ; +- synchroniser toutes les modifications avec SQLite ; +- préparer l'export du graphe. -## Ticket #033 — Afficher les erreurs dans GTK +### 7.3 Recherche et chronologie -Créer un module commun d’affichage : +- recherche transversale ; +- filtres structurés ; +- chronologie liée aux preuves, entités et relations ; +- notes, pistes et hypothèses clairement séparées des faits. -- erreur ; -- avertissement ; -- confirmation ; -- information. +### 7.4 Rapports et transmission -Les erreurs techniques restent journalisées avec GLib, mais l’utilisateur doit recevoir un message graphique compréhensible. +- rapport Markdown structuré ; +- export PDF ; +- annexes et empreintes ; +- manifeste d'enquête ; +- export autonome ; +- expurgation et anonymisation ; +- présentation adaptée aux forces de l'ordre. -## Ticket #034 — Gestionnaire de tâches asynchrones +### 7.5 Distribution Ubuntu -Créer un modèle de tâche capable de gérer : - -- état ; -- progression ; -- annulation ; -- résultat ; -- erreur ; -- date de début ; -- date de fin. - -États recommandés : - -```text -En attente -En cours -Terminée -Échouée -Annulée -``` - -L’interface GTK doit rester fluide pendant l’exécution. - -## Ticket #035 — File de tâches et panneau d’activité - -Ajouter une file de tâches et une vue GTK permettant de suivre : - -- imports ; -- calculs d’empreintes ; -- recherches OSINT ; -- extractions de métadonnées ; -- exports. - -## Ticket #036 — Configuration de l’application - -Créer une configuration persistante pour : - -- chemins d’outils ; -- délais d’exécution ; -- activation des modules ; -- préférences d’interface ; -- paramètres réseau ; -- comportement des imports. - -Les secrets et clés API ne doivent pas être stockés en clair dans la base de l’enquête. +- classifier les dépendances obligatoires et optionnelles ; +- produire un script de compilation robuste ; +- produire un paquet `.deb` ; +- fonctionner avec des dépôts institutionnels restreints ; +- documenter l'installation hors ligne ; +- tester Wayland et X11 ; +- éviter toute dépendance AUR obligatoire. --- -# Phase 2 — Système d’outils externes +## 8. Critères de qualité communs -## Ticket #037 — Registre des capacités et dépendances +Un chantier n'est pas terminé tant que : -Créer un registre central capable de détecter : +- le code compile ; +- les tests ciblés passent ; +- la suite complète passe ; +- les erreurs sont présentées correctement ; +- l'interface reste réactive ; +- les données brutes sont préservées ; +- la provenance est suffisante ; +- aucune donnée réelle d'enquête n'est présente dans le dépôt ; +- la documentation reflète l'état livré. -- présence d’un exécutable ; -- chemin réel ; -- version ; -- compatibilité minimale ; -- statut ; -- message d’erreur. +Validation recommandée : -Premiers outils candidats : - -```text -dig -host -whois -curl -openssl -file -exiftool -ffprobe -strings +```sh +make clean +make -j8 +make -j8 test +git diff --check ``` -## Ticket #038 — Interface commune des adaptateurs OSINT - -Définir les concepts opaques : - -```c -OsintTool -OsintRequest -OsintExecution -OsintResult -``` - -Un adaptateur devra pouvoir : - -- valider une requête ; -- vérifier sa disponibilité ; -- exécuter l’outil ; -- appliquer un délai maximal ; -- capturer `stdout` ; -- capturer `stderr` ; -- récupérer le code de retour ; -- analyser la sortie ; -- retourner un résultat normalisé. - -## Ticket #039 — Exécuteur sécurisé `GSubprocess` - -Créer un module générique qui lance un programme sans passer par un shell. - -Il doit gérer : - -- tableau d’arguments ; -- environnement contrôlé ; -- délai maximal ; -- annulation ; -- taille maximale des sorties ; -- code de retour ; -- erreurs de lancement. - -## Ticket #040 — Conservation des exécutions brutes - -Ajouter les tables et fichiers nécessaires pour conserver : - -- outil ; -- version ; -- cible ; -- paramètres ; -- date ; -- durée ; -- sortie standard ; -- sortie d’erreur ; -- code de retour ; -- SHA-256 de la sortie brute ; -- statut d’analyse. - -Exemple de stockage : - -```text -02_Preuves_Traitees/ -└── Resultats_Outils/ - └── __.json -``` - -## Ticket #041 — Vue des dépendances et capacités - -Créer une page GTK affichant : - -```text -ExifTool Disponible -dig Disponible -ffprobe Absent -Recherche sociale Non configurée -``` - -Une capacité absente doit expliquer comment l’activer sans bloquer l’application. +Le retour à une compilation séquentielle n'est utilisé que si la +parallélisation provoque un échec réel. --- -# Phase 3 — Preuves et fichiers +## 9. Historique -## Ticket #042 — Modèle opaque `EvidenceRecord` +L'historique détaillé du développement se trouve dans : -Champs initiaux : - -- identifiant ; -- nom original ; -- nom interne ; -- chemin relatif ; -- type ; -- taille ; -- SHA-256 ; -- date d’importation ; -- date de collecte déclarée ; -- source ; -- description ; -- statut d’intégrité. - -## Ticket #043 — Schéma SQLite et DAO des preuves - -Créer : - -- table `evidence` ; -- table `evidence_types` ; -- index ; -- contraintes ; -- DAO d’insertion ; -- DAO de lecture ; -- DAO de mise à jour autorisée. - -## Ticket #044 — Calcul SHA-256 par blocs - -Créer un module indépendant capable de traiter les gros fichiers sans les charger entièrement en mémoire. - -Ce ticket peut être synchronisé avec le cours de C. - -## Ticket #045 — Copie sûre et contrôlée d’un fichier - -Créer un service de copie qui : - -- valide le fichier source ; -- refuse les chemins dangereux ; -- évite les collisions ; -- copie vers une destination temporaire ; -- synchronise la copie ; -- recalcule son empreinte ; -- renomme atomiquement le fichier final. - -Ce ticket peut être synchronisé avec le cours Unix. - -## Ticket #046 — Import transactionnel d’une preuve - -Pipeline : - -```text -Validation -→ SHA-256 source -→ Copie temporaire -→ SHA-256 destination -→ Écriture SQLite -→ Validation de transaction -→ Renommage final -``` - -En cas d’échec, aucune preuve partiellement importée ne doit rester active. - -## Ticket #047 — Dialogue GTK d’import - -Ajouter : - -```text -Importer une preuve -``` - -Le formulaire doit permettre : - -- choix du fichier ; -- type ; -- source ; -- date de collecte ; -- description ; -- confirmation. - -## Ticket #048 — Liste et fiche détaillée des preuves - -Afficher sous forme de tableau : - -- nom ; -- type ; -- taille ; -- date ; -- source ; -- empreinte ; -- état d’intégrité. - -Une fiche détaillée doit afficher toutes les informations disponibles. - -## Ticket #049 — Vérification d’intégrité - -Recalculer les empreintes et détecter : - -- fichier absent ; -- taille modifiée ; -- empreinte modifiée ; -- chemin invalide ; -- doublon. - ---- - -# Phase 4 — Métadonnées et analyse locale - -## Ticket #050 — Premier adaptateur externe : ExifTool - -Ce sera le premier adaptateur complet validant toute l’architecture : - -```text -EvidenceRecord -→ tâche asynchrone -→ ExifTool -→ JSON brut -→ résultat stocké -→ métadonnées normalisées -``` - -## Ticket #051 — Modèle de métadonnées normalisées - -Créer un modèle générique : - -- clé ; -- valeur textuelle ; -- type de valeur ; -- namespace ; -- source ; -- outil ; -- confiance ; -- date d’extraction. - -## Ticket #052 — Extracteurs spécialisés - -Ajouter progressivement : - -- `file` pour le type réel ; -- `ffprobe` pour audio et vidéo ; -- extraction PDF ; -- extraction de documents bureautiques ; -- analyse EML ; -- analyse d’archives. - -## Ticket #053 — Recherche d’indicateurs dans les fichiers - -Détecter dans les métadonnées et contenus extraits : - -- emails ; -- domaines ; -- URL ; -- adresses IP ; -- téléphones ; -- pseudonymes ; -- noms d’utilisateurs ; -- coordonnées GPS. - -Les résultats doivent être proposés à l’enquêteur avant création d’entités. - -## Ticket #054 — Vue des métadonnées - -Afficher : - -- métadonnées brutes ; -- métadonnées normalisées ; -- filtres ; -- recherche ; -- provenance ; -- création d’entité depuis une valeur. - ---- - -# Phase 5 — Entités, observations et relations - -## Ticket #055 — Modèle opaque `EntityRecord` - -Types initiaux : - -```text -Personne -Pseudonyme -Adresse email -Téléphone -Domaine -Adresse IP -URL -Compte social -Organisation -IBAN -Cryptomonnaie -Document -Lieu -``` - -## Ticket #056 — Schéma et DAO des entités - -Créer : - -- `entity_types` ; -- `entities` ; -- `entity_attributes` ; -- contraintes ; -- index ; -- DAO. - -## Ticket #057 — Modèle `ObservationRecord` - -Une observation décrit une information découverte avec : - -- valeur ; -- date ; -- source ; -- méthode ; -- outil ; -- confiance ; -- statut de validation ; -- notes. - -## Ticket #058 — Interface de création et consultation des entités - -Permettre : - -- création manuelle ; -- modification ; -- recherche ; -- fusion contrôlée ; -- ajout d’attributs ; -- consultation des preuves associées. - -## Ticket #059 — Modèle opaque `RelationRecord` - -Une relation doit contenir : - -- source ; -- cible ; -- type ; -- direction ; -- date ; -- confiance ; -- provenance ; -- preuve associée ; -- note ; -- statut de validation. - -## Ticket #060 — Schéma et DAO des relations - -Créer : - -- `relation_types` ; -- `relations` ; -- contraintes ; -- index ; -- DAO. - -## Ticket #061 — Création et validation des relations - -Permettre : - -- création manuelle ; -- proposition automatique ; -- acceptation ; -- rejet ; -- modification ; -- justification. - -Aucune relation déduite automatiquement ne doit devenir définitive sans provenance. - ---- - -# Phase 6 — Recherche locale et requêtes - -## Ticket #062 — Index de recherche SQLite FTS5 - -Indexer : - -- preuves ; -- descriptions ; -- notes ; -- entités ; -- attributs ; -- observations ; -- métadonnées ; -- résultats OSINT ; -- événements. - -## Ticket #063 — Langage de filtres interne - -Créer un service de requêtes combinant : - -- texte ; -- type ; -- date ; -- source ; -- confiance ; -- outil ; -- statut ; -- relations. - -Exemples : - -```text -type:email source:exiftool -domain:example.org -confidence:<50 -evidence:"capture écran" -``` - -## Ticket #064 — Interface de recherche globale - -Ajouter : - -- barre de recherche ; -- filtres ; -- tri ; -- regroupement ; -- résultats paginés ; -- ouverture de la fiche correspondante. - -## Ticket #065 — Requêtes enregistrées - -Permettre d’enregistrer et de rejouer une recherche. - -## Ticket #066 — Recherche transversale et pivots - -Depuis une valeur, proposer : - -```text -Rechercher partout -Afficher les preuves liées -Afficher les entités liées -Afficher les relations -Lancer un enrichissement OSINT -``` - ---- - -# Phase 7 — Enrichissement OSINT réseau - -## Ticket #067 — Adaptateur DNS - -Fonctions initiales : - -- A ; -- AAAA ; -- MX ; -- NS ; -- TXT ; -- CNAME ; -- SOA ; -- résolution inverse. - -Stocker : - -- requête ; -- serveur utilisé ; -- date ; -- réponse brute ; -- réponses normalisées ; -- erreurs. - -## Ticket #068 — Adaptateur RDAP et WHOIS - -Extraire : - -- registraire ; -- dates ; -- serveurs de noms ; -- statuts ; -- contacts publics ; -- réseau IP ; -- ASN lorsque disponible. - -## Ticket #069 — Adaptateur TLS - -Analyser : - -- certificat ; -- sujet ; -- émetteur ; -- SAN ; -- dates ; -- chaîne ; -- empreintes ; -- protocoles observés. - -## Ticket #070 — Adaptateur HTTP - -Collecter : - -- statut ; -- redirections ; -- en-têtes ; -- titre ; -- type de contenu ; -- serveur déclaré ; -- empreinte de réponse ; -- liens principaux. - -## Ticket #071 — Recherche de sous-domaines - -Agrégation contrôlée de plusieurs sources : - -- DNS ; -- certificats ; -- données passives disponibles ; -- outils externes facultatifs. - -Les sources doivent rester identifiables séparément. - -## Ticket #072 — Archives du Web - -Ajouter un fournisseur permettant de rechercher : - -- captures anciennes ; -- dates disponibles ; -- URL historiques ; -- changements visibles. - -## Ticket #073 — Moteurs de recherche et recherche Web - -Créer une interface fournisseur pouvant utiliser : - -- API officielle ; -- service configuré ; -- ouverture assistée dans le navigateur ; -- import manuel de résultats. - -Labfy ne doit pas contourner les protections des moteurs. - -## Ticket #074 — Réseaux sociaux - -Créer un cadre générique pour : - -- comptes publics ; -- pseudonymes ; -- URL de profils ; -- publications publiques ; -- observations manuelles ; -- fournisseurs autorisés. - -Chaque plateforme pourra avoir : - -- un adaptateur API ; -- un adaptateur CLI ; -- un import manuel ; -- aucune automatisation si les règles l’interdisent. - -## Ticket #075 — Cache, quotas et limitation de débit - -Ajouter : - -- cache ; -- date d’expiration ; -- quotas ; -- pauses ; -- reprises ; -- erreurs temporaires ; -- délais entre requêtes. - -## Ticket #076 — Pivots OSINT - -Depuis une entité, proposer les recherches compatibles : - -```text -Domaine → DNS, RDAP, TLS, HTTP, archives -IP → reverse DNS, RDAP, ASN -Email → domaines, occurrences locales, fournisseurs configurés -Pseudonyme → moteurs, réseaux sociaux, dépôts publics -URL → HTTP, TLS, archives, métadonnées -``` - -## Ticket #077 — Révision des résultats avant intégration - -Une recherche OSINT doit produire une liste de propositions : - -- créer une entité ; -- compléter une entité ; -- créer une observation ; -- créer une relation ; -- ignorer. - -L’enquêteur garde le contrôle. - ---- - -# Phase 8 — Affichage analytique et graphe - -## Ticket #078 — Service de projection graphique - -Transformer les données SQLite en représentation graphique sans faire du graphe la source de vérité. - -Types de nœuds : - -- preuves ; -- entités ; -- événements ; -- résultats OSINT. - -Types d’arêtes : - -- relations validées ; -- relations proposées ; -- liens de provenance. - -## Ticket #079 — Première vue graphique - -Afficher un graphe simple avec : - -- nœuds ; -- liens ; -- libellés ; -- sélection ; -- zoom ; -- déplacement. - -Le premier moteur pourra s’appuyer sur Graphviz ou une bibliothèque compatible GTK. - -## Ticket #080 — Fiche contextuelle du graphe - -Cliquer sur un nœud ou une relation doit afficher : - -- identité ; -- attributs ; -- source ; -- confiance ; -- preuve justificative ; -- actions possibles. - -## Ticket #081 — Filtres du graphe - -Filtrer par : - -- type ; -- date ; -- source ; -- confiance ; -- statut ; -- profondeur ; -- enquêteur ; -- outil. - -## Ticket #082 — Organisation et regroupement - -Permettre : - -- regroupement manuel ; -- regroupement par type ; -- regroupement par domaine ; -- regroupement par période ; -- masquage de branches ; -- expansion d’un voisinage. - -## Ticket #083 — Vues graphiques enregistrées - -Enregistrer : - -- position des nœuds ; -- filtres ; -- regroupements ; -- annotations ; -- titre de la vue. - -## Ticket #084 — Tableaux et statistiques - -Créer des vues tabulaires et graphiques pour : - -- types de preuves ; -- entités ; -- domaines ; -- outils utilisés ; -- volume de résultats ; -- dates ; -- intégrité ; -- relations. - ---- - -# Phase 9 — Chronologie et notes - -## Ticket #085 — Modèle d’événement - -Champs : - -- date et heure ; -- précision ; -- fuseau ; -- description ; -- source ; -- entités ; -- preuves ; -- confiance. - -## Ticket #086 — Vue chronologique - -Afficher : - -- événements ; -- filtres ; -- regroupement ; -- preuves associées ; -- périodes sans date exacte. - -## Ticket #087 — Notes d’enquête - -Permettre : - -- notes globales ; -- notes liées à une preuve ; -- notes liées à une entité ; -- notes liées à une relation ; -- notes liées à un événement. - -## Ticket #088 — Hypothèses et pistes - -Créer un espace distinct pour : - -- hypothèses ; -- questions ouvertes ; -- pistes à vérifier ; -- statut ; -- priorité ; -- éléments favorables ; -- éléments contradictoires. - ---- - -# Phase 10 — Traçabilité et reproductibilité - -## Ticket #089 — Journal d’audit - -Tracer les opérations importantes : - -- création ; -- import ; -- modification ; -- suppression autorisée ; -- recherche OSINT ; -- création de relation ; -- validation ; -- export. - -## Ticket #090 — Rejouer une recherche - -Permettre de relancer une recherche avec : - -- même outil ; -- même version si disponible ; -- mêmes paramètres ; -- comparaison des résultats. - -## Ticket #091 — Manifeste de l’enquête - -Générer un manifeste contenant : - -- fichiers ; -- tailles ; -- empreintes ; -- versions d’outils ; -- base SQLite ; -- résultats bruts ; -- date de génération. - -## Ticket #092 — Contrôle de cohérence - -Détecter : - -- référence orpheline ; -- fichier absent ; -- résultat brut absent ; -- empreinte invalide ; -- relation sans provenance ; -- entité dupliquée. - ---- - -# Phase 11 — Rapports et exports - -## Ticket #093 — Rapport Markdown - -Générer : - -- identité de l’enquête ; -- résumé ; -- méthodologie ; -- preuves ; -- entités ; -- relations ; -- chronologie ; -- résultats OSINT ; -- empreintes ; -- limites. - -## Ticket #094 — Export PDF - -Transformer le rapport en document PDF transmissible. - -## Ticket #095 — Export du graphe - -Exporter une vue : - -- image ; -- SVG ; -- PDF ; -- annexe de rapport. - -## Ticket #096 — Archive autonome - -Créer une archive contenant : - -- rapport ; -- base ; -- manifeste ; -- résultats bruts ; -- preuves sélectionnées ; -- graphe ; -- journal d’audit. - -## Ticket #097 — Rédaction et anonymisation - -Permettre de produire une copie avec : - -- données masquées ; -- preuves exclues ; -- identifiants remplacés ; -- rapport adapté à la diffusion. - ---- - -# Phase 12 — Installation et distribution Ubuntu - -## Ticket #098 — Classification des dépendances - -Classer : - -```text -Obligatoires -Optionnelles -Recommandées -Fournies par une API -Indisponibles dans certains dépôts -``` - -## Ticket #099 — Script de compilation et installation - -Créer un dossier autonome avec : - -- détection de la distribution ; -- vérification des dépendances ; -- tentative d’installation ; -- compilation ; -- installation locale ; -- rapport clair des capacités indisponibles. - -## Ticket #100 — Paquet Debian - -Créer un paquet `.deb` contenant : - -- binaire ; -- icône ; -- fichier `.desktop` ; -- licence ; -- schémas ; -- dépendances obligatoires ; -- recommandations optionnelles. - -## Ticket #101 — Fonctionnement avec dépôts restreints - -Prévoir : - -- dépendances minimales ; -- modules facultatifs ; -- désactivation propre ; -- paquetage séparé si nécessaire ; -- documentation d’installation hors ligne. - -## Ticket #102 — Tests Ubuntu - -Tester : - -- Ubuntu LTS ; -- Wayland ; -- X11 ; -- machine sans outils de développement ; -- environnement hors ligne ; -- dépôts restreints ; -- utilisateur sans droits administrateur. - ---- - -# Jalons du projet - -## Jalon A — Socle professionnel - -Tickets : - -```text -#032 à #041 -``` - -Résultat : - -- contrôleur propre ; -- erreurs GTK ; -- tâches asynchrones ; -- registre d’outils ; -- exécution externe sécurisée ; -- résultats bruts conservés. - -## Jalon B — Gestion fiable des preuves - -Tickets : - -```text -#042 à #054 -``` - -Résultat : - -- import sûr ; -- SHA-256 ; -- intégrité ; -- métadonnées ; -- extraction d’indicateurs. - -## Jalon C — Enquête structurée - -Tickets : - -```text -#055 à #066 -``` - -Résultat : - -- entités ; -- observations ; -- relations ; -- recherche locale ; -- filtres ; -- pivots. - -## Jalon D — Poste de travail OSINT - -Tickets : - -```text -#067 à #077 -``` - -Résultat : - -- DNS ; -- RDAP ; -- TLS ; -- HTTP ; -- archives ; -- moteurs ; -- réseaux sociaux ; -- enrichissements contrôlés. - -## Jalon E — Analyse visuelle - -Tickets : - -```text -#078 à #088 -``` - -Résultat : - -- graphe ; -- tableaux ; -- chronologie ; -- notes ; -- hypothèses. - -## Jalon F — Transmission - -Tickets : - -```text -#089 à #102 -``` - -Résultat : - -- audit ; -- reproductibilité ; -- rapports ; -- exports ; -- installateurs Ubuntu. - ---- - -# MVP recommandé - -Le premier MVP réellement utile est atteint après le ticket **#066**. - -L’utilisateur pourra alors : - -1. créer ou ouvrir une enquête ; -2. importer des preuves ; -3. vérifier leur intégrité ; -4. extraire leurs métadonnées ; -5. créer des entités ; -6. relier les objets ; -7. rechercher dans toute l’enquête ; -8. effectuer des pivots locaux. - -Le second MVP, orienté OSINT réseau, est atteint après le ticket **#077**. - ---- - -# Ordre immédiat - -Ne pas commencer directement par le graphe ou les réseaux sociaux. - -Ordre recommandé : - -```text -#032 — Factoriser le chargement d’une enquête -#033 — Afficher les erreurs dans GTK -#034 — Gestionnaire de tâches asynchrones -#035 — File de tâches et panneau d’activité -#037 — Registre des dépendances -#038 — Interface commune des adaptateurs -#039 — Exécuteur GSubprocess -#040 — Conservation des résultats bruts -#042 — EvidenceRecord -``` - -Le ticket #036 sur la configuration peut être placé juste avant la première API nécessitant une clé. - ---- - -# Synchronisation avec les autres projets - -## C - -Tickets particulièrement adaptés au cours de C : - -- #034 gestion des tâches ; -- #039 exécution de processus ; -- #044 SHA-256 ; -- #045 copie robuste ; -- #053 extraction d’indicateurs ; -- #062 indexation ; -- #078 projection graphique. - -## Unix - -Tickets adaptés au cours système Unix : - -- #039 processus et signaux ; -- #045 fichiers et renommage atomique ; -- #049 intégrité ; -- #075 quotas et temporisation ; -- #089 journalisation ; -- #099 installation ; -- #100 paquet Debian. - -## OSINT - -Chaque nouveau fournisseur devra être précédé d’un apprentissage manuel : - -```text -Comprendre la technique -→ réaliser un exercice -→ documenter les limites -→ seulement ensuite intégrer l’outil -``` - -Labfy doit assister l’enquêteur, pas remplacer sa compréhension. +- les tickets fermés Forgejo ; +- les commits ; +- `CHANGELOG.md` ; +- les audits de schéma versionnés. +Les anciennes listes de tickets ne doivent pas être recopiées dans ce fichier, +car elles deviennent rapidement obsolètes. diff --git a/docs/database/DATABASE_ARCHITECTURE.md b/docs/database/DATABASE_ARCHITECTURE.md index 3d24dec..b811fca 100644 --- a/docs/database/DATABASE_ARCHITECTURE.md +++ b/docs/database/DATABASE_ARCHITECTURE.md @@ -1,2418 +1,616 @@ # Architecture de la base de données -> **Statut :** Stable (V1) -> -> Ce document décrit l'architecture de référence de la base de données de Labfy Investigation. -> -> Toute évolution incompatible devra faire l'objet d'une nouvelle version du schéma et d'une migration documentée. - -## Version - -**Schéma :** V1 +> **Statut :** architecture courante +> **Version du schéma :** V10 +> **Dernière mise à jour :** 2026-07-24 +> **Source de vérité détaillée :** `SCHEMA_AUDIT_CURRENT.md` --- -# 1. Introduction +## 1. Objet -## 1.1 Objectif - -La base de données de Labfy Investigation constitue le cœur du modèle métier de -l'application. - -Chaque enquête possède sa propre base SQLite, indépendante des autres -enquêtes. - -Cette base centralise toutes les informations produites ou découvertes pendant -une investigation : - -- les sources consultées ; -- les recherches réalisées ; -- les preuves collectées ; -- les entités identifiées ; -- les relations établies ; -- les hypothèses formulées ; -- la chronologie de l'enquête ; -- le journal d'audit de l'application ; -- les catégories et les tags. - -L'objectif de cette architecture est de fournir un modèle de données robuste, -cohérent et facilement extensible, tout en restant suffisamment simple pour -être compris et maintenu sur le long terme. - -Cette documentation décrit les choix d'architecture retenus pour la première -version du schéma de la base de données. - -Elle constitue le document de référence pour le développement de la couche -Database de Labfy Investigation. - ---- - -## 1.2 Philosophie - -La conception de cette base de données repose sur plusieurs principes. - -Le premier est la séparation des responsabilités. - -Chaque table représente un concept métier unique et clairement identifié. - -Par exemple : - -- une preuve représente un élément collecté ; -- une entité représente un objet identifié ; -- une relation représente un lien entre deux entités ; -- une hypothèse représente un raisonnement de l'enquêteur. - -Aucune table ne doit mélanger plusieurs responsabilités. - -Le deuxième principe est la traçabilité. - -Toute information importante doit pouvoir être reliée à son origine. - -Il doit toujours être possible d'expliquer : - -- d'où provient une information ; -- quelle recherche l'a produite ; -- quelles preuves la soutiennent ; -- quelles relations en découlent ; -- quelles hypothèses en résultent. - -Le troisième principe est l'évolutivité. - -Le schéma doit pouvoir évoluer sans remettre en cause les données existantes. - -Les nouvelles fonctionnalités devront privilégier l'ajout de nouvelles tables -ou de nouvelles relations plutôt que la modification des structures déjà -publiées. - -Enfin, le schéma privilégie la lisibilité plutôt que la recherche d'une -optimisation prématurée. - -La compréhension du modèle par les développeurs constitue une priorité. - ---- - -## 1.3 Une base par enquête - -Chaque enquête est totalement autonome. - -Lors de la création d'une nouvelle enquête, Labfy Investigation génère une -base SQLite dédiée : +Chaque enquête Labfy Investigation possède une base SQLite autonome : ```text 00_BaseDeDonnees/ └── Enquete.sqlite ``` -Toutes les informations propres à cette enquête sont enregistrées dans cette -base. +La base contient les données structurées et les références nécessaires à +l'enquête. -Aucune information métier n'est partagée entre plusieurs enquêtes. +Les fichiers originaux et dérivés restent dans l'arborescence de l'enquête. Ils +ne sont pas stockés comme blobs dans SQLite. -Cette organisation présente plusieurs avantages : +Cette architecture vise à garantir : -- chaque enquête est portable ; -- les sauvegardes sont simplifiées ; -- l'export d'une enquête est immédiat ; -- les risques de corruption croisée sont limités ; -- plusieurs enquêtes peuvent être ouvertes indépendamment. +- portabilité ; +- intégrité ; +- traçabilité ; +- migrations contrôlées ; +- compréhension durable du modèle ; +- séparation des données métier et de l'état de présentation. -La base SQLite ne contient jamais les fichiers originaux. +Pour l'inventaire détaillé des tables, contraintes et constats d'audit, +consulter : -Les preuves (captures d'écran, photographies, vidéos, documents, archives, -etc.) restent stockées dans l'arborescence de l'enquête. - -La base conserve uniquement les métadonnées nécessaires à leur exploitation. - -Cette séparation permet de préserver l'intégrité des fichiers originaux tout en -offrant un accès rapide aux informations nécessaires aux traitements réalisés -par l'application. +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` --- -# 2. Principes généraux +## 2. Sources de vérité -Cette section décrit les conventions utilisées dans toute la couche Database. +L'état réel du schéma est déterminé par : -Ces règles doivent rester cohérentes dans l'ensemble du projet afin de garantir -la lisibilité du code, la stabilité du schéma et la pérennité des données. +1. les constantes de version dans le code ; +2. `database/schema_v1.sql` à `database/schema_v10.sql` ; +3. `database/schema_current.sql` ; +4. les fonctions d'installation et de migration ; +5. `tests/test_database.c` et les tests DAO ; +6. l'audit courant. + +Les anciens audits sont historiques. + +Un document V1 ne décrit pas le schéma V10. --- -## 2.1 UUID +## 3. Principes -Tous les objets métier utilisent un identifiant unique universel (UUID) comme -clé primaire. +### 3.1 Une base par enquête -Exemple : +Une base contient une seule enquête. + +Les données métier de plusieurs enquêtes ne sont pas mélangées. + +### 3.2 Fichiers hors de SQLite + +SQLite conserve notamment : + +- chemins relatifs ; +- noms ; +- tailles ; +- empreintes ; +- métadonnées ; +- provenance ; +- relations. + +Les fichiers restent sur disque. + +### 3.3 UUID + +Les objets métier utilisent généralement : ```sql id TEXT PRIMARY KEY ``` -Les UUID sont générés par l'application lors de la création des objets. +contenant un UUID généré par l'application. -Cette approche présente plusieurs avantages : +Les tables de référence peuvent utiliser une clé entière. -- unicité garantie entre plusieurs enquêtes ; -- simplicité des imports et exports ; -- possibilité de fusionner plusieurs bases de données ; -- indépendance vis-à-vis des identifiants internes SQLite. +Cette règle est vérifiée par le schéma réel et non appliquée aveuglément. -Les tables de référence utilisent en revanche des identifiants entiers -statiques. +### 3.4 UTC -Exemples : +Les dates persistées sont en UTC. -- `types_preuve` -- `types_entite` -- `types_source` -- `types_outil` - -Ces identifiants sont contrôlés par l'application et ne sont pas destinés à -être modifiés par les utilisateurs. - ---- - -## 2.2 Dates UTC - -Toutes les dates enregistrées dans la base utilisent le temps universel (UTC). - -Le format retenu est : +Format de référence lorsqu'une date complète est exigée : ```text YYYY-MM-DDTHH:MM:SSZ ``` -Exemple : +### 3.5 Clés étrangères -```text -2026-07-15T18:42:10Z -``` - -L'utilisation de l'UTC évite les problèmes liés : - -- aux fuseaux horaires ; -- aux changements d'heure ; -- aux déplacements géographiques ; -- aux échanges de bases entre plusieurs machines. - -La conversion vers l'heure locale est réalisée uniquement lors de -l'affichage dans l'interface utilisateur. - ---- - -## 2.3 Suppression logique - -Les objets métier ne sont généralement pas supprimés physiquement. - -Ils utilisent une suppression logique basée sur la colonne : - -```text -status -``` - -Les valeurs autorisées dépendent de la table concernée mais utilisent -principalement : - -```text -active -archived -deleted -``` - -Cette approche permet : - -- de préserver l'historique de l'enquête ; -- d'éviter les suppressions accidentelles ; -- de conserver la cohérence des relations entre objets ; -- de restaurer un objet si nécessaire. - -Une suppression physique ne doit intervenir que dans le cadre d'opérations -d'administration ou de maintenance spécifiques. - ---- - -## 2.4 Intégrité référentielle - -Les clés étrangères sont activées systématiquement lors de l'ouverture de la -base. +Chaque connexion active : ```sql PRAGMA foreign_keys = ON; ``` -Toutes les relations entre objets sont protégées par des contraintes -d'intégrité. +Les actions `CASCADE`, `RESTRICT` et `SET NULL` sont choisies selon la +sémantique de chaque relation. -Selon le contexte, les suppressions utilisent : +### 3.6 Requêtes préparées -- `CASCADE` ; -- `RESTRICT` ; -- `SET NULL`. +Toute valeur variable utilise un statement préparé et des paramètres liés. -Le choix dépend du rôle métier de la relation et non d'une règle unique. +La concaténation de données utilisateur dans le SQL est interdite. + +### 3.7 Transactions + +Une opération critique multi-étapes est atomique. + +Les migrations, imports, reclassements et intégrations de propositions doivent +prévoir un rollback complet. + +### 3.8 Valeur brute et valeur interprétée + +Le modèle distingue lorsque nécessaire : + +- valeur brute ; +- valeur normalisée ; +- valeur dérivée ; +- correction utilisateur ; +- statut de vérification ; +- confiance ; +- provenance. + +La valeur brute n'est jamais modifiée pour refléter une correction ultérieure. --- -## 2.5 Transactions - -Toutes les opérations critiques sont exécutées dans une transaction SQLite. - -La création d'une enquête constitue une transaction unique comprenant : - -- l'installation du schéma ; -- l'enregistrement des métadonnées ; -- la création de l'enquête. - -En cas d'échec d'une étape, l'ensemble de la transaction est annulé. - -Cette stratégie garantit qu'une enquête ne peut jamais être créée dans un -état partiellement initialisé. - ---- - -## 2.6 Requêtes préparées - -Toutes les requêtes contenant des données variables utilisent des requêtes -préparées SQLite. - -Exemple : - -```c -sqlite3_prepare_v2(...) -sqlite3_bind_text(...) -sqlite3_step(...) -``` - -La concaténation de chaînes SQL contenant des données utilisateur est -interdite. - -Cette règle permet : - -- d'éviter les injections SQL ; -- d'améliorer les performances ; -- de simplifier la gestion des erreurs. - -Les requêtes SQL statiques peuvent être exécutées avec `sqlite3_exec()`. - ---- - -## 2.7 Séparation des responsabilités - -Le schéma suit une séparation stricte des responsabilités. - -Chaque table représente un unique concept métier. - -Les relations entre concepts sont modélisées à l'aide de tables de liaison -explicites plutôt que par des structures ambiguës ou des colonnes -multifonctions. - -Cette approche facilite : - -- la maintenance ; -- les évolutions futures ; -- les tests unitaires ; -- la compréhension du modèle. - ---- - -## 2.8 Couche Database - -L'accès à la base de données est centralisé dans le module `database`. - -Aucun autre composant de l'application ne doit exécuter directement de -requêtes SQL. - -Toutes les opérations passent par des fonctions dédiées de la couche -Database. - -Cette règle garantit : - -- une architecture modulaire ; -- une gestion uniforme des erreurs ; -- une meilleure testabilité ; -- une évolution simplifiée du schéma de la base. - ---- - -# 3. Vue d'ensemble - -Ce chapitre présente l'organisation générale de la base de données. - -Le schéma de Labfy Investigation n'a pas été conçu comme un simple ensemble de -tables indépendantes. - -Chaque objet métier représente une étape du processus d'investigation. - -L'ensemble forme un modèle cohérent permettant de suivre le cycle complet -d'une enquête, depuis la collecte initiale jusqu'à la formulation -d'hypothèses. - ---- - -## 3.1 Organisation générale - -Le modèle est organisé autour de plusieurs domaines fonctionnels. - -Chaque domaine possède une responsabilité clairement définie. +## 4. Architecture d'accès ```text -Métadonnées -Référentiels -Collecte -Connaissance -Raisonnement -Traçabilité -Classification -``` - -Cette séparation facilite : - -- la compréhension du modèle ; -- la maintenance du code ; -- les évolutions futures ; -- les tests unitaires. - ---- - -## 3.2 Domaines fonctionnels - -### Métadonnées - -Les métadonnées décrivent la base de données elle-même. - -Elles permettent notamment de connaître : - -- la version du schéma ; -- l'application ayant créé la base ; -- la date de création ; -- l'identifiant de l'enquête. - -Tables : - -```text -metadata -investigation -``` - ---- - -### Référentiels - -Les référentiels regroupent les listes de valeurs stables utilisées dans le -reste de la base. - -Ils évitent la duplication de chaînes de caractères et garantissent une -classification cohérente. - -Tables : - -```text -types_preuve -types_entite -types_source -types_outil -``` - ---- - -### Collecte - -La collecte représente toutes les actions réalisées pour obtenir de nouvelles -informations. - -Elle comprend : - -- les sources consultées ; -- les recherches effectuées ; -- les preuves collectées. - -Tables : - -```text -sources -recherches -preuves -``` - ---- - -### Connaissance - -Les preuves permettent d'identifier des objets réels. - -Ces objets deviennent des entités. - -Les relations établissent ensuite les liens entre ces entités. - -Tables : - -```text -entites -relations -``` - ---- - -### Raisonnement - -Les hypothèses représentent les conclusions provisoires formulées pendant -l'enquête. - -Elles s'appuient sur : - -- les preuves ; -- les recherches ; -- les relations ; -- les entités. - -Table : - -```text -hypotheses -``` - ---- - -### Traçabilité - -Deux mécanismes distincts assurent la traçabilité. - -La chronologie décrit les événements de l'enquête. - -Le journal décrit les actions réalisées dans l'application. - -Tables : - -```text -chronologie -journal -``` - ---- - -### Classification - -La classification facilite l'organisation des informations. - -Les catégories structurent les objets. - -Les tags permettent une annotation libre. - -Tables : - -```text -categories -tags -``` - ---- - -## 3.3 Flux d'investigation - -Le déroulement d'une enquête peut être représenté de manière simplifiée par le -schéma suivant : - -```text -Source - │ - ▼ -Recherche - │ - ▼ -Preuve - │ - ▼ -Entité - │ - ▼ -Relation - │ - ▼ -Hypothèse -``` - -Ce schéma représente uniquement le cheminement principal. - -En pratique, une enquête est beaucoup plus dynamique. - -Une recherche peut : - -- produire plusieurs preuves ; -- confirmer une preuve existante ; -- découvrir plusieurs entités ; -- modifier une relation ; -- renforcer ou contredire une hypothèse. - -De même : - -- une preuve peut être utilisée dans plusieurs recherches ; -- une entité peut apparaître dans plusieurs preuves ; -- une relation peut être soutenue par plusieurs preuves ; -- une hypothèse peut évoluer tout au long de l'enquête. - -Le modèle de données repose donc sur un réseau d'objets reliés entre eux, -plutôt que sur une chaîne linéaire. - -Les nombreuses tables de liaison présentes dans le schéma permettent de -représenter cette richesse tout en conservant un modèle relationnel simple et -cohérent. - ---- - -# 4. Tables métier - -Les tables métier représentent les objets manipulés quotidiennement par -l'application. - -Contrairement aux tables de référence, elles contiennent les données propres à -chaque enquête. - -Chaque table possède une responsabilité unique. - -Les relations entre ces objets sont assurées par des clés étrangères ou par -des tables de liaison dédiées. - ---- - -## 4.1 metadata - -### Responsabilité - -La table `metadata` stocke les informations techniques concernant la base de -données. - -Elle permet notamment d'identifier : - -- la version du schéma ; -- la version de l'application ayant créé la base ; -- les informations nécessaires aux futures migrations. - -Cette table ne contient aucune donnée liée à l'enquête elle-même. - -### Identifiant - -La table repose sur des clés textuelles (`key` / `value`) et non sur un UUID. - -### Relations principales - -Aucune. - -### Cycle de vie - -Les métadonnées sont créées lors de l'initialisation de la base puis modifiées -uniquement lors des migrations ou des mises à jour du schéma. - -### Points d'attention - -Cette table est utilisée pour déterminer la compatibilité entre la base de -données et l'application. - ---- - -## 4.2 investigation - -### Responsabilité - -La table `investigation` décrit l'enquête elle-même. - -Elle contient les informations générales nécessaires à son identification. - -Une base de données ne contient qu'une seule enquête. - -### Identifiant - -UUID. - -### Relations principales - -L'enquête constitue la racine logique de l'ensemble des objets métier. - -Les autres tables appartiennent implicitement à cette enquête. - -### Cycle de vie - -Créée automatiquement lors de l'initialisation de la base. - -Elle est ensuite très rarement modifiée. - -### Points d'attention - -Aucune seconde enquête ne doit être créée dans la même base SQLite. - ---- - -## 4.3 sources - -### Responsabilité - -Une source représente l'origine d'une information. - -Une source peut être : - -- un site web ; -- un réseau social ; -- une API ; -- un document ; -- une base publique ; -- une personne interrogée. - -### Identifiant - -UUID. - -### Relations principales - -Une source peut être utilisée par plusieurs recherches. - -### Cycle de vie - -Une source peut être enrichie au cours de l'enquête sans perdre son identité. - -### Points d'attention - -Une source ne constitue jamais une preuve. - -Elle décrit uniquement l'origine de l'information. - ---- - -## 4.4 recherches - -### Responsabilité - -Une recherche représente une action réalisée par l'enquêteur. - -Exemples : - -- requête WHOIS ; -- recherche Google ; -- interrogation d'une API ; -- analyse d'un document ; -- recherche DNS. - -### Identifiant - -UUID. - -### Relations principales - -Une recherche peut : - -- utiliser une source ; -- produire plusieurs preuves ; -- identifier des entités ; -- confirmer une relation ; -- enrichir une hypothèse ; -- générer des événements de chronologie. - -### Cycle de vie - -Une recherche est créée lorsqu'une action d'investigation est réalisée. - -Elle peut être enrichie ultérieurement. - -### Points d'attention - -Une recherche décrit une action, pas son résultat. - -Les résultats sont représentés par d'autres objets. - ---- - -## 4.5 preuves - -### Responsabilité - -Une preuve représente un élément collecté pendant l'enquête. - -Exemples : - -- capture d'écran ; -- photographie ; -- document ; -- vidéo ; -- archive ; -- export JSON. - -### Identifiant - -UUID. - -### Relations principales - -Une preuve peut : - -- provenir de plusieurs recherches ; -- contenir plusieurs entités ; -- soutenir plusieurs relations ; -- soutenir plusieurs hypothèses. - -### Cycle de vie - -Les preuves originales sont conservées. - -Les traitements réalisés sur une preuve créent de nouvelles informations mais -ne modifient pas le fichier original. - -### Points d'attention - -L'intégrité de la preuve est essentielle. - -Les métadonnées permettent notamment de suivre les empreintes cryptographiques. - -L'import groupé conserve ce modèle : chaque fichier sélectionné est révisé et -importé séparément. Les imports sont exécutés séquentiellement afin d'éviter -les écritures SQLite concurrentes. L'échec d'un fichier n'annule pas les -preuves déjà importées et apparaît dans le bilan final. - -Le classement, la source et la description peuvent être corrigés après -l'import. Un changement de type déplace la copie interne vers le dossier -adapté dans la même opération logique que la mise à jour SQLite. L'empreinte -et la taille sont vérifiées avant et après ; un échec annule la transaction et -restaure le chemin initial. L'UUID, le nom interne et la date d'import restent -inchangés. - ---- - -## 4.6 entites - -### Responsabilité - -Une entité représente un objet identifié. - -Exemples : - -- personne ; -- entreprise ; -- adresse IP ; -- adresse email ; -- nom de domaine ; -- numéro de téléphone. - -### Identifiant - -UUID. - -### Relations principales - -Les entités peuvent être reliées entre elles par des relations. - -Elles peuvent également apparaître dans plusieurs preuves. - -### Cycle de vie - -Une entité peut être enrichie au fur et à mesure de l'enquête. - -### Points d'attention - -Une entité doit représenter un objet unique. - -Les doublons doivent être évités. - ---- - -## 4.7 relations - -### Responsabilité - -Une relation représente un lien entre deux entités. - -Elle permet de formaliser les connaissances acquises. - -### Identifiant - -UUID. - -### Relations principales - -Une relation relie : - -- une entité source ; -- une entité cible. - -Elle peut être soutenue ou contredite par plusieurs preuves. - -### Cycle de vie - -Une relation peut évoluer avec l'arrivée de nouvelles preuves. - -### Points d'attention - -Une relation n'est jamais une hypothèse. - -Elle décrit un lien observé. - ---- - -## 4.8 chronologie - -### Responsabilité - -La chronologie raconte les événements importants de l'enquête. - -Elle permet de reconstruire le déroulement des investigations. - -### Identifiant - -UUID. - -### Relations principales - -Une entrée peut être liée à plusieurs objets métier. - -### Cycle de vie - -Les événements peuvent être créés automatiquement ou manuellement. - -### Points d'attention - -La chronologie décrit l'enquête, pas le fonctionnement interne de -l'application. - ---- - -## 4.9 journal - -### Responsabilité - -Le journal constitue la trace d'audit des opérations réalisées par -l'application. - -### Identifiant - -UUID. - -### Relations principales - -Les références vers les objets utilisent le couple : - -- objet_type ; -- objet_id. - -### Cycle de vie - -Les entrées sont ajoutées chronologiquement. - -### Points d'attention - -Le journal est conçu selon un modèle append-only. - -Les entrées existantes ne doivent pas être modifiées dans le fonctionnement -normal. - ---- - -## 4.10 hypotheses - -### Responsabilité - -Une hypothèse représente un raisonnement de l'enquêteur. - -Elle peut être soutenue, contredite ou confirmée. - -### Identifiant - -UUID. - -### Relations principales - -Une hypothèse peut être liée : - -- aux preuves ; -- aux entités ; -- aux relations ; -- aux recherches. - -### Cycle de vie - -Une hypothèse évolue au cours de l'enquête. - -Son niveau de confiance peut être réévalué. - -### Points d'attention - -Une hypothèse ne constitue pas un fait. - -Elle représente une conclusion provisoire. - ---- - -## 4.11 categories - -### Responsabilité - -Les catégories permettent de classer les objets métier dans un domaine -fonctionnel. - -### Identifiant - -UUID. - -### Relations principales - -Une catégorie peut être associée à plusieurs objets. - -Chaque objet ne possède qu'une seule catégorie. - -### Cycle de vie - -Les catégories évoluent peu. - -### Points d'attention - -Les catégories structurent les données. - -Elles ne remplacent pas les tags. - ---- - -## 4.12 tags - -### Responsabilité - -Les tags permettent d'annoter librement les objets métier. - -### Identifiant - -UUID. - -### Relations principales - -Les tags peuvent être associés à plusieurs types d'objets via des tables de -liaison. - -### Cycle de vie - -Les utilisateurs peuvent créer ou supprimer leurs propres tags. - -### Points d'attention - -Les tags complètent la classification mais ne modifient pas la structure du -modèle métier. - ---- - -# 5. Tables de référence - -Les tables de référence regroupent les listes de valeurs stables utilisées -dans l'ensemble de la base de données. - -Contrairement aux tables métier, leur contenu évolue peu. - -Leur objectif est de normaliser les données et d'éviter la duplication de -chaînes de caractères dans plusieurs tables. - -Les objets métier référencent ces tables au moyen d'identifiants entiers. - -Cette approche présente plusieurs avantages : - -- cohérence des valeurs utilisées ; -- réduction des risques de fautes de frappe ; -- simplification des contrôles d'intégrité ; -- meilleure lisibilité des données ; -- évolutions facilitées. - -Les tables de référence ne sont pas destinées à contenir des informations -propres à une enquête. - -Elles décrivent uniquement des classifications communes à toutes les -investigations. - ---- - -## 5.1 types_preuve - -Cette table décrit les différents types de preuves pouvant être enregistrés. - -Exemples : - -- capture d'écran ; -- photographie ; -- document ; -- archive ; -- vidéo ; -- export JSON. - -Les preuves référencent cette table afin d'identifier leur nature. - ---- - -## 5.2 types_entite - -Cette table définit les différents types d'entités manipulés par -l'application. - -Exemples : - -- personne ; -- organisation ; -- adresse IP ; -- nom de domaine ; -- adresse email ; -- numéro de téléphone ; -- compte de réseau social. - -Chaque entité appartient à un type unique. - ---- - -## 5.3 types_source - -Cette table décrit les catégories de sources utilisées pendant une enquête. - -Exemples : - -- site web ; -- moteur de recherche ; -- réseau social ; -- API ; -- document ; -- base publique. - -Les recherches utilisent ces informations pour caractériser leurs sources. - ---- - -## 5.4 types_outil - -Cette table répertorie les outils utilisés pendant les recherches. - -Exemples : - -- navigateur web ; -- dig ; -- whois ; -- curl ; -- nmap ; -- outil interne de Labfy Investigation. - -Cette classification permet de documenter précisément les méthodes employées -lors de la collecte d'informations. - ---- - -## Gestion des identifiants - -Contrairement aux objets métier, les tables de référence utilisent des -identifiants entiers. - -Ces identifiants sont définis par l'application. - -Ils sont stables et ne doivent pas être modifiés manuellement. - -Leur objectif est uniquement de faciliter les références entre les tables. - -Ils ne constituent pas des identifiants métier. - ---- - -## Évolutions - -L'ajout d'un nouveau type ne nécessite généralement aucune modification du -schéma de la base de données. - -Il suffit d'ajouter une nouvelle ligne dans la table concernée. - -En revanche, la suppression ou la modification d'un type existant doit être -réalisée avec précaution afin de préserver la cohérence des données déjà -enregistrées. - -### Traçabilité OSINT structurée — schéma V3 - -La table `osint_executions` conserve chaque exécution terminée, y compris -lorsque la révision est annulée. Elle contient notamment : - -- l'outil et sa version ; -- la cible et les arguments de l'exécution ; -- la date d'exécution ; -- les sorties standard et d'erreur sous forme de BLOB ; -- leur empreinte SHA-256. - -Les tables `osint_execution_entities` et `osint_execution_relations` relient -l'exécution aux objets intégrés. Le champ `disposition` distingue les objets -créés des objets réutilisés. Ces liaisons sont ajoutées dans la même -transaction que l'intégration DNS. - -Les descriptions métier restent présentes pour la lisibilité, mais les -entités DNS demeurent des résultats OSINT à vérifier et non des faits établis. - -Le menu contextuel du workspace permet de consulter cet historique pour -l'entité ou la relation sélectionnée. La vue est strictement en lecture seule -et expose les métadonnées, les sorties brutes rendues en UTF-8, l'empreinte et -les objets liés avec leur disposition `created` ou `reused`. - -Depuis ce détail, une vérification explicite recalcule l'empreinte SHA-256 à -partir des BLOB `stdout_raw` et `stderr_raw`, séparés par l'octet nul défini -lors de l'enregistrement. Le résultat indique si les sorties sont intactes, -altérées ou impossibles à vérifier. Ce contrôle est strictement en lecture -seule : aucune sortie ni empreinte persistée n'est corrigée automatiquement. - -### Comptes sociaux structurés — schéma V4 - -La table `comptes_sociaux` complète une ligne de `entites` sans dupliquer le -nœud affiché dans le graphe. Elle conserve la plateforme, l'URL de profil, le -pseudonyme affiché, l'identifiant stable facultatif, la première observation, -l'état observé et les notes factuelles. La contrainte unique sur -`(plateforme, url_profil)` évite les doublons. - -Une capture, une vidéo ou un courriel déjà importé peut être rattaché au -compte via `preuve_entites`. La création des deux lignes et de cette liaison -est transactionnelle : aucun nœud incomplet n'est conservé si une étape -échoue. - -### Rôles d'enquête des personnes — schémas V5 et V6 - -La table `person_roles` associe une entité de type personne à une catégorie -d'enquête contrôlée : scammer présumé, victime, témoin, suspect, personne liée, -identité usurpée ou non catégorisée. La clé étrangère avec suppression en cascade évite les -rôles orphelins. Le code stable est persisté ; le libellé et la couleur restent -des choix de présentation. - -Une personne sans ligne dans cette table est toujours interprétée comme non -catégorisée, ce qui garantit la compatibilité avec les enquêtes antérieures. - ---- - -# 6. Tables de liaison - -Le modèle de données de Labfy Investigation repose largement sur des relations -de type **plusieurs-à-plusieurs**. - -Plutôt que de multiplier les colonnes ou de stocker plusieurs valeurs dans un -même champ, chaque relation complexe est représentée par une table de liaison -dédiée. - -Cette approche permet : - -- de conserver un schéma normalisé ; -- d'éviter les redondances ; -- de garantir l'intégrité référentielle ; -- d'ajouter des informations propres à une relation lorsque cela est - nécessaire (par exemple une colonne `role`) ; -- de faire évoluer le modèle sans modifier les tables métier. - -Toutes les tables de liaison utilisent une clé primaire composite afin -d'empêcher les doublons. - ---- - -## 6.1 Liaisons des recherches - -Les recherches constituent le point d'entrée de nombreuses informations. - -Une même recherche peut produire plusieurs objets métier. - -Inversement, un objet métier peut résulter de plusieurs recherches. - -Les tables suivantes modélisent ces relations : - -```text -recherche_preuves -recherche_entites -recherche_relations -recherche_hypotheses -``` - -Ces tables permettent notamment de répondre aux questions suivantes : - -- quelles preuves ont été produites par cette recherche ? -- quelles recherches ont conduit à cette preuve ? -- quelles recherches ont confirmé cette relation ? -- quelle recherche est à l'origine d'une hypothèse ? - ---- - -## 6.2 Liaisons des preuves - -Les preuves constituent le socle de l'enquête. - -Elles peuvent révéler plusieurs entités. - -Inversement, une même entité peut apparaître dans plusieurs preuves. - -Les relations suivantes assurent cette représentation : - -```text -preuve_entites -relation_preuves -``` - -Ces tables permettent notamment de déterminer : - -- quelles entités apparaissent dans une preuve ; -- quelles preuves soutiennent une relation. - ---- - -## 6.3 Liaisons de la chronologie - -La chronologie décrit les événements importants de l'enquête. - -Un même événement peut être associé à plusieurs objets métier. - -Les tables suivantes assurent ces liens : - -```text -recherche_chronologie -preuve_chronologie -entite_chronologie -relation_chronologie -``` - -Cette architecture permet d'enrichir la chronologie sans modifier les tables -métier. - ---- - -## 6.4 Liaisons des hypothèses - -Les hypothèses constituent le niveau de raisonnement de l'enquête. - -Elles peuvent être : - -- soutenues ; -- contredites ; -- confirmées ; - -par différents objets. - -Les tables suivantes représentent ces relations : - -```text -hypothese_preuves -hypothese_entites -hypothese_relations -``` - -Certaines de ces tables utilisent une colonne : - -```text -role -``` - -Cette colonne précise le rôle joué par l'objet dans l'hypothèse. - -Exemples : - -```text -supports -contradicts -confirms -``` - -Cette approche offre une grande souplesse tout en conservant un schéma -relationnel simple. - ---- - -## 6.5 Liaisons des tags - -Les tags sont des annotations transversales. - -Ils peuvent être associés à plusieurs types d'objets métier. - -Les tables de liaison sont : - -```text -tag_preuves -tag_recherches -tag_entites -tag_relations -tag_hypotheses -tag_chronologie -``` - -Chaque table assure une relation plusieurs-à-plusieurs entre les tags et les -objets concernés. - -Cette organisation permet de conserver une architecture claire sans ajouter de -colonnes spécifiques dans chaque table métier. - ---- - -## Clés primaires composites - -Toutes les tables de liaison utilisent une clé primaire composite. - -Exemple : - -```sql -PRIMARY KEY ( - recherche_id, - preuve_id -) -``` - -Cette contrainte garantit qu'une même relation ne peut être enregistrée qu'une -seule fois. - -Elle évite les doublons sans nécessiter d'identifiant supplémentaire. - ---- - -## Clés étrangères - -Les tables de liaison utilisent systématiquement des clés étrangères. - -Le comportement associé (`CASCADE`, `RESTRICT` ou `SET NULL`) est choisi en -fonction de la signification métier de la relation. - -L'objectif est de préserver la cohérence des données tout en limitant les -suppressions accidentelles. - ---- - -## Évolutivité - -Les tables de liaison constituent l'un des principaux mécanismes d'extension du -modèle. - -Lorsqu'une nouvelle relation apparaît entre deux objets métier, il est -généralement préférable d'ajouter une nouvelle table de liaison plutôt que de -modifier les tables existantes. - -Cette stratégie limite les impacts sur le reste du schéma et facilite les -évolutions futures. - ---- - -# 7. Contraintes - -La qualité des données repose en grande partie sur les contraintes définies -dans le schéma SQL. - -Ces contraintes permettent de détecter les incohérences le plus tôt possible, -avant même que les données ne soient utilisées par l'application. - -Les contraintes SQL ne remplacent pas les validations réalisées dans le code C. - -Les deux mécanismes sont complémentaires : - -- SQLite garantit l'intégrité de la base de données ; -- l'application garantit la cohérence métier. - ---- - -## 7.1 Clés primaires - -Chaque objet métier possède une clé primaire. - -Les objets métier utilisent un UUID : - -```sql -id TEXT PRIMARY KEY -``` - -Les tables de référence utilisent des identifiants entiers. - -Les tables de liaison utilisent des clés primaires composites. - -Exemple : - -```sql -PRIMARY KEY ( - preuve_id, - entite_id -) -``` - -Cette approche garantit : - -- l'unicité des objets ; -- l'absence de doublons dans les relations ; -- une meilleure portabilité des données. - ---- - -## 7.2 Clés étrangères - -Les relations entre objets sont protégées par des clés étrangères. - -SQLite vérifie automatiquement que les objets référencés existent. - -Le comportement lors de la suppression dépend du contexte métier. - -Les principales stratégies utilisées sont : - -### CASCADE - -La suppression de l'objet parent entraîne automatiquement la suppression des -relations associées. - -Cette stratégie est principalement utilisée dans les tables de liaison. - ---- - -### RESTRICT - -La suppression est refusée tant que l'objet est encore utilisé. - -Cette stratégie protège les données importantes. - ---- - -### SET NULL - -La relation est conservée mais devient facultative. - -Cette approche est utilisée lorsque l'information reste pertinente même si -l'objet référencé disparaît. - ---- - -## 7.3 Contraintes CHECK - -Les contraintes `CHECK` assurent la validité élémentaire des données. - -Exemples : - -- chaînes non vides ; -- valeurs comprises dans une plage ; -- états autorisés ; -- cohérence entre plusieurs colonnes. - -Exemple : - -```sql -CHECK ( - confiance BETWEEN 0 AND 100 -) -``` - -Ou : - -```sql -CHECK ( - status IN ( - 'active', - 'archived', - 'deleted' - ) -) -``` - -Ces contraintes empêchent l'enregistrement de valeurs incohérentes. - ---- - -## 7.4 Contraintes UNIQUE - -Certaines informations doivent rester uniques. - -Les contraintes `UNIQUE` permettent d'empêcher les doublons. - -Exemples : - -- nom d'une catégorie ; -- nom d'un tag ; -- autres identifiants définis comme uniques. - -Lorsque cela est pertinent, la comparaison est réalisée sans tenir compte de -la casse (`COLLATE NOCASE`). - ---- - -## 7.5 Validation applicative - -Toutes les validations ne peuvent pas être exprimées uniquement en SQL. - -Certaines règles restent du ressort de l'application. - -Exemples : - -- validité d'un UUID ; -- format d'une adresse email ; -- validité d'un IBAN ; -- calcul des empreintes cryptographiques ; -- contrôle de la taille des fichiers ; -- vérification du contenu d'une archive. - -Le code C complète donc les protections offertes par SQLite. - ---- - -## 7.6 Intégrité métier - -Certaines règles concernent le fonctionnement même de l'enquête. - -Par exemple : - -- une preuve originale ne doit pas être modifiée ; -- une hypothèse ne constitue jamais un fait établi ; -- le journal est append-only ; -- une recherche décrit une action et non son résultat. - -Ces règles sont appliquées par la couche métier de l'application et ne peuvent -pas être garanties uniquement par le schéma SQL. - ---- - -## 7.7 Défense en profondeur - -Labfy Investigation applique plusieurs niveaux de validation. - -```text -Utilisateur - │ - ▼ -Interface GTK - │ - ▼ -Validation métier - │ - ▼ -Couche Database - │ - ▼ +Services métier + ↓ +DAO + ↓ +Infrastructure Database + ↓ SQLite ``` -Chaque niveau vérifie les données avant de les transmettre au niveau suivant. +### 4.1 Infrastructure Database -Cette approche permet : +`src/database` gère : -- de détecter rapidement les erreurs ; -- de limiter les incohérences ; -- de protéger la base contre les corruptions accidentelles ; -- de simplifier le débogage. +- ouverture et fermeture ; +- activation des pragmas ; +- version du schéma ; +- installation ; +- migrations ; +- statements ; +- transactions ; +- erreurs SQLite. + +### 4.2 DAO + +`src/dao` gère les requêtes métier : + +- insertion ; +- lecture ; +- mise à jour autorisée ; +- recherche ; +- transformation ligne ↔ modèle. + +### 4.3 Services + +Les services définissent les workflows et frontières transactionnelles qui +impliquent plusieurs DAO ou le système de fichiers. + +### 4.4 Interface + +Les vues et widgets n'exécutent aucune requête SQL. --- -# 8. Index +## 5. Versionnement -Les index ont pour objectif d'améliorer les performances des requêtes les plus -fréquentes sans modifier le modèle de données. +La version courante est stockée dans : -Ils permettent à SQLite de localiser rapidement les enregistrements recherchés -sans parcourir l'intégralité des tables. +```text +metadata.schema_version +``` -Les index sont définis dès la conception du schéma afin de garantir des -performances cohérentes, même lorsque les bases de données deviennent -volumineuses. +L'application connaît également une constante de version courante. -Le choix des index repose sur les usages attendus de Labfy Investigation et -non sur une optimisation prématurée. +Une base plus récente que l'application doit être refusée. + +Une base plus ancienne est migrée étape par étape jusqu'à la version courante. + +Les scripts sont conservés : + +```text +database/schema_v1.sql +database/schema_v2.sql +database/schema_v3.sql +database/schema_v4.sql +database/schema_v5.sql +database/schema_v6.sql +database/schema_v7.sql +database/schema_v8.sql +database/schema_v9.sql +database/schema_v10.sql +``` + +`database/schema_current.sql` contient des extensions ou réparations +idempotentes nécessaires au schéma courant. + +Ce fichier ne remplace pas les migrations versionnées. --- -## 8.1 Objectifs +## 6. Création d'une base neuve -Les index sont principalement utilisés pour accélérer les opérations suivantes : +Une base neuve est initialisée dans une transaction. -- recherche d'un objet par son identifiant ; -- navigation entre les objets liés ; -- filtrage par statut ; -- tri chronologique ; -- recherche par catégorie ; -- recherche par tag ; -- consultation de la chronologie ; -- consultation du journal. +Le flux général est : -Ils permettent également de limiter le coût des nombreuses jointures entre les -tables métier. +```text +ouverture SQLite + ↓ +PRAGMA foreign_keys = ON + ↓ +BEGIN + ↓ +installation V1 à V10 + ↓ +application du schéma courant idempotent + ↓ +métadonnées et enquête + ↓ +COMMIT +``` + +Un échec provoque un rollback. + +Une base neuve doit aboutir directement à : + +```text +schema_version = 10 +``` --- -## 8.2 Politique +## 7. Chaîne de migrations -Les index sont créés selon plusieurs principes. +Résumé fonctionnel : -### Clés étrangères +| Version | Évolution principale | +|---|---| +| V1 | socle métier initial de l'enquête | +| V2 | persistance enrichie des preuves | +| V3 | provenance structurée des exécutions OSINT | +| V4 | comptes sociaux | +| V5 | rôles d'enquête des personnes et présentation associée | +| V6 | extensions liées aux personnes et identités observées | +| V7 | extractions liées aux preuves ou entités | +| V8 | persistance de l'état du graphe et du viewport | +| V9 | types canoniques de relations | +| V10 | entités bancaires et types de relations du pivot e-mail | -Les colonnes utilisées comme clés étrangères sont systématiquement indexées. +Chaque migration possède une fonction dédiée. -Cette règle améliore les performances des jointures ainsi que les contrôles -d'intégrité réalisés par SQLite. +Le numéro de version est mis à jour uniquement après l'installation réussie de +la nouvelle version. --- -### Dates +## 8. Domaines du schéma -Les colonnes utilisées pour les tris chronologiques sont indexées. +Le schéma couvre plusieurs domaines. + +### 8.1 Identité de l'enquête + +- métadonnées techniques ; +- identité de l'enquête ; +- version du schéma. + +### 8.2 Référentiels + +- types de preuves ; +- types d'entités ; +- types d'outils et sources selon le schéma ; +- types canoniques de relations ; +- vocabulaires contrôlés gérés par le code et les contraintes. + +### 8.3 Preuves + +- enregistrement des preuves ; +- classification ; +- chemins relatifs ; +- empreintes ; +- taille ; +- source ; +- intégrité ; +- associations avec d'autres objets. + +La preuve originale reste sur disque. + +### 8.4 Entités + +- entités génériques ; +- comptes sociaux ; +- personnes et rôles ; +- extensions spécialisées ; +- comptes bancaires V10. + +### 8.5 Relations + +Une relation relie une source et une cible. + +Les types de relations sont centralisés pour éviter les variantes textuelles +incohérentes. + +Les preuves peuvent soutenir ou documenter une relation selon les tables de +liaison prévues. + +### 8.6 OSINT et provenance + +Le schéma conserve selon les fonctionnalités : + +- exécution ; +- outil et version ; +- cible ; +- arguments ; +- dates ; +- code de retour ; +- sorties brutes ; +- empreintes ; +- liens vers les objets créés ou réutilisés. + +### 8.7 Extractions + +Une extraction est reliée à une preuve ou à une entité source. + +Elle conserve l'outil, la date et son origine logique. + +Les fichiers ou textes produits doivent rester traçables. + +### 8.8 Graphe + +Les positions et le viewport sont des données de présentation. + +Ils restent séparés des entités et relations métier. + +Une clé étrangère polymorphe n'étant pas disponible dans SQLite, le nettoyage +de certaines positions génériques est assuré par des triggers. + +--- + +## 9. V10 — Entités bancaires + +La V10 ajoute : + +```text +bank_account_entities +``` + +Cette table conserve : + +- `id` ; +- `iban` ; +- `bic` ; +- `holder_name` ; +- `bank_name` ; +- `bank_address` ; +- `country_code` ; +- `bank_code` ; +- `branch_code` ; +- `account_number` ; +- `rib_key` ; +- `verification_status` ; +- `provenance_kind` ; +- `evidence_id` ; +- `extraction_id` ; +- `created_at` ; +- `updated_at`. + +### 9.1 Statuts contrôlés + +```text +proposed +confirmed +rejected +conflicted +invalid +``` + +### 9.2 Provenances contrôlées + +```text +observed +ocr +header +metadata +derived +manual +``` + +### 9.3 Références + +```text +evidence_id → preuves(id) ON DELETE SET NULL +extraction_id → extractions(id) ON DELETE SET NULL +``` + +La disparition d'une source ne supprime pas automatiquement la donnée bancaire +structurée. + +### 9.4 Index + +La V10 crée des index sur : + +- l'IBAN ; +- la preuve source. + +### 9.5 Interprétation + +Un nom observé comme titulaire ne prouve pas que cette personne est l'auteur +d'une fraude. + +Un IBAN détecté par OCR reste une proposition tant que sa validation et sa +confirmation n'ont pas été établies. + +Une correction OCR ne doit jamais remplacer silencieusement la valeur brute. + +--- + +## 10. Types de relations V10 + +La V10 ajoute les codes système suivants : + +```text +sent_from +sent_to +reply_to +has_attachment +relayed_by +uses_domain +held_at +named_as_holder_of +supports +``` + +Les codes sont stables. + +Les libellés français peuvent évoluer sans migration des codes. + +La formulation d'une relation doit rester factuelle. Exemples : -- `created_at` -- `updated_at` -- `event_time` - -Ces index facilitent la consultation des événements récents et des historiques -d'une enquête. +- `relayed_by` décrit un relais observé dans la chaîne SMTP ; +- `named_as_holder_of` décrit un nom présenté comme titulaire ; +- aucun de ces liens ne constitue automatiquement une attribution criminelle. --- -### États +## 11. Schéma courant idempotent -Les colonnes `status` sont indexées lorsque leur utilisation est fréquente. +`database/schema_current.sql` complète les structures nécessaires à +l'ouverture, notamment autour : -Cela permet notamment de retrouver rapidement les objets : +- des extractions ; +- des positions du graphe ; +- du viewport ; +- des types de relations ; +- des triggers de nettoyage. -- actifs ; -- archivés ; -- supprimés logiquement. +Les instructions utilisent `IF NOT EXISTS` ou des opérations idempotentes +lorsque cela est nécessaire. + +Ce mécanisme sert à maintenir la compatibilité, mais ne doit pas devenir une +migration cachée non versionnée. + +Toute évolution métier persistante significative doit recevoir une nouvelle +version de schéma. --- -### Tables de liaison +## 12. Intégrité et suppression -Les tables de liaison possèdent une clé primaire composite. +### 12.1 Suppression logique -Des index complémentaires peuvent être ajoutés lorsque les recherches sont -souvent réalisées dans le sens inverse de cette clé. +La suppression logique est privilégiée lorsque le modèle prévoit un champ +d'état et que la traçabilité l'exige. -Exemple : +### 12.2 Suppression physique + +Elle reste possible pour certaines tables selon leurs contraintes. + +La règle doit être définie table par table. + +### 12.3 Vérifications + +Les tests de migration doivent exécuter : ```sql -PRIMARY KEY ( - tag_id, - preuve_id -) +PRAGMA integrity_check; +PRAGMA foreign_key_check; ``` -Un index supplémentaire sur : - -```sql -preuve_id -``` - -permet de retrouver rapidement tous les tags associés à une preuve. +Une migration n'est pas considérée sûre uniquement parce que son script ne +retourne pas d'erreur. --- -### Équilibre +## 13. Tests attendus -Chaque index améliore certaines requêtes mais augmente également : +La couche Database doit couvrir : -- la taille de la base de données ; -- le coût des insertions ; -- le coût des mises à jour. +- création d'une base neuve V10 ; +- lecture de la version ; +- refus d'une version future ; +- migration d'une ancienne base ; +- conservation des données ; +- rollback provoqué ; +- contraintes ; +- clés étrangères ; +- statements ; +- transactions imbriquées ou interdites selon l'API ; +- réouverture idempotente ; +- DAO principaux ; +- V9 vers V10 avec données synthétiques ; +- table `bank_account_entities` ; +- unicité et réutilisation des types de relations. -Les index sont donc créés uniquement lorsqu'ils répondent à un besoin -identifié. +Matrice minimale recommandée : -Aucun index n'est ajouté sans justification fonctionnelle. +| Entrée | Résultat | +|---|---| +| base neuve | V10 valide | +| V1 | migration complète vers V10 | +| V9 | migration directe vers V10 | +| V10 | réouverture sans modification destructive | +| version > V10 | refus clair | +| migration forcée en échec | rollback complet | --- -## 8.3 Évolution +## 14. Procédure de modification -La politique d'indexation pourra évoluer à mesure que l'application grandira. +Pour une future V11 : -Toute modification devra être basée sur : - -- des mesures de performances ; -- des profils d'utilisation réels ; -- des besoins fonctionnels identifiés. - -Les optimisations devront privilégier la simplicité du schéma et préserver la -compatibilité avec les versions précédentes de la base de données. +1. auditer le schéma V10 ; +2. définir les invariants ; +3. ajouter `schema_v11.sql` ; +4. ajouter `schema_install_v11()` ; +5. ajouter `database_migrate_v10_to_v11()` ; +6. raccorder la boucle de migration ; +7. mettre à jour la version courante ; +8. adapter la création d'une base neuve ; +9. adapter `schema_current.sql` seulement si nécessaire ; +10. ajouter une fixture V10 ; +11. tester le rollback ; +12. exécuter les deux pragmas d'intégrité ; +13. mettre à jour ce document ; +14. mettre à jour `SCHEMA_AUDIT_CURRENT.md` ; +15. conserver une copie versionnée `SCHEMA_AUDIT_V11.md`. --- -# 9. Versionnement +## 15. Limites et points de vigilance -Le schéma de la base de données est versionné. - -Chaque base SQLite créée par Labfy Investigation possède un numéro de version -permettant à l'application de déterminer si elle est compatible avec le -logiciel utilisé. - -Le versionnement constitue un élément essentiel de la pérennité des données. - -Une enquête créée aujourd'hui doit pouvoir être ouverte plusieurs années plus -tard par une version plus récente de l'application. +- V10 fournit le socle bancaire, mais ne termine pas à elle seule le ticket + complet du pivot EML ; +- les valeurs OCR ne doivent pas être confirmées automatiquement ; +- la provenance doit rester suffisante pour revenir à la source ; +- le schéma courant idempotent ne doit pas masquer l'absence d'une migration ; +- les DAO doivent rester la seule couche de requêtes métier ; +- les widgets ne doivent jamais accéder directement à SQLite ; +- les fixtures utilisent exclusivement des données synthétiques ; +- aucune base réelle d'enquête ne doit être ajoutée au dépôt. --- -## 9.1 Version du schéma - -La version du schéma est enregistrée dans la table : +## 16. Références ```text -metadata +database/schema_v1.sql +database/schema_v2.sql +database/schema_v3.sql +database/schema_v4.sql +database/schema_v5.sql +database/schema_v6.sql +database/schema_v7.sql +database/schema_v8.sql +database/schema_v9.sql +database/schema_v10.sql +database/schema_current.sql + +src/database/database.c +src/database/schema.c +src/database/statement.c +src/database/transaction.c +src/database/error.c + +src/dao/ +tests/test_database.c +docs/database/SCHEMA_AUDIT_CURRENT.md ``` - -La clé : - -```text -schema_version -``` - -identifie la version de l'architecture utilisée par la base. - -Pour cette première version : - -```text -schema_version = 1 -``` - -Cette valeur constitue la référence de toute la documentation associée à la -V1. - ---- - -## 9.2 Compatibilité - -Le logiciel vérifie la version du schéma avant d'ouvrir une enquête. - -Trois situations sont possibles : - -### Même version - -La base est compatible. - -L'ouverture de l'enquête peut se poursuivre normalement. - ---- - -### Version plus ancienne - -Une migration peut être proposée si elle existe. - -La migration permet d'adapter progressivement la base vers une version plus -récente du schéma. - ---- - -### Version plus récente - -Le logiciel refuse d'ouvrir la base. - -Cette situation indique généralement que l'enquête a été créée avec une -version plus récente de Labfy Investigation. - -Une ancienne version du logiciel ne doit jamais tenter de modifier une base -qu'elle ne comprend pas. - ---- - -## 9.3 Migrations - -Toute évolution incompatible du schéma devra être réalisée à l'aide d'une -migration. - -Une migration est une opération contrôlée permettant de transformer une base -existante vers une nouvelle version du schéma. - -Chaque migration devra respecter les règles suivantes : - -- être transactionnelle ; -- préserver les données existantes ; -- être documentée ; -- être reproductible ; -- pouvoir détecter les erreurs. - -Avant toute migration, une sauvegarde complète de la base devra être réalisée. - -En cas d'échec, la base devra être restaurée dans son état initial. - ---- - -## 9.4 Compatibilité ascendante - -Une fois une version du schéma publiée, elle devient une référence. - -Les évolutions futures devront privilégier : - -- l'ajout de nouvelles tables ; -- l'ajout de nouvelles colonnes compatibles ; -- l'ajout de nouveaux index ; -- l'ajout de nouvelles contraintes lorsque cela reste compatible. - -Les modifications destructives devront être évitées autant que possible. - ---- - -## 9.5 Politique d'évolution - -Les évolutions du schéma suivent les principes suivants : - -- ne jamais casser une enquête existante sans migration ; -- documenter chaque changement ; -- conserver la cohérence du modèle métier ; -- maintenir la compatibilité avec les outils de développement et de test. - -Toute modification du schéma doit être accompagnée : - -- d'une mise à jour de `schema_v1.sql` (ou de la version concernée) ; -- d'une mise à jour de la documentation ; -- d'une adaptation des tests unitaires ; -- d'une revue d'architecture si le changement impacte le modèle métier. - ---- - -## 9.6 Cycle de vie du schéma - -Le cycle de vie d'une nouvelle version suit les étapes suivantes : - -```text -Conception - │ - ▼ -Validation - │ - ▼ -Implémentation SQL - │ - ▼ -Tests unitaires - │ - ▼ -Documentation - │ - ▼ -Publication - │ - ▼ -Maintenance -``` - -Une version publiée ne doit plus être modifiée directement. - -Toute évolution ultérieure devra conduire à une nouvelle version du schéma. - ---- - -## 9.7 Philosophie - -Le schéma de la base de données constitue un contrat entre l'application et les -données. - -Une évolution du schéma ne doit jamais être décidée uniquement pour simplifier -le code. - -Au contraire, le code de l'application doit s'adapter au schéma validé. - -Cette approche garantit : - -- la stabilité des données ; -- la lisibilité du projet ; -- la fiabilité des migrations ; -- la pérennité des enquêtes. - ---- - -# 10. Architecture C - -La base de données est entièrement encapsulée dans une couche logicielle -dédiée. - -Les autres composants de Labfy Investigation ne manipulent jamais directement -SQLite. - -Cette séparation permet d'isoler les détails d'implémentation de la base de -données du reste de l'application. - -L'objectif est de garantir une architecture modulaire, testable et facilement -maintenable. - ---- - -## 10.1 Organisation - -La couche Database est répartie entre les répertoires : - -```text -include/database/ -src/database/ -``` - -Chaque objet métier possède son propre module. - -Cette organisation permet de limiter les dépendances entre les différents -composants. - -L'ensemble de la couche Database constitue l'unique point d'accès aux données. - ---- - -## 10.2 Modules - -L'organisation cible est la suivante : - -```text -database/ -├── database.c -├── database_connection.c -├── schema.c -├── metadata.c -├── investigation.c -├── source.c -├── recherche.c -├── preuve.c -├── entite.c -├── relation.c -├── chronologie.c -├── journal.c -├── hypothese.c -├── categorie.c -└── tag.c -``` - -Chaque fichier `.c` possède son fichier d'en-tête correspondant dans : - -```text -include/database/ -``` - -Cette organisation représente l'architecture cible de la couche Database. - -Tous les modules ne sont pas nécessairement implémentés dès la première -version de l'application. - ---- - -## 10.3 Responsabilités - -Chaque module possède une responsabilité clairement définie. - -Par exemple : - -- `preuve.c` gère les preuves ; -- `entite.c` gère les entités ; -- `relation.c` gère les relations ; -- `source.c` gère les sources ; -- `hypothese.c` gère les hypothèses. - -Un module ne doit jamais gérer plusieurs concepts métier indépendants. - -Les opérations transversales sont regroupées dans des modules spécifiques. - ---- - -## 10.4 API publique - -Les autres composants de l'application utilisent exclusivement les fonctions -publiques exposées par les fichiers d'en-tête. - -Ils ne doivent jamais : - -- ouvrir directement une base SQLite ; -- construire une requête SQL ; -- préparer une instruction SQLite ; -- manipuler les structures internes de SQLite. - -Cette règle garantit une séparation claire entre la logique métier et la -persistance des données. - ---- - -## 10.5 Gestion des erreurs - -Toutes les erreurs provenant de SQLite sont traitées par la couche Database. - -Les fonctions publiques retournent des valeurs adaptées à leur usage : - -- `bool` pour les opérations simples ; -- pointeurs vers des objets en cas de création ou de lecture ; -- `NULL` lorsqu'une opération échoue. - -Les messages d'erreur détaillés sont journalisés dans un point unique afin de -faciliter le débogage. - ---- - -## 10.6 Gestion mémoire - -La couche Database respecte les conventions mémoire du projet. - -Les objets retournés par l'API possèdent un propriétaire clairement identifié. - -Chaque fonction de création possède une fonction de destruction associée. - -Exemple : - -```c -preuve_new(...) -preuve_free(...) -``` - -Cette règle garantit une gestion mémoire simple et prévisible. - ---- - -## 10.7 Transactions - -Les transactions SQLite sont gérées exclusivement par la couche Database. - -Une fonction appelante ne doit jamais ouvrir ou fermer directement une -transaction. - -Cette centralisation garantit la cohérence des opérations complexes et limite -les risques d'états intermédiaires incohérents. - ---- - -## 10.8 Évolutivité - -L'organisation modulaire permet d'ajouter de nouvelles fonctionnalités sans -modifier les modules existants. - -L'ajout d'un nouvel objet métier conduit généralement à la création : - -- d'une nouvelle table ; -- d'un nouveau module `.c` ; -- d'un nouveau fichier d'en-tête ; -- de nouveaux tests unitaires. - -Cette approche limite les régressions et facilite la maintenance du projet. - ---- - -## 10.9 Tests unitaires - -Chaque module Database doit disposer de ses propres tests unitaires. - -Les tests vérifient notamment : - -- les créations d'objets ; -- les lectures ; -- les mises à jour ; -- les suppressions logiques ; -- les contraintes d'intégrité ; -- les cas d'erreur. - -Aucune fonctionnalité de la couche Database ne doit être considérée comme -terminée sans tests associés. - ---- - -## 10.10 Principe directeur - -La couche Database constitue la seule interface entre l'application et les -données persistantes. - -Les autres composants manipulent uniquement des objets métier et des fonctions -publiques. - -Cette séparation garantit : - -- une architecture claire ; -- une meilleure testabilité ; -- une maintenance simplifiée ; -- une évolution indépendante de la base de données et de l'interface - utilisateur. - ---- - -# 11. Diagramme général - -Le schéma relationnel complet de Labfy Investigation comporte un nombre -important de tables et de relations. - -Afin de faciliter sa compréhension, ce document présente une vue simplifiée du -modèle métier. - -L'objectif de ce diagramme n'est pas de représenter chaque clé étrangère mais -de montrer la circulation de l'information au sein d'une enquête. - ---- - -## 11.1 Vue métier - -```text - Investigation - │ - ┌───────────────────────────┼───────────────────────────┐ - │ │ │ - ▼ ▼ ▼ - Métadonnées Collecte Classification - │ │ │ - │ ┌─────┴─────┐ ┌─────┴─────┐ - │ ▼ ▼ ▼ ▼ - │ Sources Recherches Catégories Tags - │ │ - │ ▼ - │ Preuves - │ │ - │ ┌────────┴────────┐ - │ ▼ ▼ - │ Entités Chronologie - │ │ - │ ▼ - │ Relations - │ │ - │ ▼ - │ Hypothèses - │ - ▼ - Journal -``` - ---- - -## 11.2 Cycle d'une investigation - -Le déroulement d'une enquête suit généralement les étapes suivantes. - -```text -Source - │ - ▼ -Recherche - │ - ▼ -Preuve - │ - ▼ -Entité - │ - ▼ -Relation - │ - ▼ -Hypothèse -``` - -Ce cycle représente uniquement le cheminement principal. - -En pratique, une enquête est itérative. - -Une nouvelle recherche peut : - -- confirmer une preuve existante ; -- découvrir une nouvelle entité ; -- modifier une relation ; -- renforcer ou affaiblir une hypothèse. - -Le modèle de données a été conçu pour permettre ces allers-retours sans perdre -la traçabilité des informations. - ---- - -## 11.3 Traçabilité - -Chaque information importante peut être reliée à son origine. - -```text -Source - │ - ▼ -Recherche - │ - ▼ -Preuve - │ - ▼ -Entité - │ - ▼ -Relation - │ - ▼ -Hypothèse -``` - -En parallèle : - -```text -Recherche - │ - ├──────────────► Chronologie - │ - └──────────────► Journal -``` - -La chronologie décrit les événements de l'enquête. - -Le journal enregistre les actions réalisées dans le logiciel. - -Ces deux mécanismes sont volontairement séparés. - ---- - -## 11.4 Philosophie du modèle - -Le modèle de Labfy Investigation repose sur plusieurs principes. - -Les objets métier représentent les concepts manipulés par les enquêteurs. - -Les relations entre ces objets sont explicites et documentées. - -Les fichiers originaux restent inchangés. - -Toutes les informations produites pendant une enquête demeurent traçables. - -Le modèle privilégie : - -- la clarté ; -- la cohérence ; -- l'intégrité des données ; -- l'évolutivité. - -L'objectif est de permettre à l'application de reproduire fidèlement le -raisonnement suivi pendant une investigation, plutôt que de simplement stocker -des fichiers ou des notes. - ---- - -## 11.5 Disposition générique du graphe - -La disposition visuelle du graphe est un état de présentation et non une -donnée métier. Elle est stockée dans `graph_layout_positions`, séparément des -tables `entites` et `relations`. - -Chaque ligne associe un UUID de nœud à des coordonnées logiques et à une date -UTC de mise à jour. Un nœud peut représenter une entité ou une relation. SQLite -ne proposant pas de clé étrangère polymorphe, l'intégrité de ce stockage est -assurée par deux triggers qui suppriment la position correspondante lors de la -suppression physique d'une entité ou d'une relation. - -La table historique `graph_node_positions` ne référençait que `entites(id)`. -À l'ouverture d'une enquête, ses lignes sont copiées de manière idempotente -vers `graph_layout_positions`, puis retirées de la table historique afin -qu'une réinitialisation volontaire de la disposition ne puisse pas restaurer -des coordonnées obsolètes. - -Cette stratégie préserve les positions existantes tout en permettant aux -nœuds de relation de suivre exactement le même cycle de chargement, -d'enregistrement et de réinitialisation que les nœuds d'entité. - -Le cadrage global est stocké séparément dans la ligne unique de -`graph_viewport`. Elle conserve le niveau de zoom et les décalages horizontal -et vertical du canevas. Ces valeurs sont enregistrées à la fermeture de -l'enquête et restaurées lors de son premier chargement, afin que la vue -réapparaisse exactement à l'endroit où l'utilisateur l'avait laissée. - -## 11.6 Types canoniques de relations - -`relation_types` constitue le référentiel persistant des catégories de -relations. Chaque type possède un identifiant SQLite, un libellé canonique, -une clé Unicode normalisée unique, une description facultative et un -indicateur système. Les types utilisés automatiquement possèdent en plus un -`code` métier stable, indépendant de la langue et du libellé affiché. - -Les quatre notions sont distinctes : - -- le **code métier stable** pilote les producteurs automatiques tels que DNS ; -- le **libellé canonique** est affiché dans le graphe et l’interface ; -- la **clé normalisée** sert uniquement à garantir l’unicité Unicode ; -- le **libellé libre de la relation** décrit le fait précis observé. - -Depuis le schéma V9, `relations.relation_type_id` référence ce référentiel. -L’unicité d’une relation orientée repose sur la source, la cible et cet -identifiant canonique. La colonne historique `type_relation` n’est conservée -que pour la compatibilité des bases antérieures et n’est plus une identité. - -La migration V8 vers V9 parcourt les relations par date puis UUID. Elle -normalise les espaces Unicode, applique NFC et le casefold Unicode, conserve -la première graphie comme libellé des types personnalisés et rattache chaque -relation au type obtenu. Les UUID, métadonnées et tables d’association ne sont -pas reconstruits. Un contrôle `foreign_key_check` précède le COMMIT. - ---- - -# 12. Conclusion - -La base de données de Labfy Investigation constitue bien davantage qu'un simple -espace de stockage. - -Elle représente le modèle métier de l'application. - -Chaque décision d'architecture a été prise afin de répondre à trois objectifs -principaux : - -- préserver l'intégrité des données ; -- garantir leur traçabilité ; -- permettre l'évolution du logiciel sur le long terme. - -Le schéma V1 repose sur une séparation claire des responsabilités. - -Chaque table représente un concept métier unique. - -Les relations entre ces concepts sont explicites et documentées. - -Les contraintes SQL assurent la cohérence des données tandis que la couche -Database applique les règles métier qui ne peuvent être exprimées dans le -schéma relationnel. - -Cette architecture permet de représenter fidèlement le déroulement d'une -investigation numérique : - -```text -Source - │ - ▼ -Recherche - │ - ▼ -Preuve - │ - ▼ -Entité - │ - ▼ -Relation - │ - ▼ -Hypothèse -``` - -À chaque étape, les informations restent reliées à leur origine et peuvent -être replacées dans leur contexte grâce à la chronologie et au journal -d'audit. - -Le choix d'utiliser une base SQLite autonome pour chaque enquête garantit la -portabilité, facilite les sauvegardes et simplifie les échanges entre -enquêteurs. - -Le schéma V1 constitue désormais la référence de développement de Labfy -Investigation. - -Toute évolution future devra respecter les principes définis dans cette -documentation : - -- documenter les besoins avant toute modification ; -- préserver la compatibilité des données ; -- privilégier l'ajout de nouveaux objets plutôt que la modification des objets - existants ; -- accompagner toute évolution d'une migration, d'une documentation et de tests - adaptés. - -Le schéma SQL, la documentation et les tests unitaires forment un ensemble -indissociable. - -Aucun de ces éléments ne doit évoluer indépendamment des autres. - -L'objectif final n'est pas uniquement de stocker des données, mais de fournir -une base solide permettant de développer un logiciel d'investigation fiable, -maintenable et pérenne. - ---- - -## Statut - -À la publication de ce document : - -- le schéma V1 est considéré comme stable ; -- il constitue la référence officielle de la couche Database ; -- toute évolution incompatible devra faire l'objet d'une nouvelle version du - schéma et d'une migration documentée. - ---- - -## Pivot e-mail et comptes bancaires - -La version V10 ajoute `bank_account_entities`, qui conserve les composants -IBAN/RIB ainsi que leur statut de vérification et leur provenance. Une valeur -extraite par OCR reste une proposition (`proposed`) ; une dérivation locale -est marquée `derived` et ne devient jamais automatiquement une donnée -confirmée. Les fichiers EML dérivés restent reliés à leur preuve source par -les tables d’association existantes. - -Les codes de statuts, de provenance, de rôles d’adresse et de type de valeur -sont fournis par `controlled_vocab` : les codes techniques sont stables et -les libellés affichés sont séparés. - -## Références - -Documents associés : - -- `database/schema_v1.sql` -- `docs/database/SCHEMA_AUDIT_V1.md` -- `docs/database/DATABASE_ARCHITECTURE.md` -- `docs/CONVENTIONS.md` - -Ces documents constituent ensemble la documentation de référence de -l'architecture de la base de données de Labfy Investigation. diff --git a/docs/database/SCHEMA_AUDIT_CURRENT.md b/docs/database/SCHEMA_AUDIT_CURRENT.md new file mode 100644 index 0000000..56bac8d --- /dev/null +++ b/docs/database/SCHEMA_AUDIT_CURRENT.md @@ -0,0 +1,1581 @@ +# Audit du schéma SQLite courant — V10 + +> [!IMPORTANT] +> Ce document décrit le schéma réellement présent sur la branche `main` au +> commit `613d2096bc5eeb2c1c4f60ae701292e19a2abe66`. +> +> Il distingue l’implémentation SQLite V10 du chantier fonctionnel plus large +> du pivot e-mail suivi dans le ticket Forgejo #107, qui reste ouvert. + +> **Projet :** Labfy Investigation +> **Date de l’audit :** 2026-07-24 +> **Branche auditée :** `main` publique sur Forgejo +> **Commit audité :** `613d2096bc5eeb2c1c4f60ae701292e19a2abe66` +> **Version de schéma confirmée par le code :** **V10** +> **Statut du document :** audit courant vérifié de la V10 +> **Périmètre :** schémas SQL, mécanisme de migration, couche Database, tests, +> documentation et tickets Forgejo associés + +--- + +# 1. Résumé exécutif + +Le schéma SQLite courant de Labfy Investigation est la **V10**. + +Cette conclusion est confirmée conjointement par : + +- `DATABASE_SCHEMA_VERSION_CURRENT 10` ; +- `DATABASE_SCHEMA_VERSION_CURRENT_TEXT "10"` ; +- `database/schema_v10.sql` ; +- `schema_install_v10()` ; +- `database_migrate_v9_to_v10()` ; +- le cas `9` de `database_migrate_to_latest()` ; +- l’installation de V10 dans `database_initialize()` ; +- les assertions V10 de `tests/test_database.c`. + +La V10 ajoute principalement : + +- la table `bank_account_entities` ; +- la conservation structurée des données IBAN, BIC et RIB ; +- un statut de vérification contrôlé ; +- une provenance contrôlée ; +- des liens facultatifs vers une preuve et une extraction ; +- neuf nouveaux types système de relations utiles au pivot e-mail et bancaire. + +Le mécanisme général reste cohérent : + +- la version est stockée dans `metadata.schema_version` ; +- une base plus récente que l’application est refusée ; +- chaque migration possède une fonction dédiée ; +- chaque migration s’exécute dans une transaction ; +- la version n’est mise à jour qu’après l’application du SQL ; +- un échec provoque un rollback ; +- une base neuve reçoit V1 à V10 dans une transaction initiale ; +- `schema_current.sql` complète les structures manquantes de manière + idempotente à l’ouverture. + +Les points les plus solides sont : + +- activation explicite des clés étrangères ; +- requêtes préparées pour les valeurs variables ; +- chaîne de migration explicite jusqu’à V10 ; +- migration V9 conservatrice des types de relations ; +- création V10 testée sur une base neuve ; +- migration V1 vers V10 vérifiée ; +- tests dédiés au vocabulaire contrôlé, aux propositions bancaires et au + pipeline EML. + +Les principaux points à renforcer sont : + +- absence d’une fixture dédiée V9 → V10 avec données bancaires ; +- absence d’un test provoquant un rollback de la migration V10 ; +- absence d’un `PRAGMA foreign_key_check` générique avant chaque commit de + migration ; +- duplication de la version courante sous forme numérique et textuelle ; +- duplication partielle de la structure V10 entre `schema_v10.sql` et + `schema_current.sql` ; +- documentation générale encore fortement marquée par l’historique V1 ; +- ticket #107 encore ouvert : la présence du schéma V10 ne signifie pas que le + pivot e-mail complet est terminé. + + +--- + +# 2. Méthode et hiérarchie des sources + +L’audit applique l’ordre de confiance suivant : + +1. code présent dans la branche auditée ; +2. scripts de schéma et fonctions de migration ; +3. tests automatisés ; +4. commits associés ; +5. tickets Forgejo fermés ; +6. documentation d’architecture ; +7. anciens audits et feuilles de route. + +Cette hiérarchie est nécessaire parce qu’un document historique peut décrire +une intention ou une ancienne version sans représenter l’état courant. + +## 2.1 Sources principales examinées + +### Schémas + +- `database/schema_v1.sql` +- `database/schema_v2.sql` +- `database/schema_v3.sql` +- `database/schema_v4.sql` +- `database/schema_v5.sql` +- `database/schema_v6.sql` +- `database/schema_v7.sql` +- `database/schema_v8.sql` +- `database/schema_v9.sql` +- `database/schema_v10.sql` +- `database/schema_current.sql` + +### Infrastructure SQLite + +- `src/database/database.c` +- `src/database/schema.c` +- `src/database/statement.c` +- `src/database/transaction.c` +- `include/database/database.h` +- `include/database/schema.h` + +### Accès métier et modèles + +- contenu de `include/dao/` +- contenu de `src/dao/` +- contenu de `include/models/` +- modules liés aux preuves, entités, relations, provenance OSINT, extractions + et positions du graphe + +### Tests + +- `tests/test_database.c` +- `tests/test_statement.c` +- `tests/test_transaction.c` +- tests des DAO et services visibles dans `tests/` +- tests des types canoniques de relations + +### Documentation et tickets + +- `docs/database/DATABASE_ARCHITECTURE.md` +- `docs/database/SCHEMA_AUDIT_V1.md` +- ticket Forgejo `#106` : normalisation des types de relations +- commit `8bc3b43d63` : centralisation des types de relations + +## 2.2 Limites de l’audit + +Cet audit est une analyse statique du dépôt public. + +Il n’a pas exécuté : + +- `make -j8` ; +- la suite de tests ; +- une migration réelle sur une base synthétique ; +- `PRAGMA integrity_check` sur une base V10 produite localement ; +- `PRAGMA foreign_key_check` sur une base V10 produite localement ; +- une comparaison binaire entre une base migrée et une base fraîche. + +Les procédures de vérification reproductible sont proposées plus loin. + +--- + +# 3. Source de vérité de la version + +## 3.1 Constante courante + +La source de vérité publique se trouve dans : + +```text +src/database/database.c +``` + +avec les deux définitions : + +```c +#define DATABASE_SCHEMA_VERSION_CURRENT 10 +#define DATABASE_SCHEMA_VERSION_CURRENT_TEXT "10" +``` + +La première sert aux comparaisons numériques. + +La seconde est enregistrée dans : + +```text +metadata.schema_version +``` + +## 3.2 Lecture de la version + +La fonction : + +```c +database_read_schema_version() +``` + +effectue les contrôles suivants : + +- prépare une requête vers `metadata` ; +- lie la clé `schema_version` ; +- refuse l’absence de valeur ; +- refuse une chaîne vide ; +- convertit la valeur en entier ; +- refuse une valeur non numérique ; +- refuse une version inférieure à 1 ; +- refuse une valeur supérieure à `G_MAXINT` ; +- vérifie qu’aucune seconde ligne n’est retournée. + +## 3.3 Base plus récente que l’application + +La fonction : + +```c +database_migrate_to_latest() +``` + +refuse une base dont la version est supérieure à : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +``` + +Cela évite qu’une ancienne version de Labfy Investigation ouvre et modifie une +base créée par une version plus récente. + +## 3.4 Version inconnue ou non migrable + +La boucle de migration utilise un `switch` sur la version actuelle. + +Une version ancienne qui ne possède aucun chemin connu produit une erreur +d’état au lieu d’essayer une transformation implicite. + +## 3.5 Mise à jour de la version + +La fonction : + +```c +database_update_schema_version() +``` + +utilise une requête préparée et met à jour la clé `schema_version`. + +Dans chaque migration examinée, cette mise à jour intervient après +l’installation de la nouvelle structure et avant le `COMMIT`. + +En cas d’erreur, la transaction est annulée et la version ne doit pas avancer. + +--- + +# 4. Installation d’une base neuve + +La fonction : + +```c +database_initialize() +``` + +crée une base neuve dans une transaction initiale unique. + +L’ordre V10 observé est le suivant : + +1. ouverture de SQLite ; +2. activation de `PRAGMA foreign_keys = ON` ; +3. début de transaction ; +4. installation de V1 ; +5. installation de V2 ; +6. installation de V3 ; +7. installation de V4 ; +8. installation de V5 ; +9. installation de V6 ; +10. installation de V7 ; +11. installation de V8 ; +12. installation de V9 ; +13. installation de V10 ; +14. application de `schema_current.sql` ; +15. insertion des métadonnées, dont `schema_version = 10` ; +16. insertion de l’enquête ; +17. commit. + +Un échec provoque un rollback de l’ensemble. + +## Observation + +Une base neuve rejoue toute l’histoire du schéma. + +Cette méthode garantit qu’une base neuve et une base migrée traversent les mêmes +étapes. Elle impose cependant que chaque ancien script reste compatible avec le +moteur SQLite utilisé aujourd’hui. + +À moyen terme, un schéma de référence consolidé pourrait être envisagé pour les +bases neuves, tout en conservant les migrations historiques pour les anciennes +bases. Un tel changement exigerait une comparaison automatique entre le schéma +consolidé et le schéma obtenu par V1 → V10. + +--- + +# 5. Chaîne publique des migrations + +| Passage | Script | Fonction C | Objet principal | +|---|---|---|---| +| création | `schema_v1.sql` | `schema_install_v1()` | socle métier complet | +| V1 → V2 | `schema_v2.sql` | `schema_install_v2()` | renforcement des preuves | +| V2 → V3 | `schema_v3.sql` | `schema_install_v3()` | provenance OSINT | +| V3 → V4 | `schema_v4.sql` | `schema_install_v4()` | comptes sociaux | +| V4 → V5 | `schema_v5.sql` | `schema_install_v5()` | rôles des personnes | +| V5 → V6 | `schema_v6.sql` | `schema_install_v6()` | identité usurpée | +| V6 → V7 | `schema_v7.sql` | `schema_install_v7()` | extractions | +| V7 → V8 | `schema_v8.sql` | `schema_install_v8()` | viewport du graphe | +| V8 → V9 | `schema_v9.sql` + migration C | `schema_install_v9()` | types canoniques de relations | +| V9 → V10 | `schema_v10.sql` | `schema_install_v10()` | pivot e-mail et entités bancaires | +| complément | `schema_current.sql` | `schema_ensure_current()` | extensions idempotentes V10 | + +## 5.1 V1 — Socle métier + +La V1 crée notamment : + +### Métadonnées + +- `metadata` +- `investigation` + +### Classification et référentiels + +- `categories` +- `tags` +- `types_preuve` +- `types_entite` +- `types_source` +- `types_outil` + +### Collecte + +- `sources` +- `preuves` +- `recherches` + +### Connaissance + +- `entites` +- `relations` + +### Raisonnement et traçabilité + +- `hypotheses` +- `chronologie` +- `journal` + +### Tables de liaison + +- `tag_preuves` +- `tag_recherches` +- `tag_entites` +- `tag_relations` +- `tag_hypotheses` +- `tag_chronologie` +- `recherche_preuves` +- `recherche_entites` +- `preuve_entites` +- `relation_preuves` +- `recherche_relations` +- `recherche_chronologie` +- `preuve_chronologie` +- `entite_chronologie` +- `relation_chronologie` +- `hypothese_preuves` +- `hypothese_entites` +- `hypothese_relations` +- `recherche_hypotheses` + +La V1 constitue un schéma étendu, et non un simple prototype à deux tables. + +## 5.2 V2 — Renforcement des preuves + +La V2 ajoute à `preuves` : + +- `original_name` ; +- `collected_at` ; +- `source` ; +- `integrity_status`. + +Elle effectue également : + +- un backfill de `original_name` depuis `name` ; +- la création de `idx_preuves_imported_at` ; +- un trigger de validation à l’insertion ; +- un trigger de validation à la mise à jour. + +Les triggers renforcent notamment : + +- le nom original obligatoire ; +- la taille non négative ; +- le SHA-256 en minuscules sur 64 caractères ; +- la plage valide de `integrity_status`. + +## 5.3 V3 — Provenance OSINT structurée + +La V3 ajoute : + +- `osint_executions` +- `osint_execution_entities` +- `osint_execution_relations` + +La table principale conserve notamment : + +- l’outil ; +- sa version ; +- l’action ; +- la sélection d’origine ; +- la cible ; +- les arguments ; +- les dates de début et de fin ; +- le code de sortie ; +- l’état final ; +- les sorties standard et erreur brutes ; +- le SHA-256 de la sortie. + +Les tables de liaison indiquent si les entités ou relations ont été créées ou +réutilisées. + +## 5.4 V4 — Comptes sociaux + +La V4 : + +- ajoute les types TikTok, X, Telegram et compte social générique ; +- crée `comptes_sociaux`. + +Cette table est une extension spécialisée d’une entité et conserve : + +- la plateforme ; +- l’URL du profil ; +- le pseudonyme ; +- un identifiant de plateforme facultatif ; +- la première observation ; +- l’état du compte ; +- des notes. + +## 5.5 V5 — Rôles des personnes + +La V5 crée `person_roles`. + +Le rôle est limité à une liste contrôlée comprenant notamment : + +- non catégorisé ; +- escroc présumé ; +- victime ; +- témoin ; +- suspect ; +- personne liée. + +## 5.6 V6 — Identité usurpée + +La V6 reconstruit `person_roles` afin d’ajouter : + +```text +impersonated_identity +``` + +Elle : + +1. renomme la table V5 ; +2. crée la nouvelle table ; +3. recopie les données ; +4. supprime l’ancienne table ; +5. recrée l’index. + +Cette migration est sensible aux clés étrangères et doit rester couverte par un +test de migration réel. + +## 5.7 V7 — Extractions + +La V7 crée `extractions`. + +Elle conserve : + +- l’identifiant de l’extraction ; +- une preuve associée facultative ; +- le type de source ; +- l’identifiant de la source ; +- l’outil ; +- la date de création. + +La provenance est partiellement polymorphe via : + +```text +source_kind +source_id +``` + +SQLite ne peut pas imposer directement une clé étrangère vers plusieurs tables +possibles. La cohérence de `source_id` dépend donc aussi de la couche métier. + +## 5.8 V8 — État du viewport + +La V8 crée `graph_viewport`. + +La table ne peut contenir qu’une ligne : + +```text +id = 1 +``` + +Elle persiste : + +- le zoom ; +- le décalage horizontal ; +- le décalage vertical ; +- la date de mise à jour. + +Il s’agit d’un état de présentation, pas d’une donnée métier. + +## 5.9 V9 — Types canoniques de relations + +La V9 crée `relation_types` avec : + +- un identifiant entier ; +- un code métier stable facultatif ; +- un libellé canonique ; +- une clé normalisée unique ; +- une description facultative ; +- un indicateur système. + +Elle insère dix types système initiaux, dont : + +- `resolves_to` +- `aliases_to` +- `uses_name_server` +- `links_to` +- `sends` +- `uses` +- `controls` +- `owns` +- `knows` +- `redirects_to` + +La migration ne se limite pas au fichier SQL. + +La fonction : + +```c +schema_v9_migrate_relation_types() +``` + +réalise également les opérations suivantes : + +1. ajoute `relations.relation_type_id` si nécessaire ; +2. parcourt les anciennes relations dans un ordre déterministe ; +3. normalise l’ancien texte `type_relation` ; +4. recherche un type existant par code ou clé normalisée ; +5. crée un type personnalisé lorsqu’aucun type ne correspond ; +6. rattache chaque relation au type canonique ; +7. crée l’index d’unicité canonique ; +8. crée l’index sur `relation_type_id` ; +9. crée des triggers interdisant un type canonique nul ; +10. exécute `PRAGMA foreign_key_check`. + +La colonne historique : + +```text +relations.type_relation +``` + +reste présente pour compatibilité. + +Depuis V9, l’identité logique du type doit être : + +```text +relations.relation_type_id +``` + +et non le texte historique. + + + +## 5.10 V10 — Pivot e-mail et entités bancaires + +La V10 crée : + +```text +bank_account_entities +``` + +Cette table conserve : + +- un UUID métier ; +- l’IBAN normalisé ; +- le BIC facultatif ; +- le nom du titulaire ; +- le nom et l’adresse de la banque ; +- le code pays ; +- le code banque ; +- le code guichet ; +- le numéro de compte ; +- la clé RIB ; +- le statut de vérification ; +- le type de provenance ; +- une preuve source facultative ; +- une extraction source facultative ; +- les dates de création et de mise à jour. + +Les statuts autorisés sont : + +```text +proposed +confirmed +rejected +conflicted +invalid +``` + +Les provenances autorisées sont : + +```text +observed +ocr +header +metadata +derived +manual +``` + +Les références vers `preuves` et `extractions` utilisent `ON DELETE SET NULL`. +La disparition d’un objet source ne supprime donc pas automatiquement la donnée +bancaire structurée. + +La V10 ajoute également les index : + +```text +idx_bank_account_entities_iban +idx_bank_account_entities_evidence +``` + +Elle insère neuf types système de relations : + +```text +sent_from +sent_to +reply_to +has_attachment +relayed_by +uses_domain +held_at +named_as_holder_of +supports +``` + +Ces codes techniques sont destinés à rester stables, tandis que les libellés +français peuvent évoluer indépendamment. + +### Migration V9 vers V10 + +La fonction : + +```c +database_migrate_v9_to_v10() +``` + +exécute atomiquement : + +1. `database_transaction_begin()` ; +2. `schema_install_v10()` ; +3. `database_update_schema_version(database, "10")` ; +4. `database_transaction_commit()`. + +En cas d’échec, elle appelle `database_transaction_rollback()`. + +### Portée fonctionnelle + +La présence du schéma V10 ne signifie pas que l’ensemble du ticket #107 est +terminé. + +Le ticket reste ouvert et couvre un périmètre beaucoup plus large : + +- analyse complète des en-têtes EML ; +- extraction MIME sécurisée ; +- OCR ; +- métadonnées ExifTool ; +- interface de révision ; +- intégration transactionnelle des propositions confirmées ; +- création ou réutilisation d’entités et de relations ; +- conservation complète de la provenance. + +La V10 constitue donc un socle persistant du pivot e-mail, pas la preuve de +l’achèvement de tout le flux fonctionnel. +--- + +# 6. Rôle de `schema_current.sql` + +`schema_current.sql` est présenté comme un ensemble d’extensions idempotentes +du schéma courant V10. + +Il crée si nécessaire : + +- `graph_node_positions` +- `extractions` +- `graph_layout_positions` +- `graph_viewport` +- `relation_types` +- `bank_account_entities` + +Il réinsère également, avec `INSERT OR IGNORE`, les types système de relations +ajoutés par V10. + +Il ajoute également deux triggers nettoyant les positions de graphe orphelines +après suppression d’une entité ou d’une relation. + +## 6.1 Migration des positions + +Le script copie les anciennes positions : + +```sql +INSERT OR IGNORE INTO graph_layout_positions (...) +SELECT ... FROM graph_node_positions; +``` + +puis exécute : + +```sql +DELETE FROM graph_node_positions; +``` + +L’objectif est de migrer l’ancien état limité aux entités vers une disposition +générique acceptant aussi les relations. + +## 6.2 Point d’attention + +Le script est exécuté après les migrations lors de l’ouverture. + +Il contient donc à la fois : + +- des créations idempotentes ; +- une migration de données de présentation ; +- une suppression des anciennes lignes. + +Le comportement peut être légitime, mais il doit être explicitement couvert par +des tests vérifiant plusieurs exécutions successives afin de garantir : + +- l’absence de perte de positions courantes ; +- l’absence de réimport d’anciennes coordonnées ; +- la stabilité après plusieurs ouvertures ; +- le nettoyage correct des positions orphelines. + +--- + +# 7. Inventaire statique du schéma V10 + +L’application statique des scripts versionnés et de `schema_current.sql` produit **46 tables distinctes**. + +Ce nombre est dérivé des scripts, et doit être confirmé sur une base générée par +une requête sur `sqlite_master`. + +## 7.1 Métadonnées + +| Table | Rôle | +|---|---| +| `metadata` | version et informations techniques | +| `investigation` | enquête unique contenue dans la base | + +## 7.2 Référentiels et classification + +| Table | Rôle | +|---|---| +| `categories` | classement principal | +| `tags` | annotations multiples | +| `types_preuve` | types de preuves | +| `types_entite` | types d’entités | +| `types_source` | types de sources | +| `types_outil` | types d’outils | +| `relation_types` | types canoniques de relations | + +## 7.3 Données métier principales + +| Table | Rôle | +|---|---| +| `sources` | origine d’une information | +| `preuves` | métadonnées des fichiers collectés | +| `recherches` | actions d’investigation | +| `entites` | objets identifiés | +| `relations` | liens orientés entre entités | +| `hypotheses` | raisonnements provisoires | +| `chronologie` | événements de l’enquête | +| `journal` | journal technique | + +## 7.4 Extensions spécialisées + +| Table | Version | Rôle | +|---|---:|---| +| `osint_executions` | V3 | provenance des traitements OSINT | +| `osint_execution_entities` | V3 | entités créées ou réutilisées | +| `osint_execution_relations` | V3 | relations créées ou réutilisées | +| `comptes_sociaux` | V4 | données propres aux comptes sociaux | +| `person_roles` | V5/V6 | rôle d’enquête d’une personne | +| `extractions` | V7 | provenance d’une extraction | +| `graph_viewport` | V8 | zoom et position du canevas | +| `graph_node_positions` | courant | ancien stockage des positions d’entités | +| `graph_layout_positions` | courant | positions génériques entités/relations | +| `bank_account_entities` | V10 | données bancaires structurées et vérifiables | + +## 7.5 Tables de liaison V1 + +| Domaine | Tables | +|---|---| +| tags | `tag_preuves`, `tag_recherches`, `tag_entites`, `tag_relations`, `tag_hypotheses`, `tag_chronologie` | +| recherches | `recherche_preuves`, `recherche_entites`, `recherche_relations`, `recherche_chronologie`, `recherche_hypotheses` | +| preuves | `preuve_entites`, `preuve_chronologie`, `relation_preuves` | +| chronologie | `entite_chronologie`, `relation_chronologie` | +| hypothèses | `hypothese_preuves`, `hypothese_entites`, `hypothese_relations` | + +--- + +# 8. Intégrité et sécurité des données + +## 8.1 Clés étrangères + +`database_open()` exécute : + +```sql +PRAGMA foreign_keys = ON; +``` + +Les stratégies observées sont : + +- `CASCADE` pour les objets strictement dépendants ; +- `RESTRICT` lorsque la suppression risquerait de casser l’historique ; +- `SET NULL` pour les références facultatives. + +## 8.2 Requêtes préparées + +Les valeurs variables de la couche Database et des DAO utilisent les fonctions +de préparation et de liaison. + +Les requêtes statiques sans donnée utilisateur peuvent être exécutées avec +`sqlite3_exec()`. + +La règle à conserver est : + +> aucune valeur externe ou utilisateur ne doit être concaténée dans une chaîne +> SQL. + +Le caractère append-only du journal ne constitue jamais une exception à cette +règle. + +## 8.3 Transactions + +Les migrations V1 à V10 sont pilotées par des fonctions dédiées. + +Chaque passage de version : + +- démarre une transaction ; +- applique le changement ; +- met à jour la version ; +- commit en cas de succès ; +- rollback en cas d’échec. + +La création d’une base neuve est également atomique. + +## 8.4 Preuves + +Le schéma et la couche métier conservent notamment : + +- UUID ; +- chemin relatif ; +- nom interne ; +- nom original ; +- taille ; +- SHA-256 ; +- type MIME ; +- date du fichier ; +- date de collecte ; +- date d’import ; +- statut d’intégrité ; +- statut logique. + +Le fichier original reste dans l’arborescence de l’enquête. SQLite conserve ses +métadonnées et ses relations. + +## 8.5 Suppression logique + +Plusieurs objets V1 utilisent des statuts tels que : + +```text +active +archived +deleted +``` + +Certaines suppressions physiques existent néanmoins dans les DAO, notamment +pour les relations. + +Le document d’architecture doit donc éviter d’affirmer que toute suppression +est systématiquement logique. La stratégie réelle doit être documentée table +par table. + +## 8.6 Journal et chronologie + +Le schéma distingue : + +- `chronologie` : événements significatifs de l’enquête ; +- `journal` : trace technique des actions de l’application. + +Le journal est conçu comme append-only dans la documentation, mais cet audit +n’a pas identifié de trigger SQLite interdisant une mise à jour ou une +suppression. Cette propriété repose donc actuellement au moins en partie sur la +couche applicative. + +--- + +# 9. Correspondance SQL, modèles, DAO et tests + +| Domaine | Table principale | Modèle ou structure | DAO/service observé | Tests observés | +|---|---|---|---|---| +| enquête | `investigation` | `InvestigationRecord` | `InvestigationDao` | `test_investigation_record`, `test_investigation_dao` | +| preuves | `preuves` | `EvidenceRecord` | `EvidenceDao`, `EvidenceTypeDao` | nombreux tests preuve/import/intégrité | +| preuve-entité | `preuve_entites` | — | `EvidenceEntityDao` | `test_evidence_entity_dao` | +| entités | `entites` | `EntityRecord` | `EntityDao`, `EntityTypeDao` | tests modèle et DAO | +| relations | `relations` | `RelationRecord` | `RelationDao`, `RelationService` | tests DAO, modèle et service | +| types de relation | `relation_types` | `RelationType` | `RelationTypeDao`, `RelationTypeService` | normalisation et service | +| relation-preuve | `relation_preuves` | — | `RelationEvidenceDao` | `test_relation_evidence_dao` | +| provenance OSINT | `osint_executions` | `OsintExecutionRecord` | `OsintExecutionDao` | DAO et intégrité | +| extractions | `extractions` | contexte métier | `ExtractionDao`, service de dépôt | `test_extraction_drop_service` | +| positions graphe | tables de graphe | `GraphNodePosition`, layout | `GraphNodePositionDao` | `test_graph_node_position_dao` | +| comptes sociaux | `comptes_sociaux` | plateforme sociale | service compte social | `test_social_account_service` | +| personnes | `person_roles` | extension d’entité | service personne | `test_person_entity_service` | +| comptes bancaires | `bank_account_entities` | `BankProposal` | pipeline EML et analyse bancaire ; DAO dédié non identifié dans les fichiers inspectés | `test_bank_proposal`, `test_eml_pipeline_task`, présence de table dans `test_database` | + +## Observation + +La V1 contient davantage de domaines que les DAO publics actuellement exposés. + +Aucun DAO dédié n’a été observé dans `include/dao/` pour plusieurs tables, dont : + +- `sources` ; +- `recherches` ; +- `hypotheses` ; +- `chronologie` ; +- `journal` ; +- `categories` ; +- `tags`. + +Cela ne signifie pas que ces tables sont inutilisables. Cela indique seulement +qu’aucune interface DAO publique dédiée n’est visible dans le dossier audité au +commit indiqué. + +--- + +# 10. Couverture de tests observée + +## 10.1 Points couverts par `test_database.c` + +Le fichier vérifie notamment : + +- l’initialisation d’une base valide ; +- le rollback d’une initialisation défaillante ; +- la présence de la version `10` dans une base neuve ; +- la présence de `bank_account_entities` ; +- la présence de plusieurs tables ajoutées après V1 ; +- la migration d’une base V1 vers la version courante V10 ; +- la conservation d’une preuve V1 ; +- le backfill V2 de `original_name` ; +- l’ajout des colonnes V2 ; +- l’ajout des triggers V2 ; +- le rollback complet d’une migration V2 provoquée en échec ; +- `PRAGMA integrity_check` après le rollback. + +## 10.2 Tests spécialisés observés + +Le dépôt possède également des tests pour : + +- les preuves et leur intégrité ; +- les entités ; +- les relations ; +- les types canoniques de relations ; +- les exécutions OSINT ; +- les extractions ; +- les positions du graphe ; +- les comptes sociaux ; +- les rôles des personnes ; +- le vocabulaire contrôlé ; +- l’analyse et la validation des propositions IBAN/BIC ; +- le pipeline EML asynchrone. + +## 10.3 Lacunes de couverture à traiter + +Le test principal de migration ne fournit pas une fixture indépendante pour +chaque version V2 à V10. + +Aucun test dédié nommé V9 → V10 n’a été identifié dans `test_database.c`. +La création d’une base neuve vérifie bien la présence de la table V10, et la +fixture V1 atteint bien la version 10, mais cela ne remplace pas une migration +V9 réaliste contenant des relations, extractions, preuves et données bancaires. + +Matrice recommandée : + +| Base d’entrée | Migration | Vérifications minimales | +|---|---|---| +| V1 | V1 → V10 | données, version, FK, intégrité | +| V2 | V2 → V10 | preuve V2 conservée | +| V3 | V3 → V10 | provenance OSINT conservée | +| V4 | V4 → V10 | comptes sociaux conservés | +| V5 | V5 → V10 | rôles conservés pendant reconstruction V6 | +| V6 | V6 → V10 | identité usurpée conservée | +| V7 | V7 → V10 | extractions conservées | +| V8 | V8 → V10 | viewport et positions conservés | +| V9 | V9 → V10 | relations canoniques conservées, table bancaire créée | +| V10 | réouverture | idempotence de `schema_current.sql` | + +Chaque fixture devrait vérifier au minimum : + +```sql +PRAGMA integrity_check; +PRAGMA foreign_key_check; +SELECT value FROM metadata WHERE key = 'schema_version'; +``` + +--- + +# 11. Constats d’audit + +## AUD-001 — Documentation courante restée en V1 + +**Sévérité : élevée** + +`docs/database/DATABASE_ARCHITECTURE.md` s’annonce encore comme : + +```text +Statut : Stable (V1) +Schéma : V1 +``` + +alors que le code utilise V10. + +### Risque + +- confusion des développeurs ; +- erreurs des agents locaux ; +- mauvaise interprétation de l’état du projet ; +- décisions basées sur des structures historiques ; +- oubli des tables V2 à V10. + +### Action recommandée + +Créer : + +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` + +et déplacer les audits historiques vers : + +```text +docs/database/audits/SCHEMA_AUDIT_V1.md +docs/database/audits/SCHEMA_AUDIT_V9.md +``` + +Le document courant doit indiquer le commit exact qu’il audite. + +--- + +## AUD-002 — Couverture spécifique V9 → V10 insuffisante + +**Sévérité : élevée** + +La V10 est bien publiée et installée par le code. Les tests confirment : + +- une base neuve en version 10 ; +- la présence de `bank_account_entities` ; +- une migration V1 atteignant la version 10. + +Aucune fixture dédiée V9 → V10 n’a toutefois été identifiée. + +### Risque + +Une régression propre au passage V9 → V10 pourrait ne pas être détectée, +notamment sur : + +- les relations canoniques V9 ; +- les références vers `preuves` et `extractions` ; +- l’idempotence des nouveaux types de relations ; +- le rollback après création partielle de la table bancaire. + +### Action recommandée + +Ajouter un test synthétique V9 → V10 qui vérifie : + +1. la conservation des objets V9 ; +2. la création de `bank_account_entities` ; +3. l’unicité des types de relations insérés ; +4. `PRAGMA integrity_check` ; +5. `PRAGMA foreign_key_check` ; +6. le rollback complet d’une migration V10 volontairement mise en échec. + +--- + +## AUD-003 — Version courante dupliquée + +**Sévérité : moyenne** + +La version est définie deux fois : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +DATABASE_SCHEMA_VERSION_CURRENT_TEXT +``` + +Les tests comparent aussi directement la chaîne `"10"`. + +### Risque + +Une future migration peut modifier une valeur et oublier l’autre. + +### Action recommandée + +Conserver une seule constante numérique et produire la représentation textuelle +au moment de l’écriture, ou centraliser les deux valeurs dans un fichier +d’interface unique couvert par une assertion de test. + +--- + +## AUD-004 — `schema_current.sql` mélange plusieurs responsabilités + +**Sévérité : moyenne** + +Le fichier sert à la fois à : + +- créer des structures manquantes ; +- maintenir la compatibilité ; +- migrer des positions ; +- supprimer les anciennes positions ; +- installer des triggers ; +- recréer la table bancaire V10 si elle manque ; +- réinsérer les types système du pivot e-mail. + +### Risque + +Une opération supposée idempotente peut finir par modifier des données à chaque +ouverture. + +### Action recommandée + +Documenter chaque opération et ajouter un test exécutant +`schema_ensure_current()` plusieurs fois sur la même fixture. + +--- + +## AUD-005 — Contrôle des clés étrangères non généralisé + +**Sévérité : moyenne** + +La migration V9 exécute explicitement : + +```sql +PRAGMA foreign_key_check; +``` + +Aucun contrôle générique similaire n’a été observé dans le pilote commun de +toutes les migrations. + +### Action recommandée + +Exécuter un contrôle générique avant le commit de chaque migration, ou fournir +une justification documentée lorsqu’une migration ne le nécessite pas. + +--- + +## AUD-006 — Couverture de migration incomplète par version + +**Sévérité : élevée** + +Le test principal couvre : + +- création d’une base neuve ; +- migration V1 vers la version courante ; +- rollback V2. + +Il ne constitue pas une matrice complète de fixtures V2 à V10. + +### Action recommandée + +Ajouter une fixture synthétique minimale pour chaque version publiée et migrer +chacune vers la version courante. + +--- + +## AUD-007 — Absence de sauvegarde préalable observée + +**Sévérité : élevée pour des enquêtes réelles** + +Aucun appel de sauvegarde SQLite ou copie préalable n’a été observé dans +`database_migrate_to_latest()`. + +La transaction protège la cohérence logique, mais elle ne remplace pas une +copie de sécurité face à : + +- panne disque ; +- interruption brutale ; +- défaut SQLite ou système de fichiers ; +- erreur de migration non anticipée ; +- corruption déjà présente. + +### Action recommandée + +Avant toute migration d’une base existante : + +1. fermer ou stabiliser les accès concurrents ; +2. créer une sauvegarde cohérente ; +3. vérifier sa création ; +4. lancer la migration ; +5. conserver la sauvegarde tant que la validation n’est pas terminée. + +Cette fonctionnalité doit être testée uniquement sur des bases synthétiques. + +--- + +## AUD-008 — Ancienne et nouvelle identité du type de relation coexistent + +**Sévérité : moyenne** + +V9 conserve : + +```text +relations.type_relation +``` + +et ajoute : + +```text +relations.relation_type_id +``` + +La documentation du commit précise que la première colonne ne doit plus servir +d’identité. + +### Risque + +Un module ancien peut encore filtrer ou détecter les doublons par texte. + +### Action recommandée + +Auditer tous les producteurs et lecteurs de relations, puis ajouter un test +interdisant toute régression vers `type_relation` comme clé métier. + +La colonne historique pourra être supprimée dans une future migration seulement +après validation de toutes les anciennes bases et de tous les adaptateurs. + +--- + +## AUD-009 — Append-only non imposé par SQLite + +**Sévérité : faible à moyenne** + +Le journal est documenté comme append-only, mais aucun trigger interdisant +`UPDATE` ou `DELETE` n’a été identifié dans les scripts examinés. + +### Action recommandée + +Choisir explicitement l’une des deux politiques : + +- garantie applicative documentée et testée ; +- garantie SQLite par triggers de refus. + +Le document courant doit dire laquelle est réellement retenue. + +--- + +## AUD-010 — Paramètres SQLite de durabilité non documentés dans le code audité + +**Sévérité : à évaluer** + +Aucun réglage explicite n’a été identifié dans `database.c` pour : + +- `journal_mode` ; +- `synchronous` ; +- `busy_timeout`. + +SQLite applique donc probablement ses valeurs par défaut, sauf réglage réalisé +ailleurs. + +### Action recommandée + +Documenter volontairement les paramètres retenus et leurs conséquences avant +un usage opérationnel. + +Ne pas activer WAL ou modifier `synchronous` sans étudier la portabilité d’une +enquête et les procédures de copie de ses fichiers annexes. + +--- + +# 12. État de validation de la V10 + +## 12.1 Implémentation confirmée + +Les éléments suivants sont présents au commit audité : + +- `database/schema_v10.sql` ; +- déclaration de `schema_install_v10()` ; +- implémentation de `schema_install_v10()` ; +- `database_migrate_v9_to_v10()` ; +- cas `9` dans `database_migrate_to_latest()` ; +- installation V10 dans `database_initialize()` ; +- version numérique `10` ; +- version textuelle `"10"` ; +- table `bank_account_entities` ; +- index IBAN et preuve ; +- nouveaux types système de relations ; +- mise à jour de `schema_current.sql` ; +- mise à jour de `test_database.c`. + +## 12.2 Validation partielle confirmée + +Les tests présents couvrent : + +- la création d’une base neuve V10 ; +- la présence de `bank_account_entities` ; +- l’arrivée d’une ancienne base V1 en version 10 ; +- le vocabulaire contrôlé ; +- l’analyse de propositions bancaires ; +- un scénario de pipeline EML. + +## 12.3 Validation encore recommandée + +Restent à ajouter ou confirmer : + +- fixture directe V9 → V10 ; +- rollback provoqué de la migration V10 ; +- conservation de données V9 riches ; +- vérification des deux clés étrangères de `bank_account_entities` ; +- contrôle de doublon des types système après ouvertures répétées ; +- `PRAGMA foreign_key_check` avant validation de V10 ; +- DAO ou service de persistance clairement identifié pour + `bank_account_entities` ; +- test de réouverture multiple de `schema_current.sql` ; +- validation complète des critères du ticket #107. + +## 12.4 Statut fonctionnel + +Le **schéma V10 est implémenté**. + +Le **pivot e-mail complet n’est pas déclaré terminé** : le ticket #107 est +toujours ouvert et couvre un périmètre supérieur à la seule migration SQLite. + +--- + +# 13. Procédure de vérification reproductible + +> Utiliser uniquement une copie synthétique. +> Ne jamais exécuter cette procédure sur une base d’enquête réelle sans +> sauvegarde et validation préalable. + +## 13.1 Compilation + +```bash +make clean +make -j8 +make -j8 test +git diff --check +``` + +En cas d’échec provoqué par la parallélisation, revenir temporairement à : + +```bash +make +make test +``` + +## 13.2 Création d’une base synthétique + +Créer une enquête de test par l’API normale de l’application ou par un test +dédié, puis vérifier : + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT value FROM metadata WHERE key = 'schema_version';" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA integrity_check;" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA foreign_key_check;" +``` + +Résultats attendus : + +```text + +ok + +``` + +## 13.3 Inventaire du schéma + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT type, name + FROM sqlite_master + WHERE name NOT LIKE 'sqlite_%' + ORDER BY type, name;" +``` + +## 13.4 Vérification de l’idempotence + +1. ouvrir la base ; +2. fermer la base ; +3. enregistrer un dump du schéma et les données de présentation ; +4. rouvrir la base plusieurs fois ; +5. comparer les résultats ; +6. vérifier les positions du graphe ; +7. vérifier les types de relations ; +8. exécuter à nouveau les deux PRAGMA d’intégrité. + +## 13.5 Vérification de migration + +Pour chaque fixture V1 à V10 : + +1. calculer une copie de travail ; +2. relever la version initiale ; +3. compter les objets métier ; +4. migrer ; +5. vérifier la version finale ; +6. comparer les UUID ; +7. comparer les empreintes des preuves ; +8. comparer les liaisons ; +9. vérifier les contraintes ; +10. vérifier le rollback sur une copie volontairement invalide. + +--- + +# 14. Règle de maintenance proposée + +Toute nouvelle version du schéma doit livrer ensemble : + +```text +migration SQL ++ fonction d’installation ++ fonction de migration ++ incrément de version ++ tests de base neuve ++ tests d’ancienne base ++ test de rollback ++ contrôle d’intégrité ++ mise à jour de SCHEMA_AUDIT_CURRENT.md ++ ticket Forgejo ++ commit vérifiable +``` + +Un ticket de migration ne doit pas être fermé tant que cette chaîne n’est pas +complète. + +## Statuts documentaires obligatoires + +Chaque table, colonne ou fonctionnalité mentionnée dans la documentation devrait +porter l’un des statuts suivants : + +```text +IMPLÉMENTÉ +PARTIELLEMENT IMPLÉMENTÉ +DOCUMENTÉ MAIS NON IMPLÉMENTÉ +HISTORIQUE +ABANDONNÉ +``` + +Cette règle évitera de confondre : + +- une architecture cible ; +- un ancien audit ; +- une fonctionnalité réellement présente ; +- un ticket encore ouvert ; +- une migration locale non publiée. + +--- + +# 15. Conclusion + +Le schéma V10 repose sur une base technique sérieuse : + +- modèle relationnel riche ; +- versionnement explicite ; +- migrations transactionnelles ; +- provenance OSINT ; +- contraintes sur les preuves ; +- normalisation des types de relations ; +- séparation des données métier et de l’état du graphe ; +- table bancaire structurée avec provenance et statut contrôlés ; +- tests dédiés aux nouveaux composants EML et bancaires. + +La V10 est bien publiée et détectable par le code comme version courante. + +Le principal risque documentaire reste l’écart entre : + +- l’ancienne documentation V1 ; +- le schéma courant V10 ; +- les fonctionnalités partielles déjà présentes ; +- le ticket #107, qui décrit encore un flux complet en cours de réalisation. + +`SCHEMA_AUDIT_V1.md` et `SCHEMA_AUDIT_V9.md` doivent rester des documents +historiques. Le présent fichier doit devenir la référence courante jusqu’à la +prochaine migration. + +Les prochaines actions recommandées sont : + +1. ajouter une fixture V9 → V10 ; +2. tester le rollback V10 ; +3. exécuter `integrity_check` et `foreign_key_check` sur une base synthétique ; +4. clarifier le service responsable de la persistance bancaire ; +5. maintenir ce document à chaque nouvelle version ; +6. ne fermer le ticket #107 qu’après validation de son flux fonctionnel complet. + +--- + +# 16. Références du dépôt + +## Commit audité + +```text +613d2096bc5eeb2c1c4f60ae701292e19a2abe66 +feat(relations): centraliser les types et améliorer les aperçus +Date : 2026-07-24 12:53:31 +02:00 +``` + +Le commit contient notamment : + +```text +28 fichiers modifiés +1826 ajouts +18 suppressions +``` + +## Tickets Forgejo liés + +```text +#107 — Ajouter un pivot e-mail forensique avec OCR, métadonnées et + normalisation des données +État : ouvert +``` + +```text +#106 — Normaliser et centraliser les types de relations +État : fermé +``` + +## Documents historiques + +```text +docs/database/DATABASE_ARCHITECTURE.md +docs/database/SCHEMA_AUDIT_V1.md +docs/database/audits/SCHEMA_AUDIT_V9.md +``` + +## Fichiers constituant la source de vérité technique V10 + +```text +database/schema_v1.sql +database/schema_v2.sql +database/schema_v3.sql +database/schema_v4.sql +database/schema_v5.sql +database/schema_v6.sql +database/schema_v7.sql +database/schema_v8.sql +database/schema_v9.sql +database/schema_v10.sql +database/schema_current.sql + +src/database/database.c +src/database/schema.c +src/database/statement.c +src/database/transaction.c + +include/database/database.h +include/database/schema.h + +include/core/bank_proposal.h +include/core/controlled_vocab.h +include/core/eml_mime_extractor.h +include/core/eml_pipeline_task.h + +tests/test_database.c +tests/test_statement.c +tests/test_transaction.c +tests/test_bank_proposal.c +tests/test_controlled_vocab.c +tests/test_eml_pipeline_task.c +``` diff --git a/docs/database/SCHEMA_AUDIT_V1.md b/docs/database/audits/SCHEMA_AUDIT_V1.md similarity index 100% rename from docs/database/SCHEMA_AUDIT_V1.md rename to docs/database/audits/SCHEMA_AUDIT_V1.md diff --git a/docs/database/audits/SCHEMA_AUDIT_V10.md b/docs/database/audits/SCHEMA_AUDIT_V10.md new file mode 100644 index 0000000..56bac8d --- /dev/null +++ b/docs/database/audits/SCHEMA_AUDIT_V10.md @@ -0,0 +1,1581 @@ +# Audit du schéma SQLite courant — V10 + +> [!IMPORTANT] +> Ce document décrit le schéma réellement présent sur la branche `main` au +> commit `613d2096bc5eeb2c1c4f60ae701292e19a2abe66`. +> +> Il distingue l’implémentation SQLite V10 du chantier fonctionnel plus large +> du pivot e-mail suivi dans le ticket Forgejo #107, qui reste ouvert. + +> **Projet :** Labfy Investigation +> **Date de l’audit :** 2026-07-24 +> **Branche auditée :** `main` publique sur Forgejo +> **Commit audité :** `613d2096bc5eeb2c1c4f60ae701292e19a2abe66` +> **Version de schéma confirmée par le code :** **V10** +> **Statut du document :** audit courant vérifié de la V10 +> **Périmètre :** schémas SQL, mécanisme de migration, couche Database, tests, +> documentation et tickets Forgejo associés + +--- + +# 1. Résumé exécutif + +Le schéma SQLite courant de Labfy Investigation est la **V10**. + +Cette conclusion est confirmée conjointement par : + +- `DATABASE_SCHEMA_VERSION_CURRENT 10` ; +- `DATABASE_SCHEMA_VERSION_CURRENT_TEXT "10"` ; +- `database/schema_v10.sql` ; +- `schema_install_v10()` ; +- `database_migrate_v9_to_v10()` ; +- le cas `9` de `database_migrate_to_latest()` ; +- l’installation de V10 dans `database_initialize()` ; +- les assertions V10 de `tests/test_database.c`. + +La V10 ajoute principalement : + +- la table `bank_account_entities` ; +- la conservation structurée des données IBAN, BIC et RIB ; +- un statut de vérification contrôlé ; +- une provenance contrôlée ; +- des liens facultatifs vers une preuve et une extraction ; +- neuf nouveaux types système de relations utiles au pivot e-mail et bancaire. + +Le mécanisme général reste cohérent : + +- la version est stockée dans `metadata.schema_version` ; +- une base plus récente que l’application est refusée ; +- chaque migration possède une fonction dédiée ; +- chaque migration s’exécute dans une transaction ; +- la version n’est mise à jour qu’après l’application du SQL ; +- un échec provoque un rollback ; +- une base neuve reçoit V1 à V10 dans une transaction initiale ; +- `schema_current.sql` complète les structures manquantes de manière + idempotente à l’ouverture. + +Les points les plus solides sont : + +- activation explicite des clés étrangères ; +- requêtes préparées pour les valeurs variables ; +- chaîne de migration explicite jusqu’à V10 ; +- migration V9 conservatrice des types de relations ; +- création V10 testée sur une base neuve ; +- migration V1 vers V10 vérifiée ; +- tests dédiés au vocabulaire contrôlé, aux propositions bancaires et au + pipeline EML. + +Les principaux points à renforcer sont : + +- absence d’une fixture dédiée V9 → V10 avec données bancaires ; +- absence d’un test provoquant un rollback de la migration V10 ; +- absence d’un `PRAGMA foreign_key_check` générique avant chaque commit de + migration ; +- duplication de la version courante sous forme numérique et textuelle ; +- duplication partielle de la structure V10 entre `schema_v10.sql` et + `schema_current.sql` ; +- documentation générale encore fortement marquée par l’historique V1 ; +- ticket #107 encore ouvert : la présence du schéma V10 ne signifie pas que le + pivot e-mail complet est terminé. + + +--- + +# 2. Méthode et hiérarchie des sources + +L’audit applique l’ordre de confiance suivant : + +1. code présent dans la branche auditée ; +2. scripts de schéma et fonctions de migration ; +3. tests automatisés ; +4. commits associés ; +5. tickets Forgejo fermés ; +6. documentation d’architecture ; +7. anciens audits et feuilles de route. + +Cette hiérarchie est nécessaire parce qu’un document historique peut décrire +une intention ou une ancienne version sans représenter l’état courant. + +## 2.1 Sources principales examinées + +### Schémas + +- `database/schema_v1.sql` +- `database/schema_v2.sql` +- `database/schema_v3.sql` +- `database/schema_v4.sql` +- `database/schema_v5.sql` +- `database/schema_v6.sql` +- `database/schema_v7.sql` +- `database/schema_v8.sql` +- `database/schema_v9.sql` +- `database/schema_v10.sql` +- `database/schema_current.sql` + +### Infrastructure SQLite + +- `src/database/database.c` +- `src/database/schema.c` +- `src/database/statement.c` +- `src/database/transaction.c` +- `include/database/database.h` +- `include/database/schema.h` + +### Accès métier et modèles + +- contenu de `include/dao/` +- contenu de `src/dao/` +- contenu de `include/models/` +- modules liés aux preuves, entités, relations, provenance OSINT, extractions + et positions du graphe + +### Tests + +- `tests/test_database.c` +- `tests/test_statement.c` +- `tests/test_transaction.c` +- tests des DAO et services visibles dans `tests/` +- tests des types canoniques de relations + +### Documentation et tickets + +- `docs/database/DATABASE_ARCHITECTURE.md` +- `docs/database/SCHEMA_AUDIT_V1.md` +- ticket Forgejo `#106` : normalisation des types de relations +- commit `8bc3b43d63` : centralisation des types de relations + +## 2.2 Limites de l’audit + +Cet audit est une analyse statique du dépôt public. + +Il n’a pas exécuté : + +- `make -j8` ; +- la suite de tests ; +- une migration réelle sur une base synthétique ; +- `PRAGMA integrity_check` sur une base V10 produite localement ; +- `PRAGMA foreign_key_check` sur une base V10 produite localement ; +- une comparaison binaire entre une base migrée et une base fraîche. + +Les procédures de vérification reproductible sont proposées plus loin. + +--- + +# 3. Source de vérité de la version + +## 3.1 Constante courante + +La source de vérité publique se trouve dans : + +```text +src/database/database.c +``` + +avec les deux définitions : + +```c +#define DATABASE_SCHEMA_VERSION_CURRENT 10 +#define DATABASE_SCHEMA_VERSION_CURRENT_TEXT "10" +``` + +La première sert aux comparaisons numériques. + +La seconde est enregistrée dans : + +```text +metadata.schema_version +``` + +## 3.2 Lecture de la version + +La fonction : + +```c +database_read_schema_version() +``` + +effectue les contrôles suivants : + +- prépare une requête vers `metadata` ; +- lie la clé `schema_version` ; +- refuse l’absence de valeur ; +- refuse une chaîne vide ; +- convertit la valeur en entier ; +- refuse une valeur non numérique ; +- refuse une version inférieure à 1 ; +- refuse une valeur supérieure à `G_MAXINT` ; +- vérifie qu’aucune seconde ligne n’est retournée. + +## 3.3 Base plus récente que l’application + +La fonction : + +```c +database_migrate_to_latest() +``` + +refuse une base dont la version est supérieure à : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +``` + +Cela évite qu’une ancienne version de Labfy Investigation ouvre et modifie une +base créée par une version plus récente. + +## 3.4 Version inconnue ou non migrable + +La boucle de migration utilise un `switch` sur la version actuelle. + +Une version ancienne qui ne possède aucun chemin connu produit une erreur +d’état au lieu d’essayer une transformation implicite. + +## 3.5 Mise à jour de la version + +La fonction : + +```c +database_update_schema_version() +``` + +utilise une requête préparée et met à jour la clé `schema_version`. + +Dans chaque migration examinée, cette mise à jour intervient après +l’installation de la nouvelle structure et avant le `COMMIT`. + +En cas d’erreur, la transaction est annulée et la version ne doit pas avancer. + +--- + +# 4. Installation d’une base neuve + +La fonction : + +```c +database_initialize() +``` + +crée une base neuve dans une transaction initiale unique. + +L’ordre V10 observé est le suivant : + +1. ouverture de SQLite ; +2. activation de `PRAGMA foreign_keys = ON` ; +3. début de transaction ; +4. installation de V1 ; +5. installation de V2 ; +6. installation de V3 ; +7. installation de V4 ; +8. installation de V5 ; +9. installation de V6 ; +10. installation de V7 ; +11. installation de V8 ; +12. installation de V9 ; +13. installation de V10 ; +14. application de `schema_current.sql` ; +15. insertion des métadonnées, dont `schema_version = 10` ; +16. insertion de l’enquête ; +17. commit. + +Un échec provoque un rollback de l’ensemble. + +## Observation + +Une base neuve rejoue toute l’histoire du schéma. + +Cette méthode garantit qu’une base neuve et une base migrée traversent les mêmes +étapes. Elle impose cependant que chaque ancien script reste compatible avec le +moteur SQLite utilisé aujourd’hui. + +À moyen terme, un schéma de référence consolidé pourrait être envisagé pour les +bases neuves, tout en conservant les migrations historiques pour les anciennes +bases. Un tel changement exigerait une comparaison automatique entre le schéma +consolidé et le schéma obtenu par V1 → V10. + +--- + +# 5. Chaîne publique des migrations + +| Passage | Script | Fonction C | Objet principal | +|---|---|---|---| +| création | `schema_v1.sql` | `schema_install_v1()` | socle métier complet | +| V1 → V2 | `schema_v2.sql` | `schema_install_v2()` | renforcement des preuves | +| V2 → V3 | `schema_v3.sql` | `schema_install_v3()` | provenance OSINT | +| V3 → V4 | `schema_v4.sql` | `schema_install_v4()` | comptes sociaux | +| V4 → V5 | `schema_v5.sql` | `schema_install_v5()` | rôles des personnes | +| V5 → V6 | `schema_v6.sql` | `schema_install_v6()` | identité usurpée | +| V6 → V7 | `schema_v7.sql` | `schema_install_v7()` | extractions | +| V7 → V8 | `schema_v8.sql` | `schema_install_v8()` | viewport du graphe | +| V8 → V9 | `schema_v9.sql` + migration C | `schema_install_v9()` | types canoniques de relations | +| V9 → V10 | `schema_v10.sql` | `schema_install_v10()` | pivot e-mail et entités bancaires | +| complément | `schema_current.sql` | `schema_ensure_current()` | extensions idempotentes V10 | + +## 5.1 V1 — Socle métier + +La V1 crée notamment : + +### Métadonnées + +- `metadata` +- `investigation` + +### Classification et référentiels + +- `categories` +- `tags` +- `types_preuve` +- `types_entite` +- `types_source` +- `types_outil` + +### Collecte + +- `sources` +- `preuves` +- `recherches` + +### Connaissance + +- `entites` +- `relations` + +### Raisonnement et traçabilité + +- `hypotheses` +- `chronologie` +- `journal` + +### Tables de liaison + +- `tag_preuves` +- `tag_recherches` +- `tag_entites` +- `tag_relations` +- `tag_hypotheses` +- `tag_chronologie` +- `recherche_preuves` +- `recherche_entites` +- `preuve_entites` +- `relation_preuves` +- `recherche_relations` +- `recherche_chronologie` +- `preuve_chronologie` +- `entite_chronologie` +- `relation_chronologie` +- `hypothese_preuves` +- `hypothese_entites` +- `hypothese_relations` +- `recherche_hypotheses` + +La V1 constitue un schéma étendu, et non un simple prototype à deux tables. + +## 5.2 V2 — Renforcement des preuves + +La V2 ajoute à `preuves` : + +- `original_name` ; +- `collected_at` ; +- `source` ; +- `integrity_status`. + +Elle effectue également : + +- un backfill de `original_name` depuis `name` ; +- la création de `idx_preuves_imported_at` ; +- un trigger de validation à l’insertion ; +- un trigger de validation à la mise à jour. + +Les triggers renforcent notamment : + +- le nom original obligatoire ; +- la taille non négative ; +- le SHA-256 en minuscules sur 64 caractères ; +- la plage valide de `integrity_status`. + +## 5.3 V3 — Provenance OSINT structurée + +La V3 ajoute : + +- `osint_executions` +- `osint_execution_entities` +- `osint_execution_relations` + +La table principale conserve notamment : + +- l’outil ; +- sa version ; +- l’action ; +- la sélection d’origine ; +- la cible ; +- les arguments ; +- les dates de début et de fin ; +- le code de sortie ; +- l’état final ; +- les sorties standard et erreur brutes ; +- le SHA-256 de la sortie. + +Les tables de liaison indiquent si les entités ou relations ont été créées ou +réutilisées. + +## 5.4 V4 — Comptes sociaux + +La V4 : + +- ajoute les types TikTok, X, Telegram et compte social générique ; +- crée `comptes_sociaux`. + +Cette table est une extension spécialisée d’une entité et conserve : + +- la plateforme ; +- l’URL du profil ; +- le pseudonyme ; +- un identifiant de plateforme facultatif ; +- la première observation ; +- l’état du compte ; +- des notes. + +## 5.5 V5 — Rôles des personnes + +La V5 crée `person_roles`. + +Le rôle est limité à une liste contrôlée comprenant notamment : + +- non catégorisé ; +- escroc présumé ; +- victime ; +- témoin ; +- suspect ; +- personne liée. + +## 5.6 V6 — Identité usurpée + +La V6 reconstruit `person_roles` afin d’ajouter : + +```text +impersonated_identity +``` + +Elle : + +1. renomme la table V5 ; +2. crée la nouvelle table ; +3. recopie les données ; +4. supprime l’ancienne table ; +5. recrée l’index. + +Cette migration est sensible aux clés étrangères et doit rester couverte par un +test de migration réel. + +## 5.7 V7 — Extractions + +La V7 crée `extractions`. + +Elle conserve : + +- l’identifiant de l’extraction ; +- une preuve associée facultative ; +- le type de source ; +- l’identifiant de la source ; +- l’outil ; +- la date de création. + +La provenance est partiellement polymorphe via : + +```text +source_kind +source_id +``` + +SQLite ne peut pas imposer directement une clé étrangère vers plusieurs tables +possibles. La cohérence de `source_id` dépend donc aussi de la couche métier. + +## 5.8 V8 — État du viewport + +La V8 crée `graph_viewport`. + +La table ne peut contenir qu’une ligne : + +```text +id = 1 +``` + +Elle persiste : + +- le zoom ; +- le décalage horizontal ; +- le décalage vertical ; +- la date de mise à jour. + +Il s’agit d’un état de présentation, pas d’une donnée métier. + +## 5.9 V9 — Types canoniques de relations + +La V9 crée `relation_types` avec : + +- un identifiant entier ; +- un code métier stable facultatif ; +- un libellé canonique ; +- une clé normalisée unique ; +- une description facultative ; +- un indicateur système. + +Elle insère dix types système initiaux, dont : + +- `resolves_to` +- `aliases_to` +- `uses_name_server` +- `links_to` +- `sends` +- `uses` +- `controls` +- `owns` +- `knows` +- `redirects_to` + +La migration ne se limite pas au fichier SQL. + +La fonction : + +```c +schema_v9_migrate_relation_types() +``` + +réalise également les opérations suivantes : + +1. ajoute `relations.relation_type_id` si nécessaire ; +2. parcourt les anciennes relations dans un ordre déterministe ; +3. normalise l’ancien texte `type_relation` ; +4. recherche un type existant par code ou clé normalisée ; +5. crée un type personnalisé lorsqu’aucun type ne correspond ; +6. rattache chaque relation au type canonique ; +7. crée l’index d’unicité canonique ; +8. crée l’index sur `relation_type_id` ; +9. crée des triggers interdisant un type canonique nul ; +10. exécute `PRAGMA foreign_key_check`. + +La colonne historique : + +```text +relations.type_relation +``` + +reste présente pour compatibilité. + +Depuis V9, l’identité logique du type doit être : + +```text +relations.relation_type_id +``` + +et non le texte historique. + + + +## 5.10 V10 — Pivot e-mail et entités bancaires + +La V10 crée : + +```text +bank_account_entities +``` + +Cette table conserve : + +- un UUID métier ; +- l’IBAN normalisé ; +- le BIC facultatif ; +- le nom du titulaire ; +- le nom et l’adresse de la banque ; +- le code pays ; +- le code banque ; +- le code guichet ; +- le numéro de compte ; +- la clé RIB ; +- le statut de vérification ; +- le type de provenance ; +- une preuve source facultative ; +- une extraction source facultative ; +- les dates de création et de mise à jour. + +Les statuts autorisés sont : + +```text +proposed +confirmed +rejected +conflicted +invalid +``` + +Les provenances autorisées sont : + +```text +observed +ocr +header +metadata +derived +manual +``` + +Les références vers `preuves` et `extractions` utilisent `ON DELETE SET NULL`. +La disparition d’un objet source ne supprime donc pas automatiquement la donnée +bancaire structurée. + +La V10 ajoute également les index : + +```text +idx_bank_account_entities_iban +idx_bank_account_entities_evidence +``` + +Elle insère neuf types système de relations : + +```text +sent_from +sent_to +reply_to +has_attachment +relayed_by +uses_domain +held_at +named_as_holder_of +supports +``` + +Ces codes techniques sont destinés à rester stables, tandis que les libellés +français peuvent évoluer indépendamment. + +### Migration V9 vers V10 + +La fonction : + +```c +database_migrate_v9_to_v10() +``` + +exécute atomiquement : + +1. `database_transaction_begin()` ; +2. `schema_install_v10()` ; +3. `database_update_schema_version(database, "10")` ; +4. `database_transaction_commit()`. + +En cas d’échec, elle appelle `database_transaction_rollback()`. + +### Portée fonctionnelle + +La présence du schéma V10 ne signifie pas que l’ensemble du ticket #107 est +terminé. + +Le ticket reste ouvert et couvre un périmètre beaucoup plus large : + +- analyse complète des en-têtes EML ; +- extraction MIME sécurisée ; +- OCR ; +- métadonnées ExifTool ; +- interface de révision ; +- intégration transactionnelle des propositions confirmées ; +- création ou réutilisation d’entités et de relations ; +- conservation complète de la provenance. + +La V10 constitue donc un socle persistant du pivot e-mail, pas la preuve de +l’achèvement de tout le flux fonctionnel. +--- + +# 6. Rôle de `schema_current.sql` + +`schema_current.sql` est présenté comme un ensemble d’extensions idempotentes +du schéma courant V10. + +Il crée si nécessaire : + +- `graph_node_positions` +- `extractions` +- `graph_layout_positions` +- `graph_viewport` +- `relation_types` +- `bank_account_entities` + +Il réinsère également, avec `INSERT OR IGNORE`, les types système de relations +ajoutés par V10. + +Il ajoute également deux triggers nettoyant les positions de graphe orphelines +après suppression d’une entité ou d’une relation. + +## 6.1 Migration des positions + +Le script copie les anciennes positions : + +```sql +INSERT OR IGNORE INTO graph_layout_positions (...) +SELECT ... FROM graph_node_positions; +``` + +puis exécute : + +```sql +DELETE FROM graph_node_positions; +``` + +L’objectif est de migrer l’ancien état limité aux entités vers une disposition +générique acceptant aussi les relations. + +## 6.2 Point d’attention + +Le script est exécuté après les migrations lors de l’ouverture. + +Il contient donc à la fois : + +- des créations idempotentes ; +- une migration de données de présentation ; +- une suppression des anciennes lignes. + +Le comportement peut être légitime, mais il doit être explicitement couvert par +des tests vérifiant plusieurs exécutions successives afin de garantir : + +- l’absence de perte de positions courantes ; +- l’absence de réimport d’anciennes coordonnées ; +- la stabilité après plusieurs ouvertures ; +- le nettoyage correct des positions orphelines. + +--- + +# 7. Inventaire statique du schéma V10 + +L’application statique des scripts versionnés et de `schema_current.sql` produit **46 tables distinctes**. + +Ce nombre est dérivé des scripts, et doit être confirmé sur une base générée par +une requête sur `sqlite_master`. + +## 7.1 Métadonnées + +| Table | Rôle | +|---|---| +| `metadata` | version et informations techniques | +| `investigation` | enquête unique contenue dans la base | + +## 7.2 Référentiels et classification + +| Table | Rôle | +|---|---| +| `categories` | classement principal | +| `tags` | annotations multiples | +| `types_preuve` | types de preuves | +| `types_entite` | types d’entités | +| `types_source` | types de sources | +| `types_outil` | types d’outils | +| `relation_types` | types canoniques de relations | + +## 7.3 Données métier principales + +| Table | Rôle | +|---|---| +| `sources` | origine d’une information | +| `preuves` | métadonnées des fichiers collectés | +| `recherches` | actions d’investigation | +| `entites` | objets identifiés | +| `relations` | liens orientés entre entités | +| `hypotheses` | raisonnements provisoires | +| `chronologie` | événements de l’enquête | +| `journal` | journal technique | + +## 7.4 Extensions spécialisées + +| Table | Version | Rôle | +|---|---:|---| +| `osint_executions` | V3 | provenance des traitements OSINT | +| `osint_execution_entities` | V3 | entités créées ou réutilisées | +| `osint_execution_relations` | V3 | relations créées ou réutilisées | +| `comptes_sociaux` | V4 | données propres aux comptes sociaux | +| `person_roles` | V5/V6 | rôle d’enquête d’une personne | +| `extractions` | V7 | provenance d’une extraction | +| `graph_viewport` | V8 | zoom et position du canevas | +| `graph_node_positions` | courant | ancien stockage des positions d’entités | +| `graph_layout_positions` | courant | positions génériques entités/relations | +| `bank_account_entities` | V10 | données bancaires structurées et vérifiables | + +## 7.5 Tables de liaison V1 + +| Domaine | Tables | +|---|---| +| tags | `tag_preuves`, `tag_recherches`, `tag_entites`, `tag_relations`, `tag_hypotheses`, `tag_chronologie` | +| recherches | `recherche_preuves`, `recherche_entites`, `recherche_relations`, `recherche_chronologie`, `recherche_hypotheses` | +| preuves | `preuve_entites`, `preuve_chronologie`, `relation_preuves` | +| chronologie | `entite_chronologie`, `relation_chronologie` | +| hypothèses | `hypothese_preuves`, `hypothese_entites`, `hypothese_relations` | + +--- + +# 8. Intégrité et sécurité des données + +## 8.1 Clés étrangères + +`database_open()` exécute : + +```sql +PRAGMA foreign_keys = ON; +``` + +Les stratégies observées sont : + +- `CASCADE` pour les objets strictement dépendants ; +- `RESTRICT` lorsque la suppression risquerait de casser l’historique ; +- `SET NULL` pour les références facultatives. + +## 8.2 Requêtes préparées + +Les valeurs variables de la couche Database et des DAO utilisent les fonctions +de préparation et de liaison. + +Les requêtes statiques sans donnée utilisateur peuvent être exécutées avec +`sqlite3_exec()`. + +La règle à conserver est : + +> aucune valeur externe ou utilisateur ne doit être concaténée dans une chaîne +> SQL. + +Le caractère append-only du journal ne constitue jamais une exception à cette +règle. + +## 8.3 Transactions + +Les migrations V1 à V10 sont pilotées par des fonctions dédiées. + +Chaque passage de version : + +- démarre une transaction ; +- applique le changement ; +- met à jour la version ; +- commit en cas de succès ; +- rollback en cas d’échec. + +La création d’une base neuve est également atomique. + +## 8.4 Preuves + +Le schéma et la couche métier conservent notamment : + +- UUID ; +- chemin relatif ; +- nom interne ; +- nom original ; +- taille ; +- SHA-256 ; +- type MIME ; +- date du fichier ; +- date de collecte ; +- date d’import ; +- statut d’intégrité ; +- statut logique. + +Le fichier original reste dans l’arborescence de l’enquête. SQLite conserve ses +métadonnées et ses relations. + +## 8.5 Suppression logique + +Plusieurs objets V1 utilisent des statuts tels que : + +```text +active +archived +deleted +``` + +Certaines suppressions physiques existent néanmoins dans les DAO, notamment +pour les relations. + +Le document d’architecture doit donc éviter d’affirmer que toute suppression +est systématiquement logique. La stratégie réelle doit être documentée table +par table. + +## 8.6 Journal et chronologie + +Le schéma distingue : + +- `chronologie` : événements significatifs de l’enquête ; +- `journal` : trace technique des actions de l’application. + +Le journal est conçu comme append-only dans la documentation, mais cet audit +n’a pas identifié de trigger SQLite interdisant une mise à jour ou une +suppression. Cette propriété repose donc actuellement au moins en partie sur la +couche applicative. + +--- + +# 9. Correspondance SQL, modèles, DAO et tests + +| Domaine | Table principale | Modèle ou structure | DAO/service observé | Tests observés | +|---|---|---|---|---| +| enquête | `investigation` | `InvestigationRecord` | `InvestigationDao` | `test_investigation_record`, `test_investigation_dao` | +| preuves | `preuves` | `EvidenceRecord` | `EvidenceDao`, `EvidenceTypeDao` | nombreux tests preuve/import/intégrité | +| preuve-entité | `preuve_entites` | — | `EvidenceEntityDao` | `test_evidence_entity_dao` | +| entités | `entites` | `EntityRecord` | `EntityDao`, `EntityTypeDao` | tests modèle et DAO | +| relations | `relations` | `RelationRecord` | `RelationDao`, `RelationService` | tests DAO, modèle et service | +| types de relation | `relation_types` | `RelationType` | `RelationTypeDao`, `RelationTypeService` | normalisation et service | +| relation-preuve | `relation_preuves` | — | `RelationEvidenceDao` | `test_relation_evidence_dao` | +| provenance OSINT | `osint_executions` | `OsintExecutionRecord` | `OsintExecutionDao` | DAO et intégrité | +| extractions | `extractions` | contexte métier | `ExtractionDao`, service de dépôt | `test_extraction_drop_service` | +| positions graphe | tables de graphe | `GraphNodePosition`, layout | `GraphNodePositionDao` | `test_graph_node_position_dao` | +| comptes sociaux | `comptes_sociaux` | plateforme sociale | service compte social | `test_social_account_service` | +| personnes | `person_roles` | extension d’entité | service personne | `test_person_entity_service` | +| comptes bancaires | `bank_account_entities` | `BankProposal` | pipeline EML et analyse bancaire ; DAO dédié non identifié dans les fichiers inspectés | `test_bank_proposal`, `test_eml_pipeline_task`, présence de table dans `test_database` | + +## Observation + +La V1 contient davantage de domaines que les DAO publics actuellement exposés. + +Aucun DAO dédié n’a été observé dans `include/dao/` pour plusieurs tables, dont : + +- `sources` ; +- `recherches` ; +- `hypotheses` ; +- `chronologie` ; +- `journal` ; +- `categories` ; +- `tags`. + +Cela ne signifie pas que ces tables sont inutilisables. Cela indique seulement +qu’aucune interface DAO publique dédiée n’est visible dans le dossier audité au +commit indiqué. + +--- + +# 10. Couverture de tests observée + +## 10.1 Points couverts par `test_database.c` + +Le fichier vérifie notamment : + +- l’initialisation d’une base valide ; +- le rollback d’une initialisation défaillante ; +- la présence de la version `10` dans une base neuve ; +- la présence de `bank_account_entities` ; +- la présence de plusieurs tables ajoutées après V1 ; +- la migration d’une base V1 vers la version courante V10 ; +- la conservation d’une preuve V1 ; +- le backfill V2 de `original_name` ; +- l’ajout des colonnes V2 ; +- l’ajout des triggers V2 ; +- le rollback complet d’une migration V2 provoquée en échec ; +- `PRAGMA integrity_check` après le rollback. + +## 10.2 Tests spécialisés observés + +Le dépôt possède également des tests pour : + +- les preuves et leur intégrité ; +- les entités ; +- les relations ; +- les types canoniques de relations ; +- les exécutions OSINT ; +- les extractions ; +- les positions du graphe ; +- les comptes sociaux ; +- les rôles des personnes ; +- le vocabulaire contrôlé ; +- l’analyse et la validation des propositions IBAN/BIC ; +- le pipeline EML asynchrone. + +## 10.3 Lacunes de couverture à traiter + +Le test principal de migration ne fournit pas une fixture indépendante pour +chaque version V2 à V10. + +Aucun test dédié nommé V9 → V10 n’a été identifié dans `test_database.c`. +La création d’une base neuve vérifie bien la présence de la table V10, et la +fixture V1 atteint bien la version 10, mais cela ne remplace pas une migration +V9 réaliste contenant des relations, extractions, preuves et données bancaires. + +Matrice recommandée : + +| Base d’entrée | Migration | Vérifications minimales | +|---|---|---| +| V1 | V1 → V10 | données, version, FK, intégrité | +| V2 | V2 → V10 | preuve V2 conservée | +| V3 | V3 → V10 | provenance OSINT conservée | +| V4 | V4 → V10 | comptes sociaux conservés | +| V5 | V5 → V10 | rôles conservés pendant reconstruction V6 | +| V6 | V6 → V10 | identité usurpée conservée | +| V7 | V7 → V10 | extractions conservées | +| V8 | V8 → V10 | viewport et positions conservés | +| V9 | V9 → V10 | relations canoniques conservées, table bancaire créée | +| V10 | réouverture | idempotence de `schema_current.sql` | + +Chaque fixture devrait vérifier au minimum : + +```sql +PRAGMA integrity_check; +PRAGMA foreign_key_check; +SELECT value FROM metadata WHERE key = 'schema_version'; +``` + +--- + +# 11. Constats d’audit + +## AUD-001 — Documentation courante restée en V1 + +**Sévérité : élevée** + +`docs/database/DATABASE_ARCHITECTURE.md` s’annonce encore comme : + +```text +Statut : Stable (V1) +Schéma : V1 +``` + +alors que le code utilise V10. + +### Risque + +- confusion des développeurs ; +- erreurs des agents locaux ; +- mauvaise interprétation de l’état du projet ; +- décisions basées sur des structures historiques ; +- oubli des tables V2 à V10. + +### Action recommandée + +Créer : + +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` + +et déplacer les audits historiques vers : + +```text +docs/database/audits/SCHEMA_AUDIT_V1.md +docs/database/audits/SCHEMA_AUDIT_V9.md +``` + +Le document courant doit indiquer le commit exact qu’il audite. + +--- + +## AUD-002 — Couverture spécifique V9 → V10 insuffisante + +**Sévérité : élevée** + +La V10 est bien publiée et installée par le code. Les tests confirment : + +- une base neuve en version 10 ; +- la présence de `bank_account_entities` ; +- une migration V1 atteignant la version 10. + +Aucune fixture dédiée V9 → V10 n’a toutefois été identifiée. + +### Risque + +Une régression propre au passage V9 → V10 pourrait ne pas être détectée, +notamment sur : + +- les relations canoniques V9 ; +- les références vers `preuves` et `extractions` ; +- l’idempotence des nouveaux types de relations ; +- le rollback après création partielle de la table bancaire. + +### Action recommandée + +Ajouter un test synthétique V9 → V10 qui vérifie : + +1. la conservation des objets V9 ; +2. la création de `bank_account_entities` ; +3. l’unicité des types de relations insérés ; +4. `PRAGMA integrity_check` ; +5. `PRAGMA foreign_key_check` ; +6. le rollback complet d’une migration V10 volontairement mise en échec. + +--- + +## AUD-003 — Version courante dupliquée + +**Sévérité : moyenne** + +La version est définie deux fois : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +DATABASE_SCHEMA_VERSION_CURRENT_TEXT +``` + +Les tests comparent aussi directement la chaîne `"10"`. + +### Risque + +Une future migration peut modifier une valeur et oublier l’autre. + +### Action recommandée + +Conserver une seule constante numérique et produire la représentation textuelle +au moment de l’écriture, ou centraliser les deux valeurs dans un fichier +d’interface unique couvert par une assertion de test. + +--- + +## AUD-004 — `schema_current.sql` mélange plusieurs responsabilités + +**Sévérité : moyenne** + +Le fichier sert à la fois à : + +- créer des structures manquantes ; +- maintenir la compatibilité ; +- migrer des positions ; +- supprimer les anciennes positions ; +- installer des triggers ; +- recréer la table bancaire V10 si elle manque ; +- réinsérer les types système du pivot e-mail. + +### Risque + +Une opération supposée idempotente peut finir par modifier des données à chaque +ouverture. + +### Action recommandée + +Documenter chaque opération et ajouter un test exécutant +`schema_ensure_current()` plusieurs fois sur la même fixture. + +--- + +## AUD-005 — Contrôle des clés étrangères non généralisé + +**Sévérité : moyenne** + +La migration V9 exécute explicitement : + +```sql +PRAGMA foreign_key_check; +``` + +Aucun contrôle générique similaire n’a été observé dans le pilote commun de +toutes les migrations. + +### Action recommandée + +Exécuter un contrôle générique avant le commit de chaque migration, ou fournir +une justification documentée lorsqu’une migration ne le nécessite pas. + +--- + +## AUD-006 — Couverture de migration incomplète par version + +**Sévérité : élevée** + +Le test principal couvre : + +- création d’une base neuve ; +- migration V1 vers la version courante ; +- rollback V2. + +Il ne constitue pas une matrice complète de fixtures V2 à V10. + +### Action recommandée + +Ajouter une fixture synthétique minimale pour chaque version publiée et migrer +chacune vers la version courante. + +--- + +## AUD-007 — Absence de sauvegarde préalable observée + +**Sévérité : élevée pour des enquêtes réelles** + +Aucun appel de sauvegarde SQLite ou copie préalable n’a été observé dans +`database_migrate_to_latest()`. + +La transaction protège la cohérence logique, mais elle ne remplace pas une +copie de sécurité face à : + +- panne disque ; +- interruption brutale ; +- défaut SQLite ou système de fichiers ; +- erreur de migration non anticipée ; +- corruption déjà présente. + +### Action recommandée + +Avant toute migration d’une base existante : + +1. fermer ou stabiliser les accès concurrents ; +2. créer une sauvegarde cohérente ; +3. vérifier sa création ; +4. lancer la migration ; +5. conserver la sauvegarde tant que la validation n’est pas terminée. + +Cette fonctionnalité doit être testée uniquement sur des bases synthétiques. + +--- + +## AUD-008 — Ancienne et nouvelle identité du type de relation coexistent + +**Sévérité : moyenne** + +V9 conserve : + +```text +relations.type_relation +``` + +et ajoute : + +```text +relations.relation_type_id +``` + +La documentation du commit précise que la première colonne ne doit plus servir +d’identité. + +### Risque + +Un module ancien peut encore filtrer ou détecter les doublons par texte. + +### Action recommandée + +Auditer tous les producteurs et lecteurs de relations, puis ajouter un test +interdisant toute régression vers `type_relation` comme clé métier. + +La colonne historique pourra être supprimée dans une future migration seulement +après validation de toutes les anciennes bases et de tous les adaptateurs. + +--- + +## AUD-009 — Append-only non imposé par SQLite + +**Sévérité : faible à moyenne** + +Le journal est documenté comme append-only, mais aucun trigger interdisant +`UPDATE` ou `DELETE` n’a été identifié dans les scripts examinés. + +### Action recommandée + +Choisir explicitement l’une des deux politiques : + +- garantie applicative documentée et testée ; +- garantie SQLite par triggers de refus. + +Le document courant doit dire laquelle est réellement retenue. + +--- + +## AUD-010 — Paramètres SQLite de durabilité non documentés dans le code audité + +**Sévérité : à évaluer** + +Aucun réglage explicite n’a été identifié dans `database.c` pour : + +- `journal_mode` ; +- `synchronous` ; +- `busy_timeout`. + +SQLite applique donc probablement ses valeurs par défaut, sauf réglage réalisé +ailleurs. + +### Action recommandée + +Documenter volontairement les paramètres retenus et leurs conséquences avant +un usage opérationnel. + +Ne pas activer WAL ou modifier `synchronous` sans étudier la portabilité d’une +enquête et les procédures de copie de ses fichiers annexes. + +--- + +# 12. État de validation de la V10 + +## 12.1 Implémentation confirmée + +Les éléments suivants sont présents au commit audité : + +- `database/schema_v10.sql` ; +- déclaration de `schema_install_v10()` ; +- implémentation de `schema_install_v10()` ; +- `database_migrate_v9_to_v10()` ; +- cas `9` dans `database_migrate_to_latest()` ; +- installation V10 dans `database_initialize()` ; +- version numérique `10` ; +- version textuelle `"10"` ; +- table `bank_account_entities` ; +- index IBAN et preuve ; +- nouveaux types système de relations ; +- mise à jour de `schema_current.sql` ; +- mise à jour de `test_database.c`. + +## 12.2 Validation partielle confirmée + +Les tests présents couvrent : + +- la création d’une base neuve V10 ; +- la présence de `bank_account_entities` ; +- l’arrivée d’une ancienne base V1 en version 10 ; +- le vocabulaire contrôlé ; +- l’analyse de propositions bancaires ; +- un scénario de pipeline EML. + +## 12.3 Validation encore recommandée + +Restent à ajouter ou confirmer : + +- fixture directe V9 → V10 ; +- rollback provoqué de la migration V10 ; +- conservation de données V9 riches ; +- vérification des deux clés étrangères de `bank_account_entities` ; +- contrôle de doublon des types système après ouvertures répétées ; +- `PRAGMA foreign_key_check` avant validation de V10 ; +- DAO ou service de persistance clairement identifié pour + `bank_account_entities` ; +- test de réouverture multiple de `schema_current.sql` ; +- validation complète des critères du ticket #107. + +## 12.4 Statut fonctionnel + +Le **schéma V10 est implémenté**. + +Le **pivot e-mail complet n’est pas déclaré terminé** : le ticket #107 est +toujours ouvert et couvre un périmètre supérieur à la seule migration SQLite. + +--- + +# 13. Procédure de vérification reproductible + +> Utiliser uniquement une copie synthétique. +> Ne jamais exécuter cette procédure sur une base d’enquête réelle sans +> sauvegarde et validation préalable. + +## 13.1 Compilation + +```bash +make clean +make -j8 +make -j8 test +git diff --check +``` + +En cas d’échec provoqué par la parallélisation, revenir temporairement à : + +```bash +make +make test +``` + +## 13.2 Création d’une base synthétique + +Créer une enquête de test par l’API normale de l’application ou par un test +dédié, puis vérifier : + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT value FROM metadata WHERE key = 'schema_version';" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA integrity_check;" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA foreign_key_check;" +``` + +Résultats attendus : + +```text + +ok + +``` + +## 13.3 Inventaire du schéma + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT type, name + FROM sqlite_master + WHERE name NOT LIKE 'sqlite_%' + ORDER BY type, name;" +``` + +## 13.4 Vérification de l’idempotence + +1. ouvrir la base ; +2. fermer la base ; +3. enregistrer un dump du schéma et les données de présentation ; +4. rouvrir la base plusieurs fois ; +5. comparer les résultats ; +6. vérifier les positions du graphe ; +7. vérifier les types de relations ; +8. exécuter à nouveau les deux PRAGMA d’intégrité. + +## 13.5 Vérification de migration + +Pour chaque fixture V1 à V10 : + +1. calculer une copie de travail ; +2. relever la version initiale ; +3. compter les objets métier ; +4. migrer ; +5. vérifier la version finale ; +6. comparer les UUID ; +7. comparer les empreintes des preuves ; +8. comparer les liaisons ; +9. vérifier les contraintes ; +10. vérifier le rollback sur une copie volontairement invalide. + +--- + +# 14. Règle de maintenance proposée + +Toute nouvelle version du schéma doit livrer ensemble : + +```text +migration SQL ++ fonction d’installation ++ fonction de migration ++ incrément de version ++ tests de base neuve ++ tests d’ancienne base ++ test de rollback ++ contrôle d’intégrité ++ mise à jour de SCHEMA_AUDIT_CURRENT.md ++ ticket Forgejo ++ commit vérifiable +``` + +Un ticket de migration ne doit pas être fermé tant que cette chaîne n’est pas +complète. + +## Statuts documentaires obligatoires + +Chaque table, colonne ou fonctionnalité mentionnée dans la documentation devrait +porter l’un des statuts suivants : + +```text +IMPLÉMENTÉ +PARTIELLEMENT IMPLÉMENTÉ +DOCUMENTÉ MAIS NON IMPLÉMENTÉ +HISTORIQUE +ABANDONNÉ +``` + +Cette règle évitera de confondre : + +- une architecture cible ; +- un ancien audit ; +- une fonctionnalité réellement présente ; +- un ticket encore ouvert ; +- une migration locale non publiée. + +--- + +# 15. Conclusion + +Le schéma V10 repose sur une base technique sérieuse : + +- modèle relationnel riche ; +- versionnement explicite ; +- migrations transactionnelles ; +- provenance OSINT ; +- contraintes sur les preuves ; +- normalisation des types de relations ; +- séparation des données métier et de l’état du graphe ; +- table bancaire structurée avec provenance et statut contrôlés ; +- tests dédiés aux nouveaux composants EML et bancaires. + +La V10 est bien publiée et détectable par le code comme version courante. + +Le principal risque documentaire reste l’écart entre : + +- l’ancienne documentation V1 ; +- le schéma courant V10 ; +- les fonctionnalités partielles déjà présentes ; +- le ticket #107, qui décrit encore un flux complet en cours de réalisation. + +`SCHEMA_AUDIT_V1.md` et `SCHEMA_AUDIT_V9.md` doivent rester des documents +historiques. Le présent fichier doit devenir la référence courante jusqu’à la +prochaine migration. + +Les prochaines actions recommandées sont : + +1. ajouter une fixture V9 → V10 ; +2. tester le rollback V10 ; +3. exécuter `integrity_check` et `foreign_key_check` sur une base synthétique ; +4. clarifier le service responsable de la persistance bancaire ; +5. maintenir ce document à chaque nouvelle version ; +6. ne fermer le ticket #107 qu’après validation de son flux fonctionnel complet. + +--- + +# 16. Références du dépôt + +## Commit audité + +```text +613d2096bc5eeb2c1c4f60ae701292e19a2abe66 +feat(relations): centraliser les types et améliorer les aperçus +Date : 2026-07-24 12:53:31 +02:00 +``` + +Le commit contient notamment : + +```text +28 fichiers modifiés +1826 ajouts +18 suppressions +``` + +## Tickets Forgejo liés + +```text +#107 — Ajouter un pivot e-mail forensique avec OCR, métadonnées et + normalisation des données +État : ouvert +``` + +```text +#106 — Normaliser et centraliser les types de relations +État : fermé +``` + +## Documents historiques + +```text +docs/database/DATABASE_ARCHITECTURE.md +docs/database/SCHEMA_AUDIT_V1.md +docs/database/audits/SCHEMA_AUDIT_V9.md +``` + +## Fichiers constituant la source de vérité technique V10 + +```text +database/schema_v1.sql +database/schema_v2.sql +database/schema_v3.sql +database/schema_v4.sql +database/schema_v5.sql +database/schema_v6.sql +database/schema_v7.sql +database/schema_v8.sql +database/schema_v9.sql +database/schema_v10.sql +database/schema_current.sql + +src/database/database.c +src/database/schema.c +src/database/statement.c +src/database/transaction.c + +include/database/database.h +include/database/schema.h + +include/core/bank_proposal.h +include/core/controlled_vocab.h +include/core/eml_mime_extractor.h +include/core/eml_pipeline_task.h + +tests/test_database.c +tests/test_statement.c +tests/test_transaction.c +tests/test_bank_proposal.c +tests/test_controlled_vocab.c +tests/test_eml_pipeline_task.c +``` diff --git a/docs/database/audits/SCHEMA_AUDIT_V9.md b/docs/database/audits/SCHEMA_AUDIT_V9.md new file mode 100644 index 0000000..8160b0b --- /dev/null +++ b/docs/database/audits/SCHEMA_AUDIT_V9.md @@ -0,0 +1,1408 @@ +# Audit du schéma SQLite V9 + +> [!IMPORTANT] +> Ce document audite la V9 visible sur la branche publique au commit indiqué. +> Il ne doit pas être utilisé comme audit du schéma V10 local sans une nouvelle +> vérification du code, des migrations et des tests V10. + +> **Projet :** Labfy Investigation +> **Date de l’audit :** 2026-07-24 +> **Branche auditée :** `main` publique sur Forgejo +> **Commit audité :** `8bc3b43d63f4bd3da673ddf86a7e4b7a81e28604` +> **Version de schéma confirmée par le code public :** **V9** +> **Statut du document :** audit historique vérifié de la V9 publique +> **Périmètre :** schémas SQL, mécanisme de migration, couche Database, DAO principaux, tests et tickets Forgejo associés + +--- + +## Avertissement important concernant la V10 + +Le propriétaire du projet indique que le dépôt de travail local est déjà en **V10**. + +Au moment de cet audit, la branche `main` publique consultée sur Forgejo expose toutefois : + +- `DATABASE_SCHEMA_VERSION_CURRENT 9` dans `src/database/database.c` ; +- des scripts versionnés allant de `database/schema_v1.sql` à + `database/schema_v9.sql` ; +- `database/schema_current.sql` explicitement présenté comme le schéma courant + V9 ; +- aucun fichier `schema_v10.sql` dans la branche publique auditée. + +Ce document décrit donc **l’état public V9 vérifiable**, et non la V10 locale +non encore accessible dans les sources consultées. + +Il ne doit pas être présenté comme l’audit définitif de la V10 tant que les +fichiers suivants n’ont pas été publiés ou fournis : + +- le script de migration V10 ; +- les fonctions C d’installation et de migration vers V10 ; +- la nouvelle constante de version ; +- les tests de création et de migration V10 ; +- les tickets et commits correspondants. + +--- + +# 1. Résumé exécutif + +Le schéma public de Labfy Investigation est un schéma SQLite versionné, propre +à chaque enquête et construit autour de quatre objectifs principaux : + +1. préserver les preuves et leurs métadonnées ; +2. structurer les entités et leurs relations ; +3. conserver la provenance des traitements OSINT ; +4. permettre l’évolution du modèle par migrations transactionnelles. + +La version publique courante est la V9. + +Le mécanisme général est cohérent : + +- la version est stockée dans `metadata.schema_version` ; +- une base plus récente que l’application est refusée ; +- chaque migration possède une fonction dédiée ; +- chaque migration s’exécute dans une transaction ; +- la version n’est mise à jour qu’après l’application du SQL ; +- un échec provoque un rollback ; +- une nouvelle base reçoit immédiatement V1 à V9 dans une seule transaction ; +- `schema_current.sql` ajoute des extensions idempotentes à chaque ouverture. + +Les points les plus solides sont : + +- activation explicite des clés étrangères ; +- usage des requêtes préparées pour les valeurs variables ; +- migration V9 conservatrice des types de relations ; +- contrôle `PRAGMA foreign_key_check` avant validation de la V9 ; +- tests de création d’une base neuve ; +- test de migration d’une ancienne base V1 ; +- test de rollback d’une migration V2 défaillante. + +Les principales faiblesses documentaires ou techniques observées sont : + +- la documentation principale de la base reste annoncée comme « stable V1 » + alors que le code public est en V9 ; +- la version courante est dupliquée sous forme numérique et textuelle dans un + fichier C privé ; +- les tests de migration ne couvrent pas systématiquement chaque version et + chaque rollback ; +- `schema_current.sql` mélange rattrapage idempotent et migration de données de + présentation ; +- aucune sauvegarde préalable automatique n’a été observée dans le mécanisme de + migration consulté ; +- la V10 locale ne peut pas être auditée tant qu’elle n’est pas disponible. + +--- + +# 2. Méthode et hiérarchie des sources + +L’audit applique l’ordre de confiance suivant : + +1. code présent dans la branche auditée ; +2. scripts de schéma et fonctions de migration ; +3. tests automatisés ; +4. commits associés ; +5. tickets Forgejo fermés ; +6. documentation d’architecture ; +7. anciens audits et feuilles de route. + +Cette hiérarchie est nécessaire parce qu’un document historique peut décrire +une intention ou une ancienne version sans représenter l’état courant. + +## 2.1 Sources principales examinées + +### Schémas + +- `database/schema_v1.sql` +- `database/schema_v2.sql` +- `database/schema_v3.sql` +- `database/schema_v4.sql` +- `database/schema_v5.sql` +- `database/schema_v6.sql` +- `database/schema_v7.sql` +- `database/schema_v8.sql` +- `database/schema_v9.sql` +- `database/schema_current.sql` + +### Infrastructure SQLite + +- `src/database/database.c` +- `src/database/schema.c` +- `src/database/statement.c` +- `src/database/transaction.c` +- `include/database/database.h` +- `include/database/schema.h` + +### Accès métier et modèles + +- contenu de `include/dao/` +- contenu de `src/dao/` +- contenu de `include/models/` +- modules liés aux preuves, entités, relations, provenance OSINT, extractions + et positions du graphe + +### Tests + +- `tests/test_database.c` +- `tests/test_statement.c` +- `tests/test_transaction.c` +- tests des DAO et services visibles dans `tests/` +- tests des types canoniques de relations + +### Documentation et tickets + +- `docs/database/DATABASE_ARCHITECTURE.md` +- `docs/database/SCHEMA_AUDIT_V1.md` +- ticket Forgejo `#106` : normalisation des types de relations +- commit `8bc3b43d63` : centralisation des types de relations + +## 2.2 Limites de l’audit + +Cet audit est une analyse statique du dépôt public. + +Il n’a pas exécuté : + +- `make -j8` ; +- la suite de tests ; +- une migration réelle sur une base synthétique ; +- `PRAGMA integrity_check` sur une base V9 produite localement ; +- `PRAGMA foreign_key_check` sur une base V9 produite localement ; +- une comparaison binaire entre une base migrée et une base fraîche. + +Les procédures de vérification reproductible sont proposées plus loin. + +--- + +# 3. Source de vérité de la version + +## 3.1 Constante courante + +La source de vérité publique se trouve dans : + +```text +src/database/database.c +``` + +avec les deux définitions : + +```c +#define DATABASE_SCHEMA_VERSION_CURRENT 9 +#define DATABASE_SCHEMA_VERSION_CURRENT_TEXT "9" +``` + +La première sert aux comparaisons numériques. + +La seconde est enregistrée dans : + +```text +metadata.schema_version +``` + +## 3.2 Lecture de la version + +La fonction : + +```c +database_read_schema_version() +``` + +effectue les contrôles suivants : + +- prépare une requête vers `metadata` ; +- lie la clé `schema_version` ; +- refuse l’absence de valeur ; +- refuse une chaîne vide ; +- convertit la valeur en entier ; +- refuse une valeur non numérique ; +- refuse une version inférieure à 1 ; +- refuse une valeur supérieure à `G_MAXINT` ; +- vérifie qu’aucune seconde ligne n’est retournée. + +## 3.3 Base plus récente que l’application + +La fonction : + +```c +database_migrate_to_latest() +``` + +refuse une base dont la version est supérieure à : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +``` + +Cela évite qu’une ancienne version de Labfy Investigation ouvre et modifie une +base créée par une version plus récente. + +## 3.4 Version inconnue ou non migrable + +La boucle de migration utilise un `switch` sur la version actuelle. + +Une version ancienne qui ne possède aucun chemin connu produit une erreur +d’état au lieu d’essayer une transformation implicite. + +## 3.5 Mise à jour de la version + +La fonction : + +```c +database_update_schema_version() +``` + +utilise une requête préparée et met à jour la clé `schema_version`. + +Dans chaque migration examinée, cette mise à jour intervient après +l’installation de la nouvelle structure et avant le `COMMIT`. + +En cas d’erreur, la transaction est annulée et la version ne doit pas avancer. + +--- + +# 4. Installation d’une base neuve + +La fonction : + +```c +database_initialize() +``` + +crée une base neuve dans une transaction initiale unique. + +L’ordre public V9 est le suivant : + +1. ouverture de SQLite ; +2. activation de `PRAGMA foreign_keys = ON` ; +3. début de transaction ; +4. installation de V1 ; +5. installation de V2 ; +6. installation de V3 ; +7. installation de V4 ; +8. installation de V5 ; +9. installation de V6 ; +10. installation de V7 ; +11. installation de V8 ; +12. installation de V9 ; +13. application de `schema_current.sql` ; +14. insertion des métadonnées ; +15. insertion de l’enquête ; +16. commit. + +Un échec provoque un rollback de l’ensemble. + +## Observation + +Une base neuve rejoue toute l’histoire du schéma. + +Cette méthode garantit qu’une base neuve et une base migrée utilisent les mêmes +étapes. Elle impose cependant que chaque ancien script reste compatible avec +le moteur SQLite utilisé aujourd’hui. + +À moyen terme, le projet pourra envisager un schéma de référence consolidé pour +les bases neuves, tout en conservant les migrations historiques pour les +anciennes bases. Ce changement ne doit être réalisé qu’avec des tests comparant +strictement les deux chemins. + +--- + +# 5. Chaîne publique des migrations + +| Passage | Script | Fonction C | Objet principal | +|---|---|---|---| +| création | `schema_v1.sql` | `schema_install_v1()` | socle métier complet | +| V1 → V2 | `schema_v2.sql` | `schema_install_v2()` | renforcement des preuves | +| V2 → V3 | `schema_v3.sql` | `schema_install_v3()` | provenance OSINT | +| V3 → V4 | `schema_v4.sql` | `schema_install_v4()` | comptes sociaux | +| V4 → V5 | `schema_v5.sql` | `schema_install_v5()` | rôles des personnes | +| V5 → V6 | `schema_v6.sql` | `schema_install_v6()` | identité usurpée | +| V6 → V7 | `schema_v7.sql` | `schema_install_v7()` | extractions | +| V7 → V8 | `schema_v8.sql` | `schema_install_v8()` | viewport du graphe | +| V8 → V9 | `schema_v9.sql` + migration C | `schema_install_v9()` | types canoniques de relations | +| complément | `schema_current.sql` | `schema_ensure_current()` | extensions idempotentes V9 | + +## 5.1 V1 — Socle métier + +La V1 crée notamment : + +### Métadonnées + +- `metadata` +- `investigation` + +### Classification et référentiels + +- `categories` +- `tags` +- `types_preuve` +- `types_entite` +- `types_source` +- `types_outil` + +### Collecte + +- `sources` +- `preuves` +- `recherches` + +### Connaissance + +- `entites` +- `relations` + +### Raisonnement et traçabilité + +- `hypotheses` +- `chronologie` +- `journal` + +### Tables de liaison + +- `tag_preuves` +- `tag_recherches` +- `tag_entites` +- `tag_relations` +- `tag_hypotheses` +- `tag_chronologie` +- `recherche_preuves` +- `recherche_entites` +- `preuve_entites` +- `relation_preuves` +- `recherche_relations` +- `recherche_chronologie` +- `preuve_chronologie` +- `entite_chronologie` +- `relation_chronologie` +- `hypothese_preuves` +- `hypothese_entites` +- `hypothese_relations` +- `recherche_hypotheses` + +La V1 constitue un schéma étendu, et non un simple prototype à deux tables. + +## 5.2 V2 — Renforcement des preuves + +La V2 ajoute à `preuves` : + +- `original_name` ; +- `collected_at` ; +- `source` ; +- `integrity_status`. + +Elle effectue également : + +- un backfill de `original_name` depuis `name` ; +- la création de `idx_preuves_imported_at` ; +- un trigger de validation à l’insertion ; +- un trigger de validation à la mise à jour. + +Les triggers renforcent notamment : + +- le nom original obligatoire ; +- la taille non négative ; +- le SHA-256 en minuscules sur 64 caractères ; +- la plage valide de `integrity_status`. + +## 5.3 V3 — Provenance OSINT structurée + +La V3 ajoute : + +- `osint_executions` +- `osint_execution_entities` +- `osint_execution_relations` + +La table principale conserve notamment : + +- l’outil ; +- sa version ; +- l’action ; +- la sélection d’origine ; +- la cible ; +- les arguments ; +- les dates de début et de fin ; +- le code de sortie ; +- l’état final ; +- les sorties standard et erreur brutes ; +- le SHA-256 de la sortie. + +Les tables de liaison indiquent si les entités ou relations ont été créées ou +réutilisées. + +## 5.4 V4 — Comptes sociaux + +La V4 : + +- ajoute les types TikTok, X, Telegram et compte social générique ; +- crée `comptes_sociaux`. + +Cette table est une extension spécialisée d’une entité et conserve : + +- la plateforme ; +- l’URL du profil ; +- le pseudonyme ; +- un identifiant de plateforme facultatif ; +- la première observation ; +- l’état du compte ; +- des notes. + +## 5.5 V5 — Rôles des personnes + +La V5 crée `person_roles`. + +Le rôle est limité à une liste contrôlée comprenant notamment : + +- non catégorisé ; +- escroc présumé ; +- victime ; +- témoin ; +- suspect ; +- personne liée. + +## 5.6 V6 — Identité usurpée + +La V6 reconstruit `person_roles` afin d’ajouter : + +```text +impersonated_identity +``` + +Elle : + +1. renomme la table V5 ; +2. crée la nouvelle table ; +3. recopie les données ; +4. supprime l’ancienne table ; +5. recrée l’index. + +Cette migration est sensible aux clés étrangères et doit rester couverte par un +test de migration réel. + +## 5.7 V7 — Extractions + +La V7 crée `extractions`. + +Elle conserve : + +- l’identifiant de l’extraction ; +- une preuve associée facultative ; +- le type de source ; +- l’identifiant de la source ; +- l’outil ; +- la date de création. + +La provenance est partiellement polymorphe via : + +```text +source_kind +source_id +``` + +SQLite ne peut pas imposer directement une clé étrangère vers plusieurs tables +possibles. La cohérence de `source_id` dépend donc aussi de la couche métier. + +## 5.8 V8 — État du viewport + +La V8 crée `graph_viewport`. + +La table ne peut contenir qu’une ligne : + +```text +id = 1 +``` + +Elle persiste : + +- le zoom ; +- le décalage horizontal ; +- le décalage vertical ; +- la date de mise à jour. + +Il s’agit d’un état de présentation, pas d’une donnée métier. + +## 5.9 V9 — Types canoniques de relations + +La V9 crée `relation_types` avec : + +- un identifiant entier ; +- un code métier stable facultatif ; +- un libellé canonique ; +- une clé normalisée unique ; +- une description facultative ; +- un indicateur système. + +Elle insère dix types système initiaux, dont : + +- `resolves_to` +- `aliases_to` +- `uses_name_server` +- `links_to` +- `sends` +- `uses` +- `controls` +- `owns` +- `knows` +- `redirects_to` + +La migration ne se limite pas au fichier SQL. + +La fonction : + +```c +schema_v9_migrate_relation_types() +``` + +réalise également les opérations suivantes : + +1. ajoute `relations.relation_type_id` si nécessaire ; +2. parcourt les anciennes relations dans un ordre déterministe ; +3. normalise l’ancien texte `type_relation` ; +4. recherche un type existant par code ou clé normalisée ; +5. crée un type personnalisé lorsqu’aucun type ne correspond ; +6. rattache chaque relation au type canonique ; +7. crée l’index d’unicité canonique ; +8. crée l’index sur `relation_type_id` ; +9. crée des triggers interdisant un type canonique nul ; +10. exécute `PRAGMA foreign_key_check`. + +La colonne historique : + +```text +relations.type_relation +``` + +reste présente pour compatibilité. + +Depuis V9, l’identité logique du type doit être : + +```text +relations.relation_type_id +``` + +et non le texte historique. + +--- + +# 6. Rôle de `schema_current.sql` + +`schema_current.sql` est présenté comme un ensemble d’extensions idempotentes +du schéma courant V9. + +Il crée si nécessaire : + +- `graph_node_positions` +- `extractions` +- `graph_layout_positions` +- `graph_viewport` +- `relation_types` + +Il ajoute également deux triggers nettoyant les positions de graphe orphelines +après suppression d’une entité ou d’une relation. + +## 6.1 Migration des positions + +Le script copie les anciennes positions : + +```sql +INSERT OR IGNORE INTO graph_layout_positions (...) +SELECT ... FROM graph_node_positions; +``` + +puis exécute : + +```sql +DELETE FROM graph_node_positions; +``` + +L’objectif est de migrer l’ancien état limité aux entités vers une disposition +générique acceptant aussi les relations. + +## 6.2 Point d’attention + +Le script est exécuté après les migrations lors de l’ouverture. + +Il contient donc à la fois : + +- des créations idempotentes ; +- une migration de données de présentation ; +- une suppression des anciennes lignes. + +Le comportement peut être légitime, mais il doit être explicitement couvert par +des tests vérifiant plusieurs exécutions successives afin de garantir : + +- l’absence de perte de positions courantes ; +- l’absence de réimport d’anciennes coordonnées ; +- la stabilité après plusieurs ouvertures ; +- le nettoyage correct des positions orphelines. + +--- + +# 7. Inventaire statique du schéma public V9 + +L’application statique des scripts publics produit **45 tables distinctes**. + +Ce nombre est dérivé des scripts, et doit être confirmé sur une base générée par +une requête sur `sqlite_master`. + +## 7.1 Métadonnées + +| Table | Rôle | +|---|---| +| `metadata` | version et informations techniques | +| `investigation` | enquête unique contenue dans la base | + +## 7.2 Référentiels et classification + +| Table | Rôle | +|---|---| +| `categories` | classement principal | +| `tags` | annotations multiples | +| `types_preuve` | types de preuves | +| `types_entite` | types d’entités | +| `types_source` | types de sources | +| `types_outil` | types d’outils | +| `relation_types` | types canoniques de relations | + +## 7.3 Données métier principales + +| Table | Rôle | +|---|---| +| `sources` | origine d’une information | +| `preuves` | métadonnées des fichiers collectés | +| `recherches` | actions d’investigation | +| `entites` | objets identifiés | +| `relations` | liens orientés entre entités | +| `hypotheses` | raisonnements provisoires | +| `chronologie` | événements de l’enquête | +| `journal` | journal technique | + +## 7.4 Extensions spécialisées + +| Table | Version | Rôle | +|---|---:|---| +| `osint_executions` | V3 | provenance des traitements OSINT | +| `osint_execution_entities` | V3 | entités créées ou réutilisées | +| `osint_execution_relations` | V3 | relations créées ou réutilisées | +| `comptes_sociaux` | V4 | données propres aux comptes sociaux | +| `person_roles` | V5/V6 | rôle d’enquête d’une personne | +| `extractions` | V7 | provenance d’une extraction | +| `graph_viewport` | V8 | zoom et position du canevas | +| `graph_node_positions` | courant | ancien stockage des positions d’entités | +| `graph_layout_positions` | courant | positions génériques entités/relations | + +## 7.5 Tables de liaison V1 + +| Domaine | Tables | +|---|---| +| tags | `tag_preuves`, `tag_recherches`, `tag_entites`, `tag_relations`, `tag_hypotheses`, `tag_chronologie` | +| recherches | `recherche_preuves`, `recherche_entites`, `recherche_relations`, `recherche_chronologie`, `recherche_hypotheses` | +| preuves | `preuve_entites`, `preuve_chronologie`, `relation_preuves` | +| chronologie | `entite_chronologie`, `relation_chronologie` | +| hypothèses | `hypothese_preuves`, `hypothese_entites`, `hypothese_relations` | + +--- + +# 8. Intégrité et sécurité des données + +## 8.1 Clés étrangères + +`database_open()` exécute : + +```sql +PRAGMA foreign_keys = ON; +``` + +Les stratégies observées sont : + +- `CASCADE` pour les objets strictement dépendants ; +- `RESTRICT` lorsque la suppression risquerait de casser l’historique ; +- `SET NULL` pour les références facultatives. + +## 8.2 Requêtes préparées + +Les valeurs variables de la couche Database et des DAO utilisent les fonctions +de préparation et de liaison. + +Les requêtes statiques sans donnée utilisateur peuvent être exécutées avec +`sqlite3_exec()`. + +La règle à conserver est : + +> aucune valeur externe ou utilisateur ne doit être concaténée dans une chaîne +> SQL. + +Le caractère append-only du journal ne constitue jamais une exception à cette +règle. + +## 8.3 Transactions + +Les migrations publiques V1 à V9 sont pilotées par des fonctions dédiées. + +Chaque passage de version : + +- démarre une transaction ; +- applique le changement ; +- met à jour la version ; +- commit en cas de succès ; +- rollback en cas d’échec. + +La création d’une base neuve est également atomique. + +## 8.4 Preuves + +Le schéma et la couche métier conservent notamment : + +- UUID ; +- chemin relatif ; +- nom interne ; +- nom original ; +- taille ; +- SHA-256 ; +- type MIME ; +- date du fichier ; +- date de collecte ; +- date d’import ; +- statut d’intégrité ; +- statut logique. + +Le fichier original reste dans l’arborescence de l’enquête. SQLite conserve ses +métadonnées et ses relations. + +## 8.5 Suppression logique + +Plusieurs objets V1 utilisent des statuts tels que : + +```text +active +archived +deleted +``` + +Certaines suppressions physiques existent néanmoins dans les DAO, notamment +pour les relations. + +Le document d’architecture doit donc éviter d’affirmer que toute suppression +est systématiquement logique. La stratégie réelle doit être documentée table +par table. + +## 8.6 Journal et chronologie + +Le schéma distingue : + +- `chronologie` : événements significatifs de l’enquête ; +- `journal` : trace technique des actions de l’application. + +Le journal est conçu comme append-only dans la documentation, mais cet audit +n’a pas identifié de trigger SQLite interdisant une mise à jour ou une +suppression. Cette propriété repose donc actuellement au moins en partie sur la +couche applicative. + +--- + +# 9. Correspondance SQL, modèles, DAO et tests + +| Domaine | Table principale | Modèle ou structure | DAO/service observé | Tests observés | +|---|---|---|---|---| +| enquête | `investigation` | `InvestigationRecord` | `InvestigationDao` | `test_investigation_record`, `test_investigation_dao` | +| preuves | `preuves` | `EvidenceRecord` | `EvidenceDao`, `EvidenceTypeDao` | nombreux tests preuve/import/intégrité | +| preuve-entité | `preuve_entites` | — | `EvidenceEntityDao` | `test_evidence_entity_dao` | +| entités | `entites` | `EntityRecord` | `EntityDao`, `EntityTypeDao` | tests modèle et DAO | +| relations | `relations` | `RelationRecord` | `RelationDao`, `RelationService` | tests DAO, modèle et service | +| types de relation | `relation_types` | `RelationType` | `RelationTypeDao`, `RelationTypeService` | normalisation et service | +| relation-preuve | `relation_preuves` | — | `RelationEvidenceDao` | `test_relation_evidence_dao` | +| provenance OSINT | `osint_executions` | `OsintExecutionRecord` | `OsintExecutionDao` | DAO et intégrité | +| extractions | `extractions` | contexte métier | `ExtractionDao`, service de dépôt | `test_extraction_drop_service` | +| positions graphe | tables de graphe | `GraphNodePosition`, layout | `GraphNodePositionDao` | `test_graph_node_position_dao` | +| comptes sociaux | `comptes_sociaux` | plateforme sociale | service compte social | `test_social_account_service` | +| personnes | `person_roles` | extension d’entité | service personne | `test_person_entity_service` | + +## Observation + +La V1 contient davantage de domaines que les DAO publics actuellement exposés. + +Aucun DAO dédié n’a été observé dans `include/dao/` pour plusieurs tables, dont : + +- `sources` ; +- `recherches` ; +- `hypotheses` ; +- `chronologie` ; +- `journal` ; +- `categories` ; +- `tags`. + +Cela ne signifie pas que ces tables sont inutilisables. Cela indique seulement +qu’aucune interface DAO publique dédiée n’est visible dans le dossier audité au +commit indiqué. + +--- + +# 10. Couverture de tests observée + +## 10.1 Points couverts par `test_database.c` + +Le fichier vérifie notamment : + +- l’initialisation d’une base valide ; +- le rollback d’une initialisation défaillante ; +- la présence de la version `9` dans une base neuve ; +- la présence de plusieurs tables ajoutées après V1 ; +- la migration d’une base V1 vers la version courante ; +- la conservation d’une preuve V1 ; +- le backfill V2 de `original_name` ; +- l’ajout des colonnes V2 ; +- l’ajout des triggers V2 ; +- le rollback complet d’une migration V2 provoquée en échec ; +- `PRAGMA integrity_check` après le rollback. + +## 10.2 Tests spécialisés observés + +Le dépôt possède également des tests pour : + +- les preuves et leur intégrité ; +- les entités ; +- les relations ; +- les types canoniques de relations ; +- les exécutions OSINT ; +- les extractions ; +- les positions du graphe ; +- les comptes sociaux ; +- les rôles des personnes. + +## 10.3 Lacunes de couverture à traiter + +Le test principal de migration ne fournit pas une fixture indépendante pour +chaque version V2 à V9. + +Il manque une matrice explicite de ce type : + +| Base d’entrée | Migration | Vérifications minimales | +|---|---|---| +| V1 | V1 → V9 | données, version, FK, intégrité | +| V2 | V2 → V9 | preuve V2 conservée | +| V3 | V3 → V9 | provenance OSINT conservée | +| V4 | V4 → V9 | comptes sociaux conservés | +| V5 | V5 → V9 | rôles conservés pendant reconstruction V6 | +| V6 | V6 → V9 | identité usurpée conservée | +| V7 | V7 → V9 | extractions conservées | +| V8 | V8 → V9 | viewport et positions conservés | +| V9 | réouverture | idempotence de `schema_current.sql` | + +Chaque fixture devrait vérifier au minimum : + +```sql +PRAGMA integrity_check; +PRAGMA foreign_key_check; +SELECT value FROM metadata WHERE key = 'schema_version'; +``` + +--- + +# 11. Constats d’audit + +## AUD-001 — Documentation courante restée en V1 + +**Sévérité : élevée** + +`docs/database/DATABASE_ARCHITECTURE.md` s’annonce encore comme : + +```text +Statut : Stable (V1) +Schéma : V1 +``` + +alors que le code public utilise V9. + +### Risque + +- confusion des développeurs ; +- erreurs des agents locaux ; +- mauvaise interprétation de l’état du projet ; +- décisions basées sur des structures historiques ; +- oubli des tables V2 à V9. + +### Action recommandée + +Créer : + +```text +docs/database/SCHEMA_AUDIT_CURRENT.md +``` + +et déplacer les audits historiques vers : + +```text +docs/database/audits/SCHEMA_AUDIT_V1.md +docs/database/audits/SCHEMA_AUDIT_V9.md +``` + +Le document courant doit indiquer le commit exact qu’il audite. + +--- + +## AUD-002 — V10 locale non représentée dans la branche publique + +**Sévérité : bloquante pour un audit « courant »** + +La branche publique s’arrête à V9 tandis que le dépôt local est annoncé en V10. + +### Action recommandée + +Avant de finaliser ce document : + +1. publier ou fournir les fichiers V10 ; +2. vérifier la constante courante ; +3. vérifier la chaîne de migration ; +4. vérifier les tests ; +5. compléter l’inventaire ; +6. remplacer le statut V9 par V10 ; +7. enregistrer le commit audité. + +--- + +## AUD-003 — Version courante dupliquée + +**Sévérité : moyenne** + +La version est définie deux fois : + +```c +DATABASE_SCHEMA_VERSION_CURRENT +DATABASE_SCHEMA_VERSION_CURRENT_TEXT +``` + +Les tests comparent aussi directement la chaîne `"9"`. + +### Risque + +Une future migration peut modifier une valeur et oublier l’autre. + +### Action recommandée + +Conserver une seule constante numérique et produire la représentation textuelle +au moment de l’écriture, ou centraliser les deux valeurs dans un fichier +d’interface unique couvert par une assertion de test. + +--- + +## AUD-004 — `schema_current.sql` mélange plusieurs responsabilités + +**Sévérité : moyenne** + +Le fichier sert à la fois à : + +- créer des structures manquantes ; +- maintenir la compatibilité ; +- migrer des positions ; +- supprimer les anciennes positions ; +- installer des triggers. + +### Risque + +Une opération supposée idempotente peut finir par modifier des données à chaque +ouverture. + +### Action recommandée + +Documenter chaque opération et ajouter un test exécutant +`schema_ensure_current()` plusieurs fois sur la même fixture. + +--- + +## AUD-005 — Contrôle des clés étrangères non généralisé + +**Sévérité : moyenne** + +La migration V9 exécute explicitement : + +```sql +PRAGMA foreign_key_check; +``` + +Aucun contrôle générique similaire n’a été observé dans le pilote commun de +toutes les migrations. + +### Action recommandée + +Exécuter un contrôle générique avant le commit de chaque migration, ou fournir +une justification documentée lorsqu’une migration ne le nécessite pas. + +--- + +## AUD-006 — Couverture de migration incomplète par version + +**Sévérité : élevée** + +Le test principal couvre : + +- création d’une base neuve ; +- migration V1 vers la version courante ; +- rollback V2. + +Il ne constitue pas une matrice complète de fixtures V2 à V9. + +### Action recommandée + +Ajouter une fixture synthétique minimale pour chaque version publiée et migrer +chacune vers la version courante. + +--- + +## AUD-007 — Absence de sauvegarde préalable observée + +**Sévérité : élevée pour des enquêtes réelles** + +Aucun appel de sauvegarde SQLite ou copie préalable n’a été observé dans +`database_migrate_to_latest()`. + +La transaction protège la cohérence logique, mais elle ne remplace pas une +copie de sécurité face à : + +- panne disque ; +- interruption brutale ; +- défaut SQLite ou système de fichiers ; +- erreur de migration non anticipée ; +- corruption déjà présente. + +### Action recommandée + +Avant toute migration d’une base existante : + +1. fermer ou stabiliser les accès concurrents ; +2. créer une sauvegarde cohérente ; +3. vérifier sa création ; +4. lancer la migration ; +5. conserver la sauvegarde tant que la validation n’est pas terminée. + +Cette fonctionnalité doit être testée uniquement sur des bases synthétiques. + +--- + +## AUD-008 — Ancienne et nouvelle identité du type de relation coexistent + +**Sévérité : moyenne** + +V9 conserve : + +```text +relations.type_relation +``` + +et ajoute : + +```text +relations.relation_type_id +``` + +La documentation du commit précise que la première colonne ne doit plus servir +d’identité. + +### Risque + +Un module ancien peut encore filtrer ou détecter les doublons par texte. + +### Action recommandée + +Auditer tous les producteurs et lecteurs de relations, puis ajouter un test +interdisant toute régression vers `type_relation` comme clé métier. + +La colonne historique pourra être supprimée dans une future migration seulement +après validation de toutes les anciennes bases et de tous les adaptateurs. + +--- + +## AUD-009 — Append-only non imposé par SQLite + +**Sévérité : faible à moyenne** + +Le journal est documenté comme append-only, mais aucun trigger interdisant +`UPDATE` ou `DELETE` n’a été identifié dans les scripts examinés. + +### Action recommandée + +Choisir explicitement l’une des deux politiques : + +- garantie applicative documentée et testée ; +- garantie SQLite par triggers de refus. + +Le document courant doit dire laquelle est réellement retenue. + +--- + +## AUD-010 — Paramètres SQLite de durabilité non documentés dans le code audité + +**Sévérité : à évaluer** + +Aucun réglage explicite n’a été identifié dans `database.c` pour : + +- `journal_mode` ; +- `synchronous` ; +- `busy_timeout`. + +SQLite applique donc probablement ses valeurs par défaut, sauf réglage réalisé +ailleurs. + +### Action recommandée + +Documenter volontairement les paramètres retenus et leurs conséquences avant +un usage opérationnel. + +Ne pas activer WAL ou modifier `synchronous` sans étudier la portabilité d’une +enquête et les procédures de copie de ses fichiers annexes. + +--- + +# 12. Exigences proposées pour la V10 + +La V10 doit être considérée incomplète tant que les éléments suivants ne sont +pas présents et cohérents. + +## 12.1 Code + +- `database/schema_v10.sql` +- `schema_install_v10()` +- `database_migrate_v9_to_v10()` +- cas `9` dans `database_migrate_to_latest()` +- installation V10 dans `database_initialize()` +- mise à jour de la version numérique +- mise à jour de la version textuelle ou suppression de cette duplication +- mise à jour du commentaire de `schema_current.sql` + +## 12.2 Intégrité + +- migration transactionnelle ; +- conservation des UUID ; +- conservation des preuves ; +- conservation des liaisons ; +- conservation de la provenance OSINT ; +- conservation des positions du graphe ; +- `PRAGMA foreign_key_check` avant commit ; +- version mise à jour uniquement après réussite ; +- rollback complet au premier échec. + +## 12.3 Tests + +- création d’une base neuve V10 ; +- migration V9 vers V10 ; +- migration V1 vers V10 ; +- fixture contenant des données réelles synthétiques de chaque domaine ; +- rollback V10 provoqué volontairement ; +- deuxième ouverture sans modification inattendue ; +- `PRAGMA integrity_check` ; +- `PRAGMA foreign_key_check` ; +- comparaison des objets SQLite attendus ; +- tests des DAO concernés. + +## 12.4 Documentation + +- mise à jour du présent audit ; +- résumé de la migration ; +- inventaire des tables et colonnes nouvelles ; +- ticket Forgejo associé ; +- commit exact audité ; +- statut explicite : implémenté, partiel, futur, historique ou abandonné. + +--- + +# 13. Procédure de vérification reproductible + +> Utiliser uniquement une copie synthétique. +> Ne jamais exécuter cette procédure sur une base d’enquête réelle sans +> sauvegarde et validation préalable. + +## 13.1 Compilation + +```bash +make clean +make -j8 +make -j8 test +git diff --check +``` + +En cas d’échec provoqué par la parallélisation, revenir temporairement à : + +```bash +make +make test +``` + +## 13.2 Création d’une base synthétique + +Créer une enquête de test par l’API normale de l’application ou par un test +dédié, puis vérifier : + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT value FROM metadata WHERE key = 'schema_version';" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA integrity_check;" + +sqlite3 /chemin/test/Enquete.sqlite \ + "PRAGMA foreign_key_check;" +``` + +Résultats attendus : + +```text + +ok + +``` + +## 13.3 Inventaire du schéma + +```bash +sqlite3 /chemin/test/Enquete.sqlite \ + "SELECT type, name + FROM sqlite_master + WHERE name NOT LIKE 'sqlite_%' + ORDER BY type, name;" +``` + +## 13.4 Vérification de l’idempotence + +1. ouvrir la base ; +2. fermer la base ; +3. enregistrer un dump du schéma et les données de présentation ; +4. rouvrir la base plusieurs fois ; +5. comparer les résultats ; +6. vérifier les positions du graphe ; +7. vérifier les types de relations ; +8. exécuter à nouveau les deux PRAGMA d’intégrité. + +## 13.5 Vérification de migration + +Pour chaque fixture V1 à V9 : + +1. calculer une copie de travail ; +2. relever la version initiale ; +3. compter les objets métier ; +4. migrer ; +5. vérifier la version finale ; +6. comparer les UUID ; +7. comparer les empreintes des preuves ; +8. comparer les liaisons ; +9. vérifier les contraintes ; +10. vérifier le rollback sur une copie volontairement invalide. + +--- + +# 14. Règle de maintenance proposée + +Toute nouvelle version du schéma doit livrer ensemble : + +```text +migration SQL ++ fonction d’installation ++ fonction de migration ++ incrément de version ++ tests de base neuve ++ tests d’ancienne base ++ test de rollback ++ contrôle d’intégrité ++ mise à jour de SCHEMA_AUDIT_CURRENT.md ++ ticket Forgejo ++ commit vérifiable +``` + +Un ticket de migration ne doit pas être fermé tant que cette chaîne n’est pas +complète. + +## Statuts documentaires obligatoires + +Chaque table, colonne ou fonctionnalité mentionnée dans la documentation devrait +porter l’un des statuts suivants : + +```text +IMPLÉMENTÉ +PARTIELLEMENT IMPLÉMENTÉ +DOCUMENTÉ MAIS NON IMPLÉMENTÉ +HISTORIQUE +ABANDONNÉ +``` + +Cette règle évitera de confondre : + +- une architecture cible ; +- un ancien audit ; +- une fonctionnalité réellement présente ; +- un ticket encore ouvert ; +- une migration locale non publiée. + +--- + +# 15. Conclusion + +Le schéma public V9 repose sur une base technique sérieuse : + +- modèle relationnel riche ; +- versionnement explicite ; +- migrations transactionnelles ; +- provenance OSINT ; +- contraintes sur les preuves ; +- normalisation des types de relations ; +- séparation des données métier et de l’état du graphe ; +- tests nombreux autour des DAO et services. + +Le problème principal n’est plus l’absence de structure. + +Le problème principal est désormais **l’écart entre le code et la +documentation de référence**. + +`SCHEMA_AUDIT_V1.md` reste utile comme document historique, mais ne doit plus +servir à déterminer l’état courant. + +La prochaine étape correcte est : + +1. fournir ou publier la V10 ; +2. auditer le delta V9 → V10 ; +3. exécuter la procédure reproductible sur des données synthétiques ; +4. remplacer le présent statut de brouillon par un audit V10 validé ; +5. conserver l’audit V9 dans un dossier historique. + +--- + +# 16. Références du dépôt + +## Commit public audité + +```text +8bc3b43d63f4bd3da673ddf86a7e4b7a81e28604 +feat(relations): centraliser les types et améliorer les aperçus +``` + +## Ticket principal lié à V9 + +```text +#106 — Normaliser et centraliser les types de relations +État : fermé +``` + +## Documents historiques + +```text +docs/database/DATABASE_ARCHITECTURE.md +docs/database/SCHEMA_AUDIT_V1.md +``` + +## Fichiers constituant la source de vérité technique publique + +```text +database/schema_v1.sql +database/schema_v2.sql +database/schema_v3.sql +database/schema_v4.sql +database/schema_v5.sql +database/schema_v6.sql +database/schema_v7.sql +database/schema_v8.sql +database/schema_v9.sql +database/schema_current.sql + +src/database/database.c +src/database/schema.c +src/database/statement.c +src/database/transaction.c + +include/database/database.h +include/database/schema.h + +tests/test_database.c +tests/test_statement.c +tests/test_transaction.c +``` diff --git a/meline59760.txt b/meline59760.txt deleted file mode 100644 index 8c8d031..0000000 --- a/meline59760.txt +++ /dev/null @@ -1,4 +0,0 @@ -https://forum.velomania.ru/member.php?username=meline59760 -https://www.youtube.com/@meline59760 -https://www.baby.ru/u/meline59760 -Total Websites Username Detected On : 3 diff --git a/watch_20260723-211101 b/watch_20260723-211101 deleted file mode 100644 index 18a636d..0000000 --- a/watch_20260723-211101 +++ /dev/null @@ -1,5 +0,0 @@ -NAME ID SIZE PROCESSOR CONTEXT UNTIL - - total utilisé libre partagé tamp/cache disponible -Mem: 14Gi 5,1Gi 7,9Gi 70Mi 2,2Gi 9,8Gi -Échange: 4,0Gi 3,8Gi 224Mi