PD-237 - Retour d'Experience (REX)¶

1. References¶

Specification : PD-237-specification.md
Tests contractuels : PD-237-tests.md
Plan d'implementation : PD-237-plan.md
Acceptabilite : PD-237-acceptability.md
Commit evalue : 5e6bdc9 (branche dev)
Pipeline CI : https://gitlab.com/probatiovault/probatiovault-backend/-/pipelines/2286331531
Date de cloture : 2026-01-26

2. Synthese¶

Critere	Valeur
Verdict final	ACCEPTE
Tests contractuels	20/20 PASS
Tests totaux CI	3328 PASS
Ecarts bloquants	0 (E-01 resolu)
Ecarts majeurs	0
Ecarts mineurs	0

La User Story PD-237 a ete livree conformement a la specification. Tous les invariants (INV-BE-01 a INV-BE-05) et criteres d'acceptation (CA-01 a CA-06) sont couverts par des tests executables en CI.

3. Conformite specification vs implementation¶

3.1 Invariants¶

ID	Invariant	Mecanisme implemente	Conforme
INV-BE-01	Pas d'evenement en clair	DTO n'accepte que hashes (VARCHAR 64), pas de champ `event_data`	Oui
INV-BE-02	Preuve identique byte-to-byte	Stockage JSONB sans transformation, retour direct `inclusionProof`	Oui
INV-BE-03	Metadonnees immuables	Trigger SQL `BEFORE UPDATE` sur `merkle_trees`	Oui
INV-BE-04	Rejet mismatch metadonnees	Validation DTO + contrainte UNIQUE `(merkle_root, window_start, window_end)`	Oui
INV-BE-05	Append-only	Trigger SQL `BEFORE DELETE` + `BEFORE UPDATE`	Oui

3.2 Criteres d'acceptation¶

ID	Critere	Implementation	Conforme
CA-01	Payload complet requis	Validation `class-validator` + rollback atomique	Oui
CA-02	Preuve exacte	Pas de normalisation, stockage/retour brut	Oui
CA-03	Pas de clair	Schema sans colonnes texte libre	Oui
CA-04	Rejet incoherence	Codes ERR-MK-01..07 avec HTTP 400/403/404	Oui
CA-05	Immutabilite	Triggers append-only + pas d'endpoint DELETE/PATCH	Oui
CA-06	Recherche multi-arbres	Query `WHERE leaf_hash = ?` + `ORDER BY tree_id ASC`	Oui

3.3 Codes d'erreur contractuels¶

Code	HTTP	Implemente	Test
ERR-MK-01	400	Oui	TC-ERR-01
ERR-MK-02	400	Oui	TC-ERR-02, TC-ERR-08
ERR-MK-03	400	Oui	TC-ERR-03
ERR-MK-04	400	Oui	TC-ERR-04
ERR-MK-05	404	Oui	TC-ERR-05
ERR-MK-06	404	Oui	TC-ERR-06
ERR-MK-07	403	Oui	TC-ERR-07

4. Plan d'implementation vs realite¶

4.1 Phases realisees¶

Phase	Prevu	Realise	Ecart
Phase 1 : Schema et migrations	Schema `vault_merkle`, tables, triggers	Idem	Aucun
Phase 2 : Entites et DTOs	MerkleTree, MerkleLeaf, DTOs	Idem	Aucun
Phase 3 : Verification crypto	MerkleProofVerifier SHA-256	Idem	Aucun
Phase 4 : Service metier	MerkleTreeService avec validation	Idem	Aucun
Phase 5 : Controller	MerkleController REST	Idem	Aucun
Phase 6 : Erreurs et audit	MerkleException + AuditService	Idem	Aucun
Phase 7 : Tests	Unit + E2E + adversariaux	Idem (corrige en CI)	Voir section 5

4.2 Hypotheses validees¶

ID	Hypothese	Resultat
H-IMPL-01	SHA-256 seul supporte	Valide, config extensible
H-IMPL-02	Max 10 000 feuilles	Non stress-teste (hors scope)
H-IMPL-03	JSONB < 1MB	Respecte pour arbres de test
H-IMPL-04	Preuves fournies par appelant	Valide, rejet ERR-MK-04 si invalide

5. Difficultes rencontrees¶

5.1 Detection environnement CI pour tests E2E¶

Probleme : Les tests E2E etaient ignores en CI car le code ne detectait que la variable DB_HOST, alors que l'environnement CI utilise DATABASE_URL.

Symptome : Les tests TC-INV-03, TC-INV-05, TC-NR-01, TC-NR-02, TC-NEG-01, TC-NEG-02 apparaissaient comme "ABSENT" dans le document d'acceptabilite.

Resolution : Modification de describeIfDb pour verifier egalement DATABASE_URL :

const hasDbConnection = !!(process.env.DB_HOST || process.env.DATABASE_URL);

Fichiers impactes : - test/integration/merkle/merkle.e2e.spec.ts - test/integration/merkle/merkle-adversarial.e2e.spec.ts

5.2 Contrainte de duplication avec BDD persistante¶

Probleme : Les tests utilisaient une date fixe (2024-01-01) pour les fenetres temporelles. La base de donnees CI etant persistante entre les executions, les arbres existaient deja et causaient des erreurs 403 (ERR-MK-07 / contrainte UNIQUE violee).

Symptome : Tests en echec avec HTTP 403 au lieu de 201 lors de la persistance.

Resolution : Utilisation de Date.now() comme base pour generer des timestamps uniques a chaque execution :

const testRunId = Date.now();
const windowStart = new Date(testRunId + testCounter * 3600000).toISOString();

Fichiers impactes : - test/integration/merkle/merkle.e2e.spec.ts - test/integration/merkle/merkle-adversarial.e2e.spec.ts

5.3 Mutation partagee d'objet de test¶

Probleme : La fonction createValidRequest() retournait une reference vers l'objet partage validBatchMetadata. Quand un test modifiait payload.batch_metadata.xxx, il mutait l'objet global, causant des effets de bord sur les tests suivants.

Symptome : Tests recevant ERR-MK-03 (metadonnees incompletes) au lieu de ERR-MK-04 (cardinalite invalide), car batch_metadata.hash_algorithm_version avait ete supprime par un test precedent.

Resolution : Utilisation du spread operator pour creer une copie independante :

const createValidRequest = (): PersistTreeRequestDto => ({
  // ...
  batch_metadata: { ...validBatchMetadata }, // Copie, pas reference
});

Fichiers impactes : - test/integration/merkle/merkle.e2e.spec.ts - test/integration/merkle/merkle-adversarial.e2e.spec.ts

6. Enseignements¶

6.1 Bonnes pratiques identifiees¶

Pratique	Justification
Tests E2E en CI obligatoires	Les tests unitaires ne suffisent pas a valider les triggers SQL et transactions
Variables d'environnement multiples	Supporter `DB_HOST` ET `DATABASE_URL` pour compatibilite CI/local
Isolation des fixtures de test	Toujours copier les objets de test, ne jamais muter les references partagees
Timestamps dynamiques	Utiliser `Date.now()` pour eviter les collisions avec BDD persistante

6.2 Points d'attention pour futures US¶

Point	Recommandation
Detection environnement	Verifier systematiquement les variables CI (`DATABASE_URL`, `CI=true`)
Idempotence des tests	Les tests doivent pouvoir s'executer N fois sans echec
Contraintes UNIQUE	Prevoir des donnees de test uniques par execution
Mutation d'objets	Preferer `Object.freeze()` ou spread operator pour les fixtures

6.3 Dettes techniques identifiees¶

Dette	Criticite	Remediation
Pas de stress test 10k feuilles	Faible	A evaluer si usage intensif prevu
Un seul hash_algorithm_id	Faible	Factory pattern deja prevu (H-IMPL-01)
Pas de pagination GET /trees/:id	Faible	A implementer si arbres > 1000 feuilles

7. Impacts processus¶

7.1 Processus de validation¶

Etape	Observation	Amelioration proposee
Revue d'acceptabilite	Ecart E-01 identifie correctement	Aucune
Execution CI	Tests E2E non executes initialement	Ajouter check CI obligatoire pour tests E2E
Correction iterative	3 corrections necessaires (env, timestamps, mutation)	Revue de code tests avec focus isolation

7.2 Documentation¶

Document	Etat	Commentaire
Specification	Stable	Aucune modification necessaire
Plan d'implementation	Stable	Phases respectees
Tests contractuels	Stable	Couverture 100%
Acceptabilite	Mis a jour	Verdict ACCEPTE apres corrections

8. Metriques¶

Metrique	Valeur
Nombre de commits pour livraison	4 (initial + 3 corrections tests)
Tests contractuels	20
Tests unitaires Merkle	56
Tests E2E Merkle	12
Tests adversariaux	6
Couverture spec	100% invariants, 100% criteres
Lignes de code service	~480 (merkle-tree.service.ts)
Lignes de code verifier	~270 (merkle-proof-verifier.ts)

9. Conclusion¶

La User Story PD-237 est livree et acceptee. L'implementation est conforme a la specification canonique et tous les tests contractuels sont executes et valides en CI.

Les difficultes rencontrees (detection environnement CI, timestamps uniques, isolation des fixtures) sont des problemes d'infrastructure de test, non des ecarts fonctionnels. Les corrections apportees renforcent la robustesse de la suite de tests pour les futures livraisons.

Recommandation principale : Integrer une verification systematique de l'execution des tests E2E en CI dans le workflow d'acceptabilite pour eviter les ecarts de type E-01.

Document genere le 2026-01-26 Pipeline de reference : https://gitlab.com/probatiovault/probatiovault-backend/-/pipelines/2286331531