fy59/labfy-investigation

Fork 0

grayTerminal-sh c2df647b46 docs(database): document v1 database architecture

2026-07-15 23:37:11 +02:00

7.4 KiB

Raw Blame History

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 :

docs/database/DATABASE_ARCHITECTURE.md

Sources de référence

La documentation doit rester cohérente avec :

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 :

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 :

Métadonnées
Référentiels
Collecte
Connaissance
Raisonnement
Traçabilité
Classification

Exemple de classement :

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 :

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 :

investigation
sources
recherches
preuves
entites
relations
chronologie
journal
hypotheses
categories
tags

6. Tables de liaison

Documenter le rôle des tables de liaison :

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 :

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 :

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 :

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 :

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