Zoha/agent-skills

NestJS Elasticsearch

Guía de integración para añadir búsqueda con Elasticsearch a una aplicación NestJS GraphQL + MongoDB. Define el límite arquitectónico (infraestructura genérica, una capa de búsqueda compartida y un índice por feature), y cubre el ciclo de vida completo: la proyección de búsqueda, indexación y sincronización, consultas solo con IDs e hidratación desde MongoDB, paginación con cursor, campos derivados entre entidades, ejecución con búsqueda opcional mediante una capa de backend configurable, pruebas sin un clúster en vivo, y las operaciones y DX (experiencia del desarrollador) que lo acompañan.

El contrato rector es Elasticsearch encuentra, MongoDB sirve: Elasticsearch es un índice de búsqueda puro que devuelve identificadores, y las entidades solicitadas siempre se hidratan desde MongoDB, la fuente de verdad.

Cuándo Aplicar

Consulta estas pautas cuando:

• Añadas búsqueda a una aplicación NestJS GraphQL + MongoDB existente
• Cablees el cliente @nestjs/elasticsearch y la capa de búsqueda compartida
• Definas o cambies un mapeo de índice o la proyección de búsqueda
• Implementes sincronización de MongoDB a Elasticsearch, reindexación o migraciones de índices
• Escribas una consulta de búsqueda, paginación con cursor o hidratación de resultados
• Mantengas un valor derivado (contadores, calificaciones) buscable entre entidades
• Hagas que la búsqueda sea opcional, o intercambies el backend, desde la configuración sin un clúster
• Pruebes la búsqueda con una capa de backend simulada, o contra un clúster desechable real
• Depures resultados de búsqueda desactualizados o tormentas de indexación

Categorías de Reglas por Prioridad

Prioridad	Categoría	Impacto	Prefijo
1	Arquitectura	CRÍTICO	arch-
2	Indexación y Sincronización	CRÍTICO	sync-
3	Esquema y Mapeo	ALTO	map-
4	Consultas	ALTO	query-
5	Entre Entidades	MEDIO-ALTO	rel-
6	Operaciones y DX	MEDIO	ops-
7	Configuración y Entornos	ALTO	cfg-
8	Pruebas	MEDIO-ALTO	test-

Referencia Rápida

1. Arquitectura (CRÍTICO)

• arch-base-search-repository - Coloca la lógica compartida de índices y consultas en un Repositorio Base
• arch-entity-vs-search-document - Mantén los campos de Elasticsearch fuera de la Entidad
• arch-feature-owned-index - Deja que cada Feature posea y registre su índice
• arch-infra-module - Aísla el cliente de Elasticsearch en un Módulo de Infraestructura Genérico

2. Indexación y Sincronización (CRÍTICO)

• sync-bulk-index - Indexa en lotes usando la API Bulk
• sync-debounce-same-id - Elimina ráfagas del mismo ID
• sync-delete-immediately - Elimina del índice de inmediato
• sync-enqueue-index - Encola la indexación; nunca escribas en Elasticsearch en línea
• sync-full-reindex-alias-swap - Reindexa a través de un índice versionado e intercambia el alias
• sync-idempotent-index-creation - Crea índices de manera idempotente con nombres deterministas

3. Esquema y Mapeo (ALTO)

• map-analyzers - Elige los analizadores de texto deliberadamente
• map-derived-fields - Calcula campos derivados y de relación en un mapeador por lotes
• map-exclude-non-search-fields - Indexa solo los campos con propósito de búsqueda
• map-mapping-object - Declara el mapeo como un objeto tipado
• map-typed-search-document - Tipa el documento de búsqueda contra la entidad

4. Consultas (ALTO)

• query-cursor-pagination - Pagina con search_after
• query-hydrate-restore-order - Hidrata desde MongoDB y restaura el orden de relevancia
• query-ids-only-search - La búsqueda devuelve solo IDs
• query-sort-tiebreaker - Incluye siempre un desempatador de orden único

5. Entre Entidades (MEDIO-ALTO)

• rel-derived-counter-cache - Cachea contadores derivados en el documento propietario
• rel-owning-module-subscribes - El módulo propietario se suscribe; los demás emiten sus propios eventos

6. Operaciones y DX (MEDIO)

• ops-cli-scripts - Proporciona comandos CLI de migración y reindexación
• ops-explain-debug - Proporciona un hook de explicación
• ops-health-check - Incluye Elasticsearch en las comprobaciones de salud
• ops-log-es-requests - Registra las solicitudes y respuestas de Elasticsearch
• ops-no-cron-for-indexing - Nunca programes la indexación con un temporizador en proceso

7. Configuración y Entornos (ALTO)

• cfg-mongo-fallback-backend - Recurre a un buscador de MongoDB determinista
• cfg-search-backend-seam - Pon la búsqueda detrás de una capa de backend

8. Pruebas (MEDIO-ALTO)

• test-mock-elasticsearch-seam - Simula la capa de backend de búsqueda en pruebas unitarias
• test-real-es-for-query-semantics - Prueba la semántica de las consultas contra un Elasticsearch real

Cómo Usar

Lee los archivos de reglas individuales para explicaciones detalladas y ejemplos de código:

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

Cada archivo de regla contiene:

• Breve explicación de por qué es importante y a qué capa aplica
• Ejemplo de código incorrecto con explicación
• Ejemplo de código correcto con explicación
• Contexto adicional y referencias

Relación con Otras Habilidades

• nestjs-graphql-structure — colocación de archivos. Esta habilidad añade la carpeta search/ a una feature y las capas common/search/ + infra/elasticsearch/; sigue las reglas de módulo-feature, repositorio y eventos de esa habilidad.
• nestjs-best-practices — reglas de comportamiento para servicios, eventos, colas, configuración y comprobaciones de salud en las que se basan los ejemplos de esta habilidad.
• Una excepción deliberada — la regla service-background-jobs de nestjs-graphql-structure mantiene los procesadores en la feature propietaria. El pipeline de búsqueda se ejecuta una vez en common/search/ y resuelve el repositorio de cada feature a través del registro de índices, porque el pipeline es idéntico para todas las features; consulta arch-base-search-repository.

Documento Compilado Completo

Para la guía completa con todas las reglas expandidas en un solo documento, consulta AGENTS.md.