Zoha/agent-skills

NestJS Elasticsearch

Guide d'intégration pour ajouter une recherche basée sur Elasticsearch à une application NestJS GraphQL + MongoDB. Il fixe la frontière architecturale (infrastructure générique, une couche de recherche partagée, un index propre par fonctionnalité), puis couvre le cycle de vie complet : la projection de recherche, l'indexation et la synchronisation, les requêtes par ID avec hydratation MongoDB, la pagination par curseur, les champs dérivés inter-entités, l'exécution avec une recherche optionnelle via une couche d'abstraction configurable, les tests sans cluster en direct, et les opérations et l'expérience développeur associées.

Le contrat directeur est Elasticsearch trouve, MongoDB sert : Elasticsearch est un pur index de recherche qui retourne des identifiants, et les entités demandées sont toujours hydratées depuis MongoDB, la source de vérité.

Quand appliquer

Référez-vous à ces directives lors :

• De l'ajout d'une recherche à une application NestJS GraphQL + MongoDB existante
• Du câblage du client @nestjs/elasticsearch et de la couche de recherche partagée
• De la définition ou modification d'un mapping d'index ou de la projection de recherche
• De l'implémentation de la synchronisation MongoDB vers Elasticsearch, de la réindexation ou des migrations d'index
• De l'écriture d'une requête de recherche, d'une pagination par curseur ou d'une hydratation de résultats
• Du maintien de valeurs dérivées (compteurs, évaluations) consultables entre entités
• De la possibilité de rendre la recherche optionnelle, ou de changer de backend, depuis la configuration sans cluster
• Des tests de la recherche avec une couche d'abstraction simulée, ou contre un cluster réel jetable
• Du débogage de résultats de recherche obsolètes ou de tempêtes d'indexation

Catégories de règles par priorité

Priorité	Catégorie	Impact	Préfixe
1	Architecture	CRITIQUE	arch-
2	Indexation & Synchronisation	CRITIQUE	sync-
3	Schéma & Mapping	ÉLEVÉ	map-
4	Requêtes	ÉLEVÉ	query-
5	Inter-entités	MOYEN-ÉLEVÉ	rel-
6	Opérations & DX	MOYEN	ops-
7	Configuration & Environnements	ÉLEVÉ	cfg-
8	Tests	MOYEN-ÉLEVÉ	test-

Référence rapide

1. Architecture (CRITIQUE)

• arch-base-search-repository - Placer la logique partagée d'index et de requête dans un dépôt de base
• arch-entity-vs-search-document - Garder les champs Elasticsearch hors de l'entité
• arch-feature-owned-index - Laisser chaque fonctionnalité posséder et enregistrer son index
• arch-infra-module - Isoler le client Elasticsearch dans un module d'infrastructure générique

2. Indexation & Synchronisation (CRITIQUE)

• sync-bulk-index - Indexer par lots avec l'API Bulk
• sync-debounce-same-id - Débouncer les rafales de mêmes identifiants
• sync-delete-immediately - Supprimer de l'index immédiatement
• sync-enqueue-index - Mettre en file d'attente l'indexation ; ne jamais écrire dans Elasticsearch en ligne
• sync-full-reindex-alias-swap - Réindexer via un index versionné et échanger l'alias
• sync-idempotent-index-creation - Créer les index de manière idempotente avec des noms déterministes

3. Schéma & Mapping (ÉLEVÉ)

• map-analyzers - Choisir les analyseurs de texte délibérément
• map-derived-fields - Calculer les champs dérivés et de relation dans un mappeur par lots
• map-exclude-non-search-fields - Indexer uniquement les champs ayant un but de recherche
• map-mapping-object - Déclarer le mapping comme un objet typé
• map-typed-search-document - Typer le document de recherche par rapport à l'entité

4. Requêtes (ÉLEVÉ)

• query-cursor-pagination - Paginer avec search_after
• query-hydrate-restore-order - Hydrater depuis MongoDB et restaurer l'ordre de pertinence
• query-ids-only-search - La recherche ne retourne que des identifiants
• query-sort-tiebreaker - Toujours inclure un départage unique de tri

5. Inter-entités (MOYEN-ÉLEVÉ)

• rel-derived-counter-cache - Mettre en cache les compteurs dérivés sur le document propriétaire
• rel-owning-module-subscribes - Le module propriétaire s'abonne ; les autres émettent leurs propres événements

6. Opérations & DX (MOYEN)

• ops-cli-scripts - Fournir des commandes CLI de migration et de réindexation
• ops-explain-debug - Fournir un crochet d'explication
• ops-health-check - Inclure Elasticsearch dans les vérifications de santé
• ops-log-es-requests - Journaliser les requêtes et réponses Elasticsearch
• ops-no-cron-for-indexing - Ne jamais planifier l'indexation avec une temporisation interne

7. Configuration & Environnements (ÉLEVÉ)

• cfg-mongo-fallback-backend - Replier sur un finder MongoDB déterministe
• cfg-search-backend-seam - Mettre la recherche derrière une couche d'abstraction de backend

8. Tests (MOYEN-ÉLEVÉ)

• test-mock-elasticsearch-seam - Simuler la couche d'abstraction du backend de recherche dans les tests unitaires
• test-real-es-for-query-semantics - Tester la sémantique des requêtes contre un vrai Elasticsearch

Comment utiliser

Lisez les fichiers de règles individuels pour des explications détaillées et des exemples de code :

rules/arch-entity-vs-search-document.md
rules/sync-full-reindex-alias-swap.md
rules/query-ids-only-search.md

Chaque fichier de règle contient :

• Une brève explication de pourquoi c'est important et à quelle couche cela s'applique
• Un exemple de code incorrect avec explication
• Un exemple de code correct avec explication
• Contexte supplémentaire et références

Relation avec les autres skills

• nestjs-graphql-structure — placement des fichiers. Ce skill ajoute le dossier search/ à une fonctionnalité et les couches common/search/ + infra/elasticsearch/ ; il suit les règles de module de fonctionnalité, dépôt et événements de ce skill.
• nestjs-best-practices — règles comportementales pour les services, événements, files d'attente, configuration et vérifications de santé sur lesquelles s'appuient les exemples de ce skill.
• Une exception délibérée — la règle service-background-jobs de nestjs-graphql-structure maintient les processeurs dans la fonctionnalité propriétaire. Le pipeline de recherche s'exécute une fois dans common/search/ et résout le dépôt de chaque fonctionnalité via le registre d'index à la place, car le pipeline est identique pour chaque fonctionnalité ; voir arch-base-search-repository.

Document complet compilé

Pour le guide complet avec toutes les règles développées dans un seul document, voir AGENTS.md.