# ADR 0008 — External-Reference-Pattern

## Status
Accepted

## Kurz erklärt
External Reference bedeutet:

```text
Ein internes Objekt merkt sich,
wie es in einem externen System heißt.
```

Beispiel:

- Kunde im Backoffice
- derselbe Kunde in Lexware
- dieselbe Domain bei 1blu
- derselbe Hostingaccount in KeyHelp

## Kontext
Das Architekturreview hat kritisiert, dass konkrete Anbieterfelder wie `keyhelp_id` oder `lexware_id` im Core das Adapter-Pattern zerstören würden.

## Entscheidung
Hosting-Backoffice verwendet ein generisches External-Reference-Pattern.

Der Core erhält keine Anbieterfelder wie:

```text
keyhelp_id
lexware_id
oneblu_id
```

Stattdessen gibt es eine generische Referenzstruktur.

## Beispielstruktur

```text
external_references
- id
- tenant_id
- owner_type
- owner_id
- provider
- provider_account_id
- external_id
- external_type
- metadata
- last_synced_at
- created_at
- updated_at
```

## Beispiel

```text
owner_type: Domain
owner_id: 123
provider: 1blu
external_id: ABC-987
```

Oder:

```text
owner_type: Server
owner_id: 55
provider: KeyHelp
external_id: server-user-4711
```

## Begründung
Dieses Pattern sorgt für:

- Providerneutralität
- weniger Core-Abhängigkeiten
- einfachere neue Integrationen
- saubere Migrationen
- bessere Austauschbarkeit von Modulen

## Konsequenzen

### Positiv
- keine harte Anbieterlogik im Core
- bessere Erweiterbarkeit
- sauberer Wechsel von Anbietern möglich

### Negativ
- etwas komplexeres Datenmodell
- Entwickler müssen über Adapter denken
- direkte Fremdschlüssel zu externen Systemen sind nicht erlaubt

## Verwandte ADRs
- ADR 0007 — Modul-System
- ADR 0009 — Core-Grenzen
- ADR 0017 — Adapter-Fehlerresilienz