Contract-Schema-Referenz

Menschenlesbare Dokumentation fuer die JSON Contracts, die jinflows stabile Interfaces definieren.

Contracts sind pack-spezifisch im Inhalt, folgen aber einer gemeinsamen Struktur. Die hier gezeigten Felder stammen aus dem interlogic Pack als repraesentatives Beispiel. Andere Packs (alptrack, millesime) definieren andere Gold Entities, verwenden aber dasselbe Contract-Format und dieselben findings/diagnosis/smebit/bitbundle/report Contracts.

Wie Contracts funktionieren

Contracts definieren das Schema fuer den Output jeder Ebene. Sie sind die stabile API zwischen Ebenen — interne Tabellenschemas koennen sich aendern, aber Contract-Felder sind garantiert. Signals referenzieren gold.v1 Entities nach Contract-Name (z.B. Shipment, nicht gold_shipments). Perspectives referenzieren findings.v1. Theses produzieren Verdicts, die von Verdicts via diagnosis.v1 konsumiert werden. Der Compiler validiert alle Entity- und Feld-Referenzen gegen Contracts vor der SQL-Generierung.

Die 7 Contracts bilden eine Abhaengigkeitskette:

1. Gold Contract (gold.v1)

Zweck: Definiert den quellsystem-agnostischen kanonischen Datensatz, auf dem Signals operieren.

Siehe die englische Referenz fuer die vollstaendige Feldliste aller 15 Entities (Shipment, ShipmentItem, Checkpoint, Warehouse, Route, RouteLeg, Carrier, Customer, Container, CustomsDeclaration, InventorySnapshot, Incident, TaxonomyNode, TaxonomyMemberMapping, TaxonomyClosure).

2. Silver Contract (silver.v1)

Zweck: Definiert die validierte Domain-Ebene mit Datenqualitaets-Flags — dieselben Entities wie Gold plus Lineage- und Validierungsspalten.

Jede Silver Entity spiegelt ihr Gold-Gegenstueck mit vier zusaetzlichen Spalten: source_file, row_number, is_valid, invalid_reason.

3. Findings Contract (findings.v1)

Zweck: Definiert das Standard-Ausgabeschema fuer alle Signals und Perspectives, ermoeglicht Signal-uebergreifende Aggregation und Thesis-Bewertung.

Feld	Typ	Nullable	Beschreibung
finding_id	string	Nein	Eindeutiger Bezeichner
tenant_id	string	Nein	Tenant, der dieses Finding produziert hat
probe_id	string	Nein	Signal, das dieses Finding generiert hat
probe_version	string	Nein	Version des Signals
severity	string	Nein	Schweregrad (critical/high/medium/low/info)
entity_type	string	Nein	Gold Entity-Typ
entity_id	string	Nein	Business-ID der markierten Entity
time_bucket	string	Ja	Zeitgruppierung
money_at_risk	decimal	Ja	Monetaerer Impact in Basiswaehrung
qty_at_risk	decimal	Ja	Mengen-Impact
health_score	decimal	Ja	Health Score (0.0-1.0, nur Perspectives)
evidence	string	Nein	JSON-Blob mit Signal-spezifischem Detail

4. Diagnosis Contract (diagnosis.v1)

Zweck: Definiert das Ausgabeschema fuer Root-Cause-Verdicts an bestaetigten Theses.

Felder: diagnosis_id, tenant_id, hypothesis_id, root_cause_category, root_cause_id, confidence, finding_count, money_at_risk, hypothesis_evidence_score.

5. Subject Matter Contract (smebit.v1)

Zweck: Definiert die Registry- und Verdict-Schemas fuer atomare Expertenwissen-Artefakte.

Siehe die englische Referenz fuer die vollstaendige Feldliste der SMEbit Registry (30 Felder) und SubjectMatterVerdict (6 Felder).

6. Dossier Contract (bitbundle.v1)

Zweck: Definiert die Registry- und Mitgliedschafts-Schemas fuer kuratierte narrative SMEbit-Gruppierungen.

7. Report Contract (report.v1)

Zweck: Definiert das Ausgabeschema fuer kompilierte analytische Reports (Daten-Payload und Registry-Metadaten).

Designprinzipien

Surrogatschluessel neben Business-IDs. Jede Gold Entity hat sowohl einen *_key (Surrogat) als auch eine *_id (Business-Bezeichner). Surrogatschluessel sind stabil ueber Rebuilds; Business-IDs sind menschenlesbar.

Dreisprachige Unterstuetzung. Alle benutzersichtbaren Textfelder kommen in _en, _de, _fr Varianten.

Qualitaetsverfolgung. Silver fuegt is_valid und invalid_reason zu jeder Entity hinzu. Ungueltige Zeilen werden beibehalten (nicht stillschweigend verworfen).

Tenant-Isolation. Jede Fakten- und Verdict-Tabelle enthaelt tenant_id.

Nullable-Felder explizit markiert. Fremdschluessel fuer optionale Beziehungen und Felder, die von der Prozessfertigstellung abhaengen, sind nullable.

JSON fuer strukturierte Evidenz. Die evidence-Felder tragen strukturierte Daten als JSON-Strings.