Zoha/agent-skills

NestJS Elasticsearch

Integrationsleitfaden zum Hinzufügen einer Elasticsearch-gestützten Suche zu einer NestJS GraphQL + MongoDB-Anwendung. Er legt die architektonische Grenze fest (generische Infrastruktur, eine gemeinsame Suchschicht, ein eigener Index pro Feature) und deckt dann den vollständigen Lebenszyklus ab: die Suchprojektion, Indizierung und Synchronisation, ID-basierte Abfragen mit MongoDB-Hydratation, Cursor-Paginierung, entitätsübergreifende abgeleitete Felder, Betrieb mit optionaler Suche über einen konfigurierbaren Backend-Seam, Tests ohne Live-Cluster sowie die damit verbundenen Betriebsabläufe und die Entwicklererfahrung (DX).

Der Leitvertrag ist Elasticsearch findet, MongoDB liefert aus: Elasticsearch ist ein reiner Suchindex, der Identifikatoren zurückgibt, und die angeforderten Entitäten werden stets aus der Datenquelle MongoDB hydriert.

Wann anwenden

Diese Richtlinien sind zu beachten, wenn:

• Sie eine Suche zu einer vorhandenen NestJS GraphQL + MongoDB-Anwendung hinzufügen
• Sie den @nestjs/elasticsearch-Client und die gemeinsame Suchschicht verkabeln
• Sie ein Index-Mapping oder die Suchprojektion definieren oder ändern
• Sie die MongoDB-zu-Elasticsearch-Synchronisation, Neuindizierung oder Index-Migrationen implementieren
• Sie eine Suchabfrage, Cursor-Paginierung oder Ergebnishydratation schreiben
• Sie einen abgeleiteten Wert (Zählungen, Bewertungen) suchbar über Entitäten hinweg halten
• Sie die Suche optional machen oder das Backend per Konfiguration ohne Cluster austauschen
• Sie die Suche mit einem gemockten Backend-Seam oder gegen einen echten temporären Cluster testen
• Sie veraltete Suchergebnisse oder Indizierungsstürme debuggen

Regelkategorien nach Priorität

Priorität	Kategorie	Auswirkung	Präfix
1	Architektur	KRITISCH	arch-
2	Indizierung & Sync	KRITISCH	sync-
3	Schema & Mapping	HOCH	map-
4	Abfragen	HOCH	query-
5	Entitätsübergreifend	MITTEL-HOCH	rel-
6	Betrieb & DX	MITTEL	ops-
7	Konfiguration & Umgebungen	HOCH	cfg-
8	Testen	MITTEL-HOCH	test-

Kurzreferenz

1. Architektur (KRITISCH)

• arch-base-search-repository - Gemeinsame Index- und Abfragelogik in ein Basis-Repository auslagern
• arch-entity-vs-search-document - Elasticsearch-Felder aus der Entität heraushalten
• arch-feature-owned-index - Jedes Feature besitzt und registriert seinen eigenen Index
• arch-infra-module - Den Elasticsearch-Client in einem generischen Infrastruktur-Modul isolieren

2. Indizierung & Sync (KRITISCH)

• sync-bulk-index - In Batches mit der Bulk-API indizieren
• sync-debounce-same-id - Gleichzeitige Bursts derselben ID entprellen
• sync-delete-immediately - Sofort aus dem Index löschen
• sync-enqueue-index - Indizierung in die Warteschlange stellen; nie direkt in Elasticsearch schreiben
• sync-full-reindex-alias-swap - Über einen versionierten Index neu indizieren und den Alias tauschen
• sync-idempotent-index-creation - Indizes idempotent mit deterministischen Namen erstellen

3. Schema & Mapping (HOCH)

• map-analyzers - Textanalysatoren bewusst auswählen
• map-derived-fields - Abgeleitete und Relationsfelder in einem Batch-Mapper berechnen
• map-exclude-non-search-fields - Nur Felder mit Suchzweck indizieren
• map-mapping-object - Das Mapping als typisiertes Objekt deklarieren
• map-typed-search-document - Das Suchdokument gegen die Entität typisieren

4. Abfragen (HOCH)

• query-cursor-pagination - Mit search_after paginieren
• query-hydrate-restore-order - Aus MongoDB hydrieren und die Relevanzreihenfolge wiederherstellen
• query-ids-only-search - Die Suche gibt nur IDs zurück
• query-sort-tiebreaker - Immer einen eindeutigen Sortier-Tiebreaker einfügen

5. Entitätsübergreifend (MITTEL-HOCH)

• rel-derived-counter-cache - Abgeleitete Zähler auf dem besitzenden Dokument cachen
• rel-owning-module-subscribes - Das besitzende Modul abonniert; andere emittieren eigene Ereignisse

6. Betrieb & DX (MITTEL)

• ops-cli-scripts - CLI-Befehle für Migration und Neuindizierung bereitstellen
• ops-explain-debug - Einen Explain-Hook bereitstellen
• ops-health-check - Elasticsearch in Health Checks einbeziehen
• ops-log-es-requests - Elasticsearch-Anfragen und -Antworten protokollieren
• ops-no-cron-for-indexing - Indizierung nie mit einem prozessinternen Timer planen

7. Konfiguration & Umgebungen (HOCH)

• cfg-mongo-fallback-backend - Auf einen deterministischen MongoDB-Finder zurückfallen
• cfg-search-backend-seam - Die Suche hinter einen Backend-Seam legen

8. Testen (MITTEL-HOCH)

• test-mock-elasticsearch-seam - Den Such-Backend-Seam in Unit-Tests mocken
• test-real-es-for-query-semantics - Abfragesemantik gegen einen echten Elasticsearch testen

Verwendung

Lesen Sie die einzelnen Regeldateien für detaillierte Erklärungen und Codebeispiele:

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

Jede Regeldatei enthält:

• Kurze Erklärung, warum sie wichtig ist und auf welche Schicht sie angewendet wird
• Falsches Codebeispiel mit Erklärung
• Richtiges Codebeispiel mit Erklärung
• Zusätzlicher Kontext und Referenzen

Beziehung zu anderen Skills

• nestjs-graphql-structure – Dateiplatzierung. Dieser Skill fügt den search/-Ordner zu einem Feature und die common/search/ + infra/elasticsearch/-Schichten hinzu; er folgt den Regeln dieses Skills zu Feature-Modulen, Repositories und Ereignissen.
• nestjs-best-practices – Verhaltensregeln für Services, Ereignisse, Warteschlangen, Konfiguration und Health Checks, auf denen die Beispiele dieses Skills aufbauen.
• Eine bewusste Ausnahme – Die service-background-jobs-Regel von nestjs-graphql-structure belässt Prozessoren im besitzenden Feature. Die Suchpipeline läuft stattdessen einmal in common/search/ und löst jedes Feature-Repository über das Index-Registry auf, da die Pipeline für jedes Feature identisch ist; siehe arch-base-search-repository.

Vollständig kompiliertes Dokument

Für die vollständige Anleitung mit allen erweiterten Regeln in einem einzigen Dokument siehe AGENTS.md.