Entity Registry — Konzeptdokument

Was es ist

Die Entity Registry ist ein metadatengesteuerter Ersatz fuer alle hardcodierten Domain-Annahmen im Explorer. Statt dass der Explorer weiss, dass gold_cases eine start_time-Spalte hat, lebt all dieses Wissen in YAML-Dateien, wird in dbt-Registry-Tabellen kompiliert, und der Explorer liest es zur Laufzeit.

Der Explorer-Code darf das Metadaten-Schema annehmen. Er darf keinen Business-Inhalt annehmen.

Das Problem

Der Explorer funktioniert derzeit weil ~25 hardcodierte Annahmen verstreut ueber 5 TypeScript-Dateien zufaellig mit dem aktuellen Gold-Schema uebereinstimmen. Eine neue Gold Entity hinzuzufuegen erfordert das Bearbeiten mehrerer Dateien auf mehreren Ebenen.

Design

Architektur

entities/*.yaml                              ← Wahrheitsquelle
      │
      ▼
scripts/entitycompile.py ──validiert──▶ contracts/gold_contract.v1.json
      │
      ├──▶ dbt/{pack}/models/registry/entity_registry.sql
      └──▶ dbt/{pack}/models/registry/entity_relationships.sql

Dies folgt demselben Muster wie Signals und Theses: YAML-Wahrheitsquelle → Compiler → dbt SQL → Laufzeit-Konsum.

Schema-Definitionen

entity_registry Tabelle

Eine Zeile pro Entity. 16 Spalten: entity_id, dbt_model, display_name_en/de/fr, icon, is_browseable, primary_key_column, business_id_column, label_column, detail_column, timestamp_column, amount_column, probe_entity_type, taxonomy_dimension_type, taxonomy_caption_column.

entity_relationships Tabelle

Eine Zeile pro Beziehung. 9 Spalten: source_entity_id, join_column, target_model, target_join_column, order_column, label_en/de/fr, custom_sql.

Explorer-Konsum

Ein einzelnes Modul entityRegistry.ts laedt, cached und befragt die Registry-Tabellen. Alles Domain-Wissen im Explorer fliesst durch dieses Modul.

Oeffentliche API

Funktion	Gibt zurueck	Ersetzt
getBrowseableEntities(tenant)	is_browseable = true Entities	discoverDimensions() + Ausschlusslisten
getEntityByKey(tenant, key)	Lookup nach entity_id	PK-Heuristik + pickDisplayColumns
getEntityByProbeType(tenant, type)	Lookup nach probe_entity_type	ENTITY_TYPE_MAP
getRelationships(tenant, entityId)	Beziehungen fuer Entity	RELATED_FACTS

Graceful Degradation

Wenn die entity_registry-Tabelle nicht existiert (Tenant noch nicht nach Registry-Einfuehrung neu gebaut), Fallback auf aktuelle information_schema-Erkennung + Heuristiken.

Siehe die englische Referenz fuer vollstaendige Implementierungsphasen, Tests (4 Tiers) und offene Fragen.