diff --git a/docs/database/DATABASE_ARCHITECTURE.md b/docs/database/DATABASE_ARCHITECTURE.md new file mode 100644 index 0000000..6b7da10 --- /dev/null +++ b/docs/database/DATABASE_ARCHITECTURE.md @@ -0,0 +1,2283 @@ +# 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 + +--- + +# 1. Introduction + +## 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 : + +```text +00_BaseDeDonnees/ +└── Enquete.sqlite +``` + +Toutes les informations propres à cette enquête sont enregistrées dans cette +base. + +Aucune information métier n'est partagée entre plusieurs enquêtes. + +Cette organisation présente plusieurs avantages : + +- 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. + +La base SQLite ne contient jamais les fichiers originaux. + +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. + +--- + +# 2. Principes généraux + +Cette section décrit les conventions utilisées dans toute la couche Database. + +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. + +--- + +## 2.1 UUID + +Tous les objets métier utilisent un identifiant unique universel (UUID) comme +clé primaire. + +Exemple : + +```sql +id TEXT PRIMARY KEY +``` + +Les UUID sont générés par l'application lors de la création des objets. + +Cette approche présente plusieurs avantages : + +- 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. + +Les tables de référence utilisent en revanche des identifiants entiers +statiques. + +Exemples : + +- `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 : + +```text +YYYY-MM-DDTHH:MM:SSZ +``` + +Exemple : + +```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. + +```sql +PRAGMA foreign_keys = ON; +``` + +Toutes les relations entre objets sont protégées par des contraintes +d'intégrité. + +Selon le contexte, les suppressions utilisent : + +- `CASCADE` ; +- `RESTRICT` ; +- `SET NULL`. + +Le choix dépend du rôle métier de la relation et non d'une règle unique. + +--- + +## 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. + +```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. + +--- + +## 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. + +--- + +# 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 + │ + ▼ +SQLite +``` + +Chaque niveau vérifie les données avant de les transmettre au niveau suivant. + +Cette approche permet : + +- 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. + +--- + +# 8. Index + +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. + +Ils permettent à SQLite de localiser rapidement les enregistrements recherchés +sans parcourir l'intégralité des tables. + +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. + +Le choix des index repose sur les usages attendus de Labfy Investigation et +non sur une optimisation prématurée. + +--- + +## 8.1 Objectifs + +Les index sont principalement utilisés pour accélérer les opérations suivantes : + +- 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. + +Ils permettent également de limiter le coût des nombreuses jointures entre les +tables métier. + +--- + +## 8.2 Politique + +Les index sont créés selon plusieurs principes. + +### Clés étrangères + +Les colonnes utilisées comme clés étrangères sont systématiquement indexées. + +Cette règle améliore les performances des jointures ainsi que les contrôles +d'intégrité réalisés par SQLite. + +--- + +### Dates + +Les colonnes utilisées pour les tris chronologiques sont indexées. + +Exemples : + +- `created_at` +- `updated_at` +- `event_time` + +Ces index facilitent la consultation des événements récents et des historiques +d'une enquête. + +--- + +### États + +Les colonnes `status` sont indexées lorsque leur utilisation est fréquente. + +Cela permet notamment de retrouver rapidement les objets : + +- actifs ; +- archivés ; +- supprimés logiquement. + +--- + +### Tables de liaison + +Les tables de liaison possèdent une clé primaire composite. + +Des index complémentaires peuvent être ajoutés lorsque les recherches sont +souvent réalisées dans le sens inverse de cette clé. + +Exemple : + +```sql +PRIMARY KEY ( + tag_id, + preuve_id +) +``` + +Un index supplémentaire sur : + +```sql +preuve_id +``` + +permet de retrouver rapidement tous les tags associés à une preuve. + +--- + +### Équilibre + +Chaque index améliore certaines requêtes mais augmente également : + +- la taille de la base de données ; +- le coût des insertions ; +- le coût des mises à jour. + +Les index sont donc créés uniquement lorsqu'ils répondent à un besoin +identifié. + +Aucun index n'est ajouté sans justification fonctionnelle. + +--- + +## 8.3 Évolution + +La politique d'indexation pourra évoluer à mesure que l'application grandira. + +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. + +--- + +# 9. Versionnement + +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. + +--- + +## 9.1 Version du schéma + +La version du schéma est enregistrée dans la table : + +```text +metadata +``` + +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. + +--- + +# 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. + +--- + +## 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/tickets/open/TICKET-024.md b/docs/tickets/open/TICKET-024.md new file mode 100644 index 0000000..82dae89 --- /dev/null +++ b/docs/tickets/open/TICKET-024.md @@ -0,0 +1,436 @@ +# Ticket #024 + +## Titre + +Documenter l'architecture de la base de données V1. + +--- + +## Objectif + +Créer une documentation de référence expliquant l'architecture SQLite V1 de +Labfy Investigation. + +Cette documentation doit permettre à un développeur de comprendre : + +- le rôle de chaque table ; +- les relations entre les objets métier ; +- les conventions d'identifiants ; +- les règles sur les dates ; +- la suppression logique ; +- les tables de liaison ; +- les contraintes d'intégrité ; +- la politique de versionnement du schéma. + +Le document ne doit pas recopier intégralement le SQL. + +Il doit expliquer le modèle et les décisions prises. + +--- + +## Livrable principal + +Créer : + +```text +docs/database/DATABASE_ARCHITECTURE.md +``` + +--- + +## Sources de référence + +La documentation doit rester cohérente avec : + +```text +database/schema_v1.sql +docs/database/SCHEMA_AUDIT_V1.md +docs/CONVENTIONS.md +``` + +En cas de contradiction, le schéma SQL exécuté fait foi jusqu'à correction de +la documentation. + +--- + +## Contenu attendu + +### 1. Vue d'ensemble + +Présenter le rôle de la base SQLite dans une enquête. + +Chaque enquête possède sa propre base : + +```text +00_BaseDeDonnees/Enquete.sqlite +``` + +La base est autonome et liée au dossier d'enquête. + +--- + +### 2. Principes généraux + +Documenter les choix suivants : + +- une base par enquête ; +- aucun chemin absolu dans les objets métier ; +- UUID pour les objets métier ; +- identifiants entiers pour les tables de référence ; +- dates UTC au format ISO 8601 ; +- clés étrangères activées ; +- suppression logique ; +- requêtes préparées obligatoires dans le code C ; +- aucune requête SQL métier hors du module Database. + +--- + +### 3. Domaines du modèle + +Présenter les grands ensembles : + +```text +Métadonnées +Référentiels +Collecte +Connaissance +Raisonnement +Traçabilité +Classification +``` + +Exemple de classement : + +```text +Métadonnées +├── metadata +└── investigation + +Référentiels +├── types_preuve +├── types_entite +├── types_source +└── types_outil + +Collecte +├── sources +├── recherches +└── preuves + +Connaissance +├── entites +└── relations + +Raisonnement +└── hypotheses + +Traçabilité +├── chronologie +└── journal + +Classification +├── categories +└── tags +``` + +--- + +### 4. Chaîne d'investigation + +Décrire le flux métier principal : + +```text +Source + ↓ +Recherche + ↓ +Preuve + ↓ +Entité + ↓ +Relation + ↓ +Hypothèse +``` + +Préciser que ce flux n'est pas strictement linéaire. + +Une recherche peut : + +- utiliser une preuve existante ; +- produire plusieurs preuves ; +- découvrir plusieurs entités ; +- confirmer ou contredire une relation ; +- enrichir une hypothèse. + +--- + +### 5. Description des tables métier + +Pour chaque table importante, documenter : + +- responsabilité ; +- identifiant ; +- colonnes principales ; +- relations ; +- suppression ; +- points d'attention. + +Tables concernées : + +```text +investigation +sources +recherches +preuves +entites +relations +chronologie +journal +hypotheses +categories +tags +``` + +--- + +### 6. Tables de liaison + +Documenter le rôle des tables de liaison : + +```text +recherche_preuves +recherche_entites +recherche_relations +recherche_hypotheses + +preuve_entites +relation_preuves + +recherche_chronologie +preuve_chronologie +entite_chronologie +relation_chronologie + +hypothese_preuves +hypothese_entites +hypothese_relations + +tag_preuves +tag_recherches +tag_entites +tag_relations +tag_hypotheses +tag_chronologie +``` + +Expliquer : + +- les clés primaires composites ; +- l'interdiction des doublons ; +- les colonnes `role` lorsqu'elles existent ; +- le comportement `ON DELETE`. + +--- + +### 7. Relations principales + +Inclure un diagramme textuel ou Mermaid. + +Exemple : + +```mermaid +erDiagram + SOURCES ||--o{ RECHERCHES : "interrogee par" + RECHERCHES ||--o{ RECHERCHE_PREUVES : produit + PREUVES ||--o{ RECHERCHE_PREUVES : participe + PREUVES ||--o{ PREUVE_ENTITES : contient + ENTITES ||--o{ PREUVE_ENTITES : est extraite + ENTITES ||--o{ RELATIONS : source + ENTITES ||--o{ RELATIONS : cible + HYPOTHESES ||--o{ HYPOTHESE_PREUVES : s_appuie_sur +``` + +Le diagramme peut être simplifié afin de rester lisible. + +--- + +### 8. Identifiants + +Expliquer : + +```sql +id TEXT PRIMARY KEY +``` + +pour les objets métier. + +Préciser : + +- UUID généré dans l'application ; +- pas de colonne `uuid` supplémentaire ; +- aucune dépendance aux numéros de ligne SQLite ; +- meilleure portabilité pour l'import, l'export et la fusion. + +--- + +### 9. Dates + +Expliquer la différence entre : + +```text +created_at +updated_at +imported_at +file_created_at +started_at +completed_at +event_time +``` + +Toutes les dates techniques sont enregistrées en UTC. + +--- + +### 10. Suppression logique + +Documenter les statuts comme : + +```text +active +archived +deleted +``` + +Préciser que : + +- les preuves originales ne sont pas modifiées ; +- les objets supprimés logiquement restent référencés ; +- les purges physiques sont hors des opérations ordinaires ; +- le journal est append-only dans le fonctionnement normal. + +--- + +### 11. Intégrité + +Documenter : + +- `PRAGMA foreign_keys = ON` ; +- contraintes `NOT NULL` ; +- contraintes `CHECK` ; +- contraintes `UNIQUE` ; +- clés primaires composites ; +- validation applicative complémentaire. + +Préciser que SQLite ne suffit pas à valider : + +- la syntaxe réelle d'un UUID ; +- la validité complète d'une couleur ; +- la normalisation d'une adresse email ; +- la validité d'un IBAN ; +- l'existence d'une référence polymorphe du journal. + +--- + +### 12. Index + +Expliquer que les index couvrent principalement : + +- les clés étrangères ; +- les statuts ; +- les dates ; +- les hashes ; +- les valeurs recherchées ; +- les catégories ; +- les relations orientées. + +Le document ne doit pas recopier chaque index sans explication. + +--- + +### 13. Versionnement + +Documenter : + +```text +schema_version = 1 +``` + +Préciser : + +- aucune modification destructive d'une V1 publiée ; +- toute évolution incompatible nécessite une migration ; +- les migrations devront être transactionnelles ; +- une sauvegarde devra précéder toute migration ; +- le schéma V1 reste la référence jusqu'à publication d'une V2. + +--- + +### 14. Couche C + +Documenter l'organisation prévue : + +```text +include/database/ +src/database/ +``` + +Avec un module par objet métier : + +```text +preuve.c +entite.c +relation.c +source.c +recherche.c +chronologie.c +journal.c +hypothese.c +categorie.c +tag.c +``` + +Le document doit préciser que cette organisation représente la cible +d'architecture, même si tous les modules ne sont pas encore implémentés. + +--- + +## Hors périmètre + +Ce ticket ne doit pas : + +- modifier le schéma SQL ; +- ajouter de table ; +- écrire un CRUD ; +- ajouter une migration ; +- modifier GTK ; +- intégrer GResource ; +- modifier le packaging. + +Toute incohérence réellement détectée doit être documentée avant de faire +l'objet d'un ticket de correction séparé. + +--- + +## Critères d'acceptation + +- [ ] `DATABASE_ARCHITECTURE.md` existe. +- [ ] Le rôle de chaque table métier est expliqué. +- [ ] Les tables de liaison sont documentées. +- [ ] Les UUID sont expliqués. +- [ ] Les dates sont expliquées. +- [ ] La suppression logique est expliquée. +- [ ] Les contraintes d'intégrité sont expliquées. +- [ ] La politique de migrations est définie. +- [ ] Un diagramme global est présent. +- [ ] Le document est cohérent avec `schema_v1.sql`. +- [ ] Aucun changement fonctionnel n'est introduit. +- [ ] `make test` reste entièrement valide. + +--- + +## Commit attendu + +```text +docs(database): document v1 database architecture +```