Aller au contenu

PD-236 — Retour d'expérience (REX)

1. Résumé exécutif

Objectif initial : Implémenter la consommation backend des tokens de recherche déterministes (T_kw) conformément à PD-42, avec indexation, persistance et recherche server-side par égalité stricte.

Résultat obtenu : Module TokenSearchModule fonctionnel avec 10 suites de tests, 135 tests PASS. Couverture : Statements 88.6%, Branches 84.13%, Lines 90.11%.

Verdict d'acceptabilité : ✅ ACCEPTÉ (après résolution des écarts E-01, E-02, E-03 identifiés lors de la première revue).

État des tests contractuels : - TC-NOM-01..04 : PASS - TC-ERR-01..05 : PASS - TC-INV-01..04 : PASS - TC-INV-05 : NON TESTABLE (conformément à PD-236-tests.md §9) - TC-NR-01..02 : PASS - TC-NEG-01..03 : PASS

2. Points fluides

  1. Spécification canonique claire : La structure en invariants (INV-01..05), critères d'acceptation (CA-01..05), et cas d'erreur (ERR-BE-01..05) a fourni un référentiel non ambigu pour l'implémentation.

  2. Découpage en composants explicite : Le plan d'implémentation définissait clairement les responsabilités de chaque composant (TokenSearchController, TokenSearchService, RequestValidatorService, MetadataRepository, TokenIndexRepository, etc.).

  3. Mapping tests → mécanismes : La section §5 du plan d'implémentation fournissait une correspondance directe entre chaque TC-* et les mécanismes/composants concernés.

  4. Architecture NestJS standard : L'utilisation de patterns connus (modules, injectable services, TypeORM repositories) a facilité le développement et les tests unitaires.

  5. Gestion des erreurs structurée : Les 5 codes ERR-BE-xx avec leurs exceptions dédiées (TokenAbsentException, InvalidTokenFormatException, MissingMetadataException, MetadataMismatchException, ClearKeywordInjectionException) ont permis une traçabilité des rejets.

3. Points difficiles

  1. Tests d'inspection probatoire (TC-NOM-03, TC-INV-01) : L'absence initiale de tests vérifiant qu'aucun keyword en clair n'est persisté a nécessité la création d'un fichier de tests d'intégration dédié (token-search-integration.spec.ts).

  2. Scénario séquentiel Q1/Q2 (TC-NOM-04) : Le scénario nécessitant deux requêtes séquentielles avec métadonnées différentes n'était pas couvert par les tests existants et a dû être ajouté explicitement.

  3. Couverture des 3 champs de métadonnées : Le test TC-NEG-02 (mismatch k_search_scope spécifiquement) était absent ; la couverture initiale ne testait que algorithm_id et canonicalization_id dans certains scénarios.

  4. Annotations de tests incorrectes : Certains tests existants portaient des annotations TC-NOM-03/TC-NOM-04 erronées (sur des tests de doublons et résultats vides), masquant l'absence des vrais scénarios contractuels.

  5. Pattern Jest pour fichiers d'intégration : Le pattern .integration.spec.ts n'était pas reconnu par la configuration Jest, nécessitant un renommage en -integration.spec.ts.

4. Hypothèses révélées tardivement

ID Hypothèse Découverte
HT-06 Une recherche sur un index non initialisé (M_I inexistant) retourne un ensemble vide Comportement non spécifié par la spec ; choisi lors de l'implémentation du service
Implicite Le registre de validateurs doit être initialisé avec au moins DET-HMAC-SHA256-B64T22-V1 Découvert lors de l'écriture des tests de validation de format
Implicite La détection de keyword en clair se fait sur un champ nommé "keyword" dans le body JSON Le contrat d'API définissant les champs interdits n'était pas explicitement spécifié

5. Invariants complexes

ID Complexité Mécanisme Risque résiduel
INV-01 Moyenne Schéma API sans champ "keyword" + détection champ interdit + aucun stockage clair Ajout futur d'un champ "keyword" par erreur
INV-03 Élevée M_I immuable après création, comparaison stricte champ-à-champ Race condition à la création (mitigée par contrainte UNIQUE)
INV-05 N/A NON TESTABLE (neutralité sémantique) Principe architectural, pas de preuve formelle possible

TC-INV-03 : Testé via token-search.service.spec.ts - vérification que M_L == M_I est requise pour acceptation.

TC-INV-04 : Testé via token-search.service.spec.ts - rejet explicite avec MetadataMismatchException sur tout mismatch.

6. Dette technique

Élément Description Criticité Impact
ProtocolMapper Abstraction non implémentée ; mapping ERR-BE-xx → HTTP hardcodé dans le contrôleur Faible Refactoring nécessaire si support gRPC requis
Collation DB Aucune vérification explicite que la collation PostgreSQL garantit l'égalité stricte Faible Potentiel faux positifs si collation case-insensitive
Masquage logs Masquage/troncature des T_kw dans les logs non implémenté Faible Fuite potentielle de tokens dans les logs applicatifs
TODO spec §10 Points à clarifier non résolus : migration d'index, purge/reconstruction Non bloquant Documentation à compléter

7. Risques résiduels

Risque Probabilité Impact Mitigation actuelle
Race condition création M_I Faible Moyen Contrainte UNIQUE sur (index_id) dans table metadata
Attaque par fréquence/dictionnaire Accepté Moyen Hors périmètre (spec §2.2)
Validateur manquant pour nouvel algorithm_id Faible Bloquant TokenFormatValidatorRegistry extensible
Index DB non créé Faible Performance Migration à valider en production

8. Améliorations de processus

  1. Annotations de tests : Établir une convention stricte pour l'annotation des tests contractuels (TC-*) et vérifier la correspondance spec ↔ tests lors de la revue de code.

  2. Tests d'inspection probatoire : Inclure systématiquement des tests vérifiant l'absence de données sensibles en clair (INV-01) dès la première implémentation.

  3. Configuration Jest : Documenter les patterns de fichiers reconnus par Jest dans le projet pour éviter les erreurs de découverte de tests.

  4. Scénarios séquentiels : Pour les scénarios de tests nécessitant plusieurs requêtes ordonnées (Q1/Q2), créer des tests dédiés plutôt que de supposer qu'ils sont couverts par des tests unitaires atomiques.

  5. Checklist de couverture : Avant revue d'acceptabilité, vérifier manuellement que chaque TC-* du fichier de tests contractuels a un test correspondant annoté dans le code.

9. Enseignements clés

  1. Les annotations de tests ne garantissent pas la couverture : Une annotation TC-NOM-03 sur un test de doublons ne couvre pas le scénario d'inspection probatoire. La correspondance doit être vérifiée sémantiquement, pas syntaxiquement.

  2. Les tests d'invariants de sécurité (INV-01) requièrent des tests d'intégration dédiés : Les tests unitaires avec mocks ne permettent pas de vérifier l'absence de données sensibles dans les données réellement persistées.

  3. Les scénarios multi-requêtes sont distincts des tests atomiques : Un test vérifiant qu'une requête avec métadonnées incorrectes est rejetée ne couvre pas le scénario Q1 (succès) puis Q2 (rejet) sur le même index.

  4. Le hors-périmètre explicite (INV-05, risque fréquence/dictionnaire) clarifie les attentes : Documenter ce qui n'est pas testable évite les débats lors de la revue d'acceptabilité.

  5. La revue d'acceptabilité itérative fonctionne : Les 3 écarts (E-01, E-02, E-03) identifiés lors de la première revue ont été corrigés et validés lors de la seconde, aboutissant à un verdict ACCEPTÉ.