labfy-investigation/docs/tickets/closed/TICKET-025.md

Ticket #025

Titre

Refactoriser la couche Database et établir l'infrastructure d'accès aux données.

---

Objectif

Mettre en place l'architecture définitive de la couche Database afin de fournir une API interne homogène pour tous les futurs modules métier.

Ce ticket ne comprend aucun CRUD métier.

Son objectif est uniquement de construire les fondations techniques qui seront réutilisées par l'ensemble de l'application.

---

Motivations

À terme, Labfy Investigation manipulera de nombreux objets métier :

• investigations ;
• sources ;
• recherches ;
• preuves ;
• entités ;
• relations ;
• chronologie ;
• journal ;
• hypothèses ;
• catégories ;
• tags.

Sans une couche d'abstraction, chaque module devrait manipuler directement SQLite, ce qui entraînerait :

• une forte duplication de code ;
• une gestion incohérente des erreurs ;
• des transactions difficiles à maintenir ;
• une architecture difficile à faire évoluer.

L'objectif de ce ticket est d'éviter cette dette technique.

---

Architecture cible

La couche Database devra évoluer vers l'organisation suivante :

include/database/
├── database.h
├── connection.h
├── transaction.h
├── statement.h
├── error.h
├── schema.h

src/database/
├── database.c
├── connection.c
├── transaction.c
├── statement.c
├── error.c
├── schema.c

Les futurs modules métier seront ajoutés ultérieurement.

---

Structure Database

Créer un type opaque :

typedef struct Database Database;

L'implémentation reste privée.

La structure interne contiendra au minimum :

• le pointeur sqlite3 *;
• le chemin de la base ;
• l'état de la transaction ;
• la version du schéma.

Cette abstraction permettra de faire évoluer facilement l'implémentation sans modifier l'API publique.

---

Connexion

Créer les fonctions :

Database *database_open(
    const char *database_path
);

void database_close(
    Database *database
);

Ces fonctions sont responsables de :

• l'ouverture de SQLite ;
• l'activation des PRAGMA nécessaires ;
• la fermeture propre de la base.

---

Transactions

Créer les fonctions :

bool database_begin(
    Database *database
);

bool database_commit(
    Database *database
);

bool database_rollback(
    Database *database
);

Toute gestion des transactions devra passer exclusivement par ces fonctions.

---

Gestion des requêtes préparées

Créer une couche d'abstraction pour les instructions préparées.

L'objectif est de centraliser :

• sqlite3_prepare_v2()
• sqlite3_bind_*()
• sqlite3_step()
• sqlite3_reset()
• sqlite3_finalize()

Aucun futur module métier ne devra appeler directement ces fonctions SQLite.

---

Gestion des erreurs

Créer un point d'entrée unique pour les erreurs SQLite.

Toutes les erreurs devront passer par une fonction dédiée.

Cette centralisation facilitera :

• le débogage ;
• la journalisation ;
• l'intégration future avec le journal d'audit.

---

Responsabilités

À la fin du ticket :

• la couche Database est la seule autorisée à manipuler SQLite ;
• les autres modules ne connaissent pas sqlite3;
• les transactions sont centralisées ;
• les erreurs sont uniformisées ;
• les requêtes préparées sont encapsulées.

---

Hors périmètre

Ce ticket ne doit pas :

• ajouter de nouvelles tables ;
• modifier le schéma SQL ;
• créer un CRUD métier ;
• modifier GTK ;
• implémenter des migrations ;
• ajouter des fonctionnalités d'investigation.

---

Critères d'acceptation

• Création du type opaque Database.
• API publique de connexion disponible.
• API publique des transactions disponible.
• Encapsulation des requêtes préparées.
• Gestion centralisée des erreurs.
• Aucune utilisation directe de sqlite3 en dehors du dossier database.
• Documentation des nouvelles API.
• Tous les tests existants restent valides.

---

Commit attendu

refactor(database): introduce database infrastructure layer