568 lines
12 KiB
Markdown
568 lines
12 KiB
Markdown
# Guide de développement
|
|
|
|
> **Version :** 2.0
|
|
> **Dernière mise à jour :** 2026-07-24
|
|
> **Projet :** Labfy Investigation
|
|
|
|
---
|
|
|
|
## 1. Objet
|
|
|
|
Ce document décrit l'environnement et le workflow de développement.
|
|
|
|
Les règles d'architecture se trouvent dans :
|
|
|
|
```text
|
|
docs/ARCHITECTURE.md
|
|
docs/CONVENTIONS.md
|
|
docs/database/DATABASE_ARCHITECTURE.md
|
|
```
|
|
|
|
Forgejo est la source de vérité des tickets :
|
|
|
|
```text
|
|
https://git.labfytools.com/fy59/labfy-investigation/issues
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Environnements
|
|
|
|
### 2.1 Environnement principal
|
|
|
|
Le développement courant est réalisé sous Arch Linux.
|
|
|
|
### 2.2 Cible de distribution
|
|
|
|
Ubuntu est la cible principale de distribution, notamment pour un futur
|
|
déploiement dans des environnements institutionnels.
|
|
|
|
Le code ne doit pas dépendre d'un paquet AUR.
|
|
|
|
Les dépendances optionnelles doivent se désactiver proprement lorsqu'elles sont
|
|
absentes.
|
|
|
|
### 2.3 Interface graphique
|
|
|
|
Le projet utilise GTK4 et doit rester compatible avec Wayland et X11 lorsque
|
|
GTK le permet.
|
|
|
|
Aucune hypothèse ne doit dépendre de la présence d'une barre de titre fournie
|
|
par le gestionnaire de fenêtres.
|
|
|
|
---
|
|
|
|
## 3. Dépendances de compilation
|
|
|
|
Le Makefile utilise `pkg-config` pour GTK4 et SQLite.
|
|
|
|
### Arch Linux
|
|
|
|
```sh
|
|
sudo pacman -S --needed \
|
|
base-devel \
|
|
pkgconf \
|
|
gtk4 \
|
|
glib2 \
|
|
sqlite
|
|
```
|
|
|
|
### Ubuntu
|
|
|
|
```sh
|
|
sudo apt update
|
|
sudo apt install \
|
|
build-essential \
|
|
pkg-config \
|
|
libgtk-4-dev \
|
|
libglib2.0-dev \
|
|
libsqlite3-dev
|
|
```
|
|
|
|
Les versions minimales exactes doivent correspondre aux API réellement utilisées
|
|
dans le code. Elles ne doivent pas être inventées dans la documentation si le
|
|
système de build ne les impose pas.
|
|
|
|
Les outils OSINT, OCR, métadonnées ou PDF sont documentés séparément et restent
|
|
optionnels sauf décision explicite.
|
|
|
|
---
|
|
|
|
## 4. Récupération du dépôt
|
|
|
|
```sh
|
|
git clone https://git.labfytools.com/fy59/labfy-investigation.git
|
|
cd labfy-investigation
|
|
```
|
|
|
|
Avant de commencer :
|
|
|
|
```sh
|
|
git status
|
|
git pull --ff-only
|
|
```
|
|
|
|
Ne pas écraser un travail local non validé.
|
|
|
|
---
|
|
|
|
## 5. Compilation
|
|
|
|
### 5.1 Compilation recommandée
|
|
|
|
```sh
|
|
make -j8
|
|
```
|
|
|
|
Le projet utilise globalement :
|
|
|
|
```text
|
|
-std=c17
|
|
-Wall
|
|
-Wextra
|
|
-Werror
|
|
```
|
|
|
|
Plusieurs cibles de tests ajoutent `-Wpedantic`.
|
|
|
|
### 5.2 Compilation séquentielle
|
|
|
|
Utiliser une compilation séquentielle seulement lorsque l'exécution parallèle
|
|
provoque un échec réel et identifié :
|
|
|
|
```sh
|
|
make
|
|
```
|
|
|
|
Une erreur de code ne doit pas être masquée en supprimant simplement `-j8`.
|
|
|
|
### 5.3 Nettoyage
|
|
|
|
```sh
|
|
make clean
|
|
```
|
|
|
|
### 5.4 Lancement
|
|
|
|
```sh
|
|
make run
|
|
```
|
|
|
|
ou :
|
|
|
|
```sh
|
|
./labfy-investigation
|
|
```
|
|
|
|
### 5.5 Documentation générée
|
|
|
|
Le Makefile courant ne fournit pas de cible `make docs`.
|
|
|
|
Ne pas documenter ou utiliser cette commande tant qu'une cible réelle n'a pas
|
|
été ajoutée et testée.
|
|
|
|
---
|
|
|
|
## 6. Tests
|
|
|
|
### 6.1 Suite complète
|
|
|
|
```sh
|
|
make -j8 test
|
|
```
|
|
|
|
En cas de problème réellement causé par la parallélisation :
|
|
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
### 6.2 Test ciblé
|
|
|
|
Les tests sont des exécutables dans `tests/`.
|
|
|
|
Exemple :
|
|
|
|
```sh
|
|
make tests/test_database
|
|
./tests/test_database
|
|
```
|
|
|
|
Autre exemple :
|
|
|
|
```sh
|
|
make tests/test_eml_pipeline_task
|
|
./tests/test_eml_pipeline_task
|
|
```
|
|
|
|
Le nom exact d'une cible doit être vérifié dans le Makefile.
|
|
|
|
### 6.3 Validation avant intégration
|
|
|
|
```sh
|
|
make clean
|
|
make -j8
|
|
make -j8 test
|
|
git diff --check
|
|
```
|
|
|
|
Vérifier également :
|
|
|
|
```sh
|
|
git status --short
|
|
```
|
|
|
|
Aucun fichier de preuve réel, base réelle ou artefact temporaire ne doit
|
|
apparaître.
|
|
|
|
---
|
|
|
|
## 7. Workflow d'un ticket
|
|
|
|
### 7.1 Avant de coder
|
|
|
|
1. lire le ticket Forgejo ;
|
|
2. vérifier l'état de la branche `main` ;
|
|
3. identifier les modules concernés ;
|
|
4. lire les tests existants ;
|
|
5. vérifier les migrations si SQLite est concerné ;
|
|
6. distinguer clairement ce qui est déjà implémenté de ce qui est seulement
|
|
demandé ;
|
|
7. préparer uniquement des données synthétiques.
|
|
|
|
### 7.2 Pendant le développement
|
|
|
|
1. limiter le changement à un objectif cohérent ;
|
|
2. compiler régulièrement ;
|
|
3. ajouter les tests au fur et à mesure ;
|
|
4. conserver une API claire ;
|
|
5. respecter les propriétaires mémoire ;
|
|
6. éviter toute logique métier dans GTK ;
|
|
7. ne pas créer une seconde architecture concurrente ;
|
|
8. ne pas toucher aux données réelles d'enquête.
|
|
|
|
### 7.3 Avant le commit
|
|
|
|
1. lancer la validation complète ;
|
|
2. relire le diff ;
|
|
3. vérifier les erreurs et chemins de rollback ;
|
|
4. vérifier la documentation ;
|
|
5. vérifier l'absence de données sensibles ;
|
|
6. demander la validation manuelle prévue par le workflow.
|
|
|
|
Aucun commit n'est effectué tant que la fonction ne marche pas.
|
|
|
|
---
|
|
|
|
## 8. Organisation des modules
|
|
|
|
```text
|
|
include/core/ interfaces du cœur et des services
|
|
include/dao/ interfaces des DAO
|
|
include/database/ interfaces SQLite
|
|
include/models/ interfaces des modèles
|
|
include/views/ interfaces des vues GTK
|
|
include/widgets/ interfaces des widgets
|
|
|
|
src/core/ services, tâches et orchestration
|
|
src/dao/ accès métier à SQLite
|
|
src/database/ connexion, schéma, statements, transactions
|
|
src/models/ modèles métier
|
|
src/views/ fenêtres et dialogues GTK
|
|
src/widgets/ widgets réutilisables
|
|
```
|
|
|
|
### Ajouter un modèle
|
|
|
|
Un modèle doit généralement fournir :
|
|
|
|
- un header dans `include/models/` ;
|
|
- une implémentation dans `src/models/` ;
|
|
- des constructeurs et destructeurs clairs ;
|
|
- des validations ;
|
|
- un test dans `tests/`.
|
|
|
|
Il ne dépend pas de GTK ni de SQLite.
|
|
|
|
### Ajouter un DAO
|
|
|
|
Un DAO doit généralement fournir :
|
|
|
|
- une interface dans `include/dao/` ;
|
|
- une implémentation dans `src/dao/` ;
|
|
- des statements préparés ;
|
|
- une transformation explicite ligne ↔ modèle ;
|
|
- des tests sur une base temporaire ;
|
|
- des erreurs structurées.
|
|
|
|
Il ne contient pas de logique GTK ni d'exécution d'outil.
|
|
|
|
### Ajouter un service
|
|
|
|
Un service est approprié lorsqu'une opération combine :
|
|
|
|
- plusieurs DAO ;
|
|
- une transaction ;
|
|
- le système de fichiers ;
|
|
- une validation métier ;
|
|
- un résultat composé.
|
|
|
|
Le service définit la frontière transactionnelle.
|
|
|
|
### Ajouter une tâche
|
|
|
|
Une tâche est appropriée lorsque l'opération peut bloquer l'interface.
|
|
|
|
Elle doit définir :
|
|
|
|
- ses entrées copiées ou référencées clairement ;
|
|
- son annulation ;
|
|
- son résultat ;
|
|
- son erreur ;
|
|
- son nettoyage ;
|
|
- la remise du résultat au thread principal.
|
|
|
|
### Ajouter une vue ou un widget
|
|
|
|
Une vue GTK :
|
|
|
|
- collecte l'intention de l'utilisateur ;
|
|
- appelle un contrôleur ou un service ;
|
|
- présente le résultat ;
|
|
- ne manipule pas directement SQLite ;
|
|
- ne lance pas de processus ;
|
|
- ne déplace pas directement les preuves.
|
|
|
|
---
|
|
|
|
## 9. Développement SQLite
|
|
|
|
### 9.1 Avant toute modification
|
|
|
|
Lire :
|
|
|
|
```text
|
|
docs/database/DATABASE_ARCHITECTURE.md
|
|
docs/database/SCHEMA_AUDIT_CURRENT.md
|
|
database/schema_current.sql
|
|
database/schema_v10.sql
|
|
src/database/database.c
|
|
src/database/schema.c
|
|
tests/test_database.c
|
|
```
|
|
|
|
### 9.2 Nouvelle version de schéma
|
|
|
|
Pour créer V11, par exemple :
|
|
|
|
1. ajouter `database/schema_v11.sql` ;
|
|
2. déclarer et implémenter `schema_install_v11()` ;
|
|
3. ajouter `database_migrate_v10_to_v11()` ;
|
|
4. raccorder la migration dans la boucle vers la version courante ;
|
|
5. mettre à jour les constantes de version ;
|
|
6. installer V11 lors de la création d'une base neuve ;
|
|
7. adapter `schema_current.sql` si nécessaire ;
|
|
8. ajouter une fixture V10 vers V11 ;
|
|
9. tester une base neuve ;
|
|
10. tester le rollback ;
|
|
11. vérifier l'intégrité et les clés étrangères ;
|
|
12. mettre à jour l'audit courant ;
|
|
13. créer l'audit versionné de V11.
|
|
|
|
Ne pas réécrire une ancienne migration publiée pour changer sa signification.
|
|
|
|
### 9.3 Vérifications SQLite
|
|
|
|
Sur une base synthétique :
|
|
|
|
```sql
|
|
PRAGMA integrity_check;
|
|
PRAGMA foreign_key_check;
|
|
SELECT value
|
|
FROM metadata
|
|
WHERE key = 'schema_version';
|
|
```
|
|
|
|
### 9.4 Transactions et fichiers
|
|
|
|
Lorsqu'une opération combine SQLite et le système de fichiers :
|
|
|
|
- préparer les fichiers temporaires ;
|
|
- vérifier les empreintes ;
|
|
- ouvrir la transaction au moment approprié ;
|
|
- ne valider qu'après toutes les étapes critiques ;
|
|
- nettoyer ou restaurer les fichiers en cas d'échec ;
|
|
- tester explicitement le rollback.
|
|
|
|
---
|
|
|
|
## 10. Outils externes
|
|
|
|
Avant d'intégrer un outil :
|
|
|
|
1. vérifier sa licence ;
|
|
2. vérifier son usage légal ;
|
|
3. vérifier sa disponibilité Arch et Ubuntu ;
|
|
4. documenter son caractère obligatoire ou optionnel ;
|
|
5. ajouter sa détection au registre si nécessaire ;
|
|
6. utiliser `GSubprocess` ;
|
|
7. transmettre les arguments séparément ;
|
|
8. définir un délai maximal ;
|
|
9. gérer l'annulation ;
|
|
10. limiter la taille des sorties ;
|
|
11. conserver la provenance ;
|
|
12. tester son absence.
|
|
|
|
Interdit :
|
|
|
|
```c
|
|
system(command);
|
|
```
|
|
|
|
Interdit également de construire une chaîne puis de l'exécuter via un shell.
|
|
|
|
Une dépendance absente doit produire un statut clair, pas un plantage.
|
|
|
|
---
|
|
|
|
## 11. GTK4
|
|
|
|
### 11.1 Thread principal
|
|
|
|
Seul le thread GTK principal modifie les widgets.
|
|
|
|
Les résultats d'une tâche sont transférés vers ce thread par les mécanismes
|
|
GLib adaptés.
|
|
|
|
### 11.2 Dialogues
|
|
|
|
Un dialogue :
|
|
|
|
- valide ses entrées ;
|
|
- ne conserve pas de pointeur vers une session détruite ;
|
|
- permet l'annulation ;
|
|
- ne réalise pas une opération longue directement ;
|
|
- présente un résumé avant une écriture importante.
|
|
|
|
### 11.3 Messages utilisateur
|
|
|
|
Les détails techniques restent dans les journaux.
|
|
|
|
Le message graphique indique :
|
|
|
|
- ce qui a échoué ;
|
|
- les conséquences ;
|
|
- ce qui a été conservé ou annulé ;
|
|
- l'action possible.
|
|
|
|
---
|
|
|
|
## 12. Mémoire et diagnostic
|
|
|
|
Compiler avec les avertissements activés est obligatoire.
|
|
|
|
Pour une erreur mémoire, utiliser les outils disponibles localement sans
|
|
modifier durablement les options du dépôt.
|
|
|
|
Exemple avec Valgrind lorsque l'application et l'environnement le permettent :
|
|
|
|
```sh
|
|
valgrind \
|
|
--leak-check=full \
|
|
--show-leak-kinds=all \
|
|
./tests/test_cible
|
|
```
|
|
|
|
Les faux positifs provenant de bibliothèques externes doivent être distingués
|
|
des allocations du projet.
|
|
|
|
Une tâche annulée, une erreur SQLite et un échec de processus doivent tous
|
|
libérer leurs ressources.
|
|
|
|
---
|
|
|
|
## 13. Données de test et sécurité
|
|
|
|
Le dépôt et les agents de développement utilisent uniquement des fixtures
|
|
synthétiques.
|
|
|
|
Ne jamais fournir à un agent local ou versionner :
|
|
|
|
```text
|
|
Enquete.sqlite réelle
|
|
captures réelles
|
|
conversations réelles
|
|
e-mails réels
|
|
RIB ou IBAN réels
|
|
pièces jointes réelles
|
|
documents d'identité réels
|
|
sorties OSINT contenant des données personnelles réelles
|
|
```
|
|
|
|
Les tests doivent utiliser :
|
|
|
|
- domaines réservés comme `example.com` ;
|
|
- adresses IP de documentation ;
|
|
- noms fictifs ;
|
|
- IBAN de test explicitement synthétiques ;
|
|
- fichiers générés pendant le test ;
|
|
- bases SQLite temporaires.
|
|
|
|
Avant chaque commit :
|
|
|
|
```sh
|
|
git diff --check
|
|
git status --short
|
|
```
|
|
|
|
Inspecter tout nouveau fichier inhabituel à la racine du dépôt.
|
|
|
|
---
|
|
|
|
## 14. Git
|
|
|
|
Les messages de commit sont en anglais.
|
|
|
|
Format recommandé :
|
|
|
|
```text
|
|
type(scope): description
|
|
```
|
|
|
|
Exemples :
|
|
|
|
```text
|
|
feat(email): add MIME attachment extraction
|
|
fix(database): rollback failed V10 migration
|
|
test(relations): cover canonical type reuse
|
|
docs(architecture): align documentation with V10
|
|
```
|
|
|
|
Un ticket peut être découpé en plusieurs commits cohérents.
|
|
|
|
Ne pas ajouter manuellement un numéro dans le titre d'un nouveau ticket :
|
|
Forgejo le fournit.
|
|
|
|
Ne pas effectuer de commit ou de push avant la validation manuelle prévue par
|
|
le workflow du projet.
|
|
|
|
---
|
|
|
|
## 15. Revue finale
|
|
|
|
Avant de considérer une modification terminée :
|
|
|
|
- [ ] le code respecte C17 ;
|
|
- [ ] les dépendances entre couches sont correctes ;
|
|
- [ ] la propriété mémoire est claire ;
|
|
- [ ] les erreurs sont remontées ;
|
|
- [ ] les opérations longues sont asynchrones ;
|
|
- [ ] les requêtes utilisent des paramètres liés ;
|
|
- [ ] les transactions possèdent un rollback testé ;
|
|
- [ ] les preuves originales restent intactes ;
|
|
- [ ] les valeurs brutes restent intactes ;
|
|
- [ ] les tests utilisent des données synthétiques ;
|
|
- [ ] `make -j8` passe ;
|
|
- [ ] `make -j8 test` passe ;
|
|
- [ ] `git diff --check` passe ;
|
|
- [ ] la documentation est à jour.
|