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