Zoha/agent-skills

NestJS Elasticsearch

Guia de integração para adicionar busca baseada em Elasticsearch a uma aplicação NestJS GraphQL + MongoDB. Ele define o limite arquitetural (infraestrutura genérica, uma camada de busca compartilhada, um índice por funcionalidade) e cobre todo o ciclo de vida: a projeção de busca, indexação e sincronização, consultas apenas por ID com hidratação do MongoDB, paginação por cursor, campos derivados entre entidades, execução com busca opcional por meio de uma camada de backend configurável, testes sem um cluster ativo e as operações/experiência do desenvolvedor relacionadas.

O contrato orientador é Elasticsearch encontra, MongoDB serve: o Elasticsearch é um índice de busca puro que retorna identificadores, e as entidades solicitadas são sempre hidratadas a partir do MongoDB, a fonte da verdade.

Quando Aplicar

Consulte estas diretrizes ao:

• Adicionar busca a uma aplicação NestJS GraphQL + MongoDB existente
• Configurar o cliente @nestjs/elasticsearch e a camada de busca compartilhada
• Definir ou alterar um mapeamento de índice ou a projeção de busca
• Implementar sincronização MongoDB-para-Elasticsearch, reindexação ou migrações de índice
• Escrever uma consulta de busca, paginação por cursor ou hidratação de resultados
• Manter um valor derivado (contagens, classificações) pesquisável entre entidades
• Tornar a busca opcional ou trocar o backend a partir da configuração sem um cluster
• Testar a busca com uma camada de backend simulada ou contra um cluster descartável real
• Depurar resultados de busca desatualizados ou tempestades de indexação

Categorias de Regras por Prioridade

Prioridade	Categoria	Impacto	Prefixo
1	Arquitetura	CRÍTICO	arch-
2	Indexação e Sincronização	CRÍTICO	sync-
3	Esquema e Mapeamento	ALTO	map-
4	Consultas	ALTO	query-
5	Entre Entidades	MÉDIO-ALTO	rel-
6	Operações e DX	MÉDIO	ops-
7	Configuração e Ambientes	ALTO	cfg-
8	Testes	MÉDIO-ALTO	test-

Referência Rápida

1. Arquitetura (CRÍTICO)

• arch-base-search-repository - Coloque Índice e Lógica de Consulta Compartilhados em um Repositório Base
• arch-entity-vs-search-document - Mantenha Campos do Elasticsearch Fora da Entidade
• arch-feature-owned-index - Deixe Cada Funcionalidade Possuir e Registrar Seu Índice
• arch-infra-module - Isole o Cliente Elasticsearch em um Módulo de Infraestrutura Genérico

2. Indexação e Sincronização (CRÍTICO)

• sync-bulk-index - Indexe em Lotes com a Bulk API
• sync-debounce-same-id - Deboule as Rajadas do Mesmo ID
• sync-delete-immediately - Exclua do Índice Imediatamente
• sync-enqueue-index - Enfileire a Indexação; Nunca Escreva no Elasticsearch em Linha
• sync-full-reindex-alias-swap - Reindexe Através de um Índice Versionado e Troque o Alias
• sync-idempotent-index-creation - Crie Índices de Forma Idempotente com Nomes Determinísticos

3. Esquema e Mapeamento (ALTO)

• map-analyzers - Escolha Analisadores de Texto Deliberadamente
• map-derived-fields - Calcule Campos Derivados e de Relacionamento em um Mapeador em Lote
• map-exclude-non-search-fields - Indexe Apenas Campos com Propósito de Busca
• map-mapping-object - Declare o Mapeamento como um Objeto Tipado
• map-typed-search-document - Tipifique o Documento de Busca Contra a Entidade

4. Consultas (ALTO)

• query-cursor-pagination - Pagine com search_after
• query-hydrate-restore-order - Hidrate a partir do MongoDB e Restaure a Ordem de Relevância
• query-ids-only-search - Busca Retorna Apenas IDs
• query-sort-tiebreaker - Inclua Sempre um Desempate de Ordenação Único

5. Entre Entidades (MÉDIO-ALTO)

• rel-derived-counter-cache - Armazene em Cache Contadores Derivados no Documento Proprietário
• rel-owning-module-subscribes - O Módulo Proprietário se Inscreve; Outros Emitem Seus Próprios Eventos

6. Operações e DX (MÉDIO)

• ops-cli-scripts - Forneça Comandos CLI de Migração e Reindexação
• ops-explain-debug - Forneça um Gancho de Explicação
• ops-health-check - Inclua Elasticsearch nas Verificações de Saúde
• ops-log-es-requests - Registre em Log as Requisições e Respostas do Elasticsearch
• ops-no-cron-for-indexing - Nunca Agende Indexação com um Timer em Processo

7. Configuração e Ambientes (ALTO)

• cfg-mongo-fallback-backend - Recorra a um Localizador MongoDB Determinístico
• cfg-search-backend-seam - Coloque a Busca por Trás de uma Camada de Backend

8. Testes (MÉDIO-ALTO)

• test-mock-elasticsearch-seam - Simule a Camada de Backend de Busca em Testes Unitários
• test-real-es-for-query-semantics - Teste Semântica de Consulta Contra um Elasticsearch Real

Como Usar

Leia os arquivos de regra individuais para explicações detalhadas e exemplos de código:

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

Cada arquivo de regra contém:

• Breve explicação de por que é importante e a qual camada se aplica
• Exemplo de código incorreto com explicação
• Exemplo de código correto com explicação
• Contexto adicional e referências

Relação com Outras Skills

• nestjs-graphql-structure — posicionamento de arquivos. Esta skill adiciona a pasta search/ a uma funcionalidade e as camadas common/search/ + infra/elasticsearch/; ela segue as regras de módulo de funcionalidade, repositório e eventos daquela skill.
• nestjs-best-practices — regras comportamentais para serviços, eventos, filas, configuração e verificações de saúde nas quais os exemplos desta skill se baseiam.
• Uma exceção deliberada — a regra service-background-jobs da nestjs-graphql-structure mantém processadores na funcionalidade proprietária. O pipeline de busca é executado uma vez em common/search/ e resolve o repositório de cada funcionalidade através do registro de índices, porque o pipeline é idêntico para todas as funcionalidades; veja arch-base-search-repository.

Documento Compilado Completo

Para o guia completo com todas as regras expandidas em um único documento, veja AGENTS.md.