# ED-04-008 – OpenRefine Delivery ID Integration

- **Status:** Status: Completed (2026-08-01, PL)
- **Version:** 0.1
- **Scope:** ED-04 – Source Delivery Integration
- **Basis:** reconcile_ADR002.WP2_20260801_6.zip
- **Related:**
    - ADR002 – Source Delivery Model
    - ED-04-007 – SourceValue SourceDelivery Reference

---

# 1. Ziel

ED-04-008 übernimmt die von OpenRefine übergebene externe `delivery_id`
vollständig in das SourceDelivery-Modell.

Damit besitzt jede SourceDelivery künftig zwei Identitäten:

- interne Reconcilix-ID (`SourceDelivery.id`)
- externe OpenRefine-ID (`externalDeliveryId`)

Beide Identitäten erfüllen unterschiedliche Aufgaben und werden bewusst
nicht miteinander vermischt.

---

# 2. Motivation

Der aktuelle OpenRefine-Request überträgt bereits:

```text
GET

api_key=...

delivery_id=OR-TEST-20260725-001
```

Die Information wird derzeit jedoch nicht persistiert.

Dadurch können spätere Analysen oder Logs nicht eindeutig einem
OpenRefine-Delivery zugeordnet werden.

ED-04-008 schließt diese Lücke.

---

# 3. Architektur

Reconcilix verwendet weiterhin die interne UUID
als technische Aggregate-ID.

Die OpenRefine-ID wird ausschließlich
als externe Referenz gespeichert.

```text
OpenRefine

delivery_id
        │
        ▼
SourceDelivery.externalDeliveryId


Reconcilix

SourceDelivery.id
(UUID)
```

Die interne UUID bleibt die einzige Primäridentität
des Aggregats.

---

# 4. Scope

## Domain

SourceDelivery erhält:

```php
private readonly ?string $externalDeliveryId;
```

Getter:

```php
public function externalDeliveryId(): ?string
```

---

## Persistence

Neue Spalte

```text
source_delivery.external_delivery_id
```

Typ

```sql
VARCHAR(255)
```

Index

```sql
idx_source_delivery_external_delivery_id
```

Kein Unique Index.

Mehrere Deliveries dürfen dieselbe externe ID besitzen,
beispielsweise nach Testläufen.

---

# 5. OpenRefine Integration

## GET

Übernahme von

```text
delivery_id
```

aus

```php
$_GET['delivery_id']
```

---

## POST

Keine Änderung.

Die Queries bleiben unverändert.

---

## Manifest

Das Manifest bleibt:

```text
http://localhost:8080/reconcile/v2/?api_key=...&delivery_id=...
```

Es erfolgt keine Änderung des URL-Formats.

---

# 6. Runtime

Beim Registrieren einer SourceDelivery:

```text
OpenRefineRequest

↓

delivery_id

↓

SourceDelivery.externalDeliveryId

↓

Repository
```

Weitere Runtime-Komponenten bleiben unverändert.

---

# 7. Persistence

Migration:

```text
0005_source_delivery_external_delivery_id.sql
```

Repository

Mapper

Rehydration

werden erweitert.

---

# 8. Tests

## Domain

externalDeliveryId wird korrekt gespeichert.

---

## Persistence

Mapper speichert und lädt
external_delivery_id.

---

## Integration

OpenRefine POST

↓

SourceDelivery

↓

external_delivery_id

entspricht exakt dem Request.

---

## Regression

OpenRefine-End-to-End bleibt unverändert erfolgreich.

---

# 9. Nicht Bestandteil

Nicht Bestandteil von ED-04-008 sind:

- Discovery Framework
- Candidate Discovery
- RuntimeFactory
- SourceValue
- delivery_id im ReconciliationResult
- SourceSystem Integration

---

# 10. Akzeptanzkriterien

ED-04-008 ist abgeschlossen, wenn

✓ SourceDelivery externalDeliveryId besitzt

✓ source_delivery.external_delivery_id existiert

✓ OpenRefine delivery_id übernommen wird

✓ Mapper korrekt persistiert

✓ Rehydration funktioniert

✓ Manifest unverändert bleibt

✓ GET und POST unterstützt werden

✓ bestehende Tests erfolgreich bleiben

✓ OpenRefine-End-to-End erfolgreich bleibt

---

# 11. Engineering-Votum

ED-04-008 ergänzt ausschließlich die Provenienz einer SourceDelivery.

Die interne UUID bleibt unverändert die technische
Aggregatidentität.

Die externe OpenRefine-delivery_id dient ausschließlich
der Nachvollziehbarkeit und Integration.

Es entstehen keine Änderungen am Discovery Framework,
an WP3 oder an der Runtime-Architektur.