fy59/labfy-investigation

Fork 0

Documenter l'architecture de la base de données V1. #25

New issue

Closed

opened 2026-07-18 08:43:45 +02:00 by fy59 · 0 comments

fy59 commented

2026-07-18 08:43:45 +02:00

Owner

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

Documenter :

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 :

include/database/
src/database/

Avec un module par objet métier :

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

docs(database): document v1 database architecture

## 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 - [x] `DATABASE_ARCHITECTURE.md` existe. - [x] Le rôle de chaque table métier est expliqué. - [x] Les tables de liaison sont documentées. - [x] Les UUID sont expliqués. - [x] Les dates sont expliquées. - [x] La suppression logique est expliquée. - [x] Les contraintes d'intégrité sont expliquées. - [x] La politique de migrations est définie. - [x] Un diagramme global est présent. - [x] Le document est cohérent avec `schema_v1.sql`. - [x] Aucun changement fonctionnel n'est introduit. - [x] `make test` reste entièrement valide. --- ## Commit attendu ```text docs(database): document v1 database architecture ```

TICKET-024.md

7.4 KiB