labfy-investigation/docs/DOCUMENTATION_AUDIT_V10.md

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 :

Version du schéma SQLite : V10

avec un lien vers :

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 :

#107 — Pivot e-mail forensique

Le ticket #42 reste l’inventaire permanent des outils OSINT.

Corriger les commandes de validation

Utiliser :

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 :

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

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

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 :

IMPLÉMENTÉ
PARTIEL
PRÉVU
HISTORIQUE

---

4. docs/DEVELOPMENT.md

Incohérences avec le Makefile

Cible make docs

Le document mentionne :

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 :

-Wpedantic

Le Makefile principal utilise globalement :

-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 :

architecture en couches

avec services, DAO, tâches et adaptateurs.

Accès SQLite

Remplacer :

Toutes les opérations sur SQLite passent par la couche DAO.

par :

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 :

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 :

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 :

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 :

Un ticket terminé correspond à un commit.

par :

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 :

# 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 :

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 :

# 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 :

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 :

# 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 :

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 :

docs/database/audits/SCHEMA_AUDIT_V1.md

Ajouter en première ligne :

> [!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 :

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 :

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.