# Reconcilix – Source Delivery Import v0.1

**Status:** Umsetzung v0.1  
**Eingang:** `tools/importSourceDelivery.php` (CLI)  
**Ziel:** generisches Lieferformat für SourceDelivery, SourceValue und ContextItems; zunächst als Grundlage für Vector Candidate Discovery und vergleichende klassische Discovery-Pfade.

## 1. Leitgedanke

Das Lieferformat ist quellsystemneutral. Quellsystem-spezifische Identifikatoren und Feldangaben werden von Reconcilix nicht fachlich interpretiert, sondern soweit erforderlich als Rückadressierung bzw. Provenienz erhalten.

Ein `records[]`-Eintrag enthält in v0.1 genau **einen** `source_value`.

## 2. Contract v0.1

```json
{
  "source_delivery": {
    "tenant_id": "source-delivery-test_id",
    "source_system_id": "http://digicult.vocnet.org/terminology/ter03115",
    "delivery_channel": "BATCH_IMPORT",
    "external_delivery_id": "dehioSubjectRheinland_001"
  },
  "records": [
    {
      "recordID": "83414",
      "workID": "d-RF0f90rT",
      "source_value": {
        "recordID": "27562517",
        "source_field": "entities_x_classification_addedNotes.lexical_value",
        "value": "Ehem. Pfarrhaus",
        "preferred_entity_type_uri": "CONCEPT"
      },
      "context_sources": [
        {
          "recordID": "83413",
          "context_items": [
            {
              "context_type_uri": "https://reconcilix.vocnet.org/context/0001",
              "context_role": "item_discovery",
              "value": "<wrap>...</wrap>"
            },
            {
              "context_type_uri": "https://reconcilix.vocnet.org/context/0001",
              "context_role": "structural_context_discovery",
              "value": "<div>...</div>"
            }
          ]
        }
      ]
    }
  ]
}
```

## 3. Mapping in das Rx-Modell

| Lieferformat | Reconcilix |
|---|---|
| `source_delivery.tenant_id` | `SourceDelivery.tenantId` |
| `source_delivery.source_system_id` | `SourceDelivery.sourceSystemId` |
| `source_delivery.delivery_channel` | `SourceDelivery.deliveryChannel` |
| `source_delivery.external_delivery_id` | `SourceDelivery.externalDeliveryId` |
| `source_value.recordID` | `SourceValue.sourceRecordId` |
| `source_value.source_field` | `SourceValue.sourceField` |
| `source_value.value` | `SourceValue.value` |
| `source_value.preferred_entity_type_uri` | `SourceValue.preferredEntityTypeUri` |
| `context_items[].context_type_uri` | `ContextItem.contextTypeUri` |
| `context_items[].context_role` | `ContextItem.contextRole` |
| `context_items[].value` | `ContextItem.value` |

`source_value.recordID` und `source_value.source_field` sind in v0.1 optional. Fehlen sie, kann Reconcilix den Wert zwar verarbeiten, das Liefersystem erhält jedoch keine eindeutige Rückadressierung über diese beiden Merkmale.

## 4. Context Type und Context Role

`context_type_uri` beschreibt die **fachliche Bedeutung** des Kontextes. `context_role` beschreibt seine **Rolle im Verarbeitungsprozess**.

Für v0.1 sind fachlich vereinbart:

- `item_discovery` – Kontext unmittelbar zum Source-Item.
- `structural_context_discovery` – zusätzlicher Kontext aus dem strukturellen Zusammenhang des Source-Items; keine bestimmte hierarchische Richtung wird vorausgesetzt.

Die Domain-Eigenschaft `ContextItem.contextRole` ist nullable, damit bestehende OpenRefine-/Legacy-Pfade unverändert funktionieren. Der Source-Delivery-Contract v0.1 verlangt `context_role` für jedes gelieferte `context_item`.

## 5. Provenienz

`records[].recordID`, `records[].workID`, `context_sources[].recordID` und die übrige ursprüngliche Record-Struktur werden in v0.1 nicht zu zusätzlichen Domain-Eigenschaften ausgebaut.

Stattdessen wird der **vollständige empfangene `records[]`-Eintrag** unter

```text
SourceValue.provenance_json.source_delivery_record
```

gespeichert. Dadurch bleibt der Lieferkontext verlustfrei verfügbar, ohne quellsystemspezifische Modellannahmen in den Rx-Core zu übernehmen.

## 6. Persistenzänderung

`ContextItem` wird um die optionale Eigenschaft `contextRole` erweitert. Dazu ergänzt Migration `0005_context_item_context_role.sql`:

```sql
context_role VARCHAR(64) NULL
```

Bestehende ContextItems bleiben mit `NULL` gültig.

## 7. Importverhalten

Der CLI-Import:

1. liest und validiert das JSON,
2. prüft bei vorhandener `external_delivery_id`, ob dieselbe Kombination aus Tenant und externer Delivery-ID bereits existiert,
3. legt eine `SourceDelivery` an,
4. setzt sie auf `PROCESSING`,
5. erzeugt je `records[]` genau einen `SourceValue`,
6. flacht alle `context_sources[].context_items[]` auf die `ContextItem[]` des SourceValue ab,
7. speichert den vollständigen Record in `provenance_json`,
8. setzt die Lieferung auf `COMPLETED`,
9. führt den gesamten Import atomar in einer DB-Transaktion aus.

Bei einem Fehler wird die Transaktion zurückgerollt; es werden keine Teilimporte persistiert.

## 8. CLI

Vor dem ersten Import Migrationen ausführen:

```bash
php tools/migrate.php
```

Danach:

```bash
php tools/importSourceDelivery.php path/to/source-delivery.json
```

Beispielausgabe:

```text
Source Delivery Import v0.1: OK
source_delivery_id: <UUID>
records: 1
source_values: 1
context_items: 2
```

## 9. Nicht im Scope

Nicht Bestandteil dieses Imports sind:

- Candidate Discovery selbst,
- Qdrant-/Vector-API-Aufruf,
- OpenRefine-Ausgabe,
- LLM-Interpretation,
- Ableitung von ContextItems aus Roh-/Umgebungstext,
- fachliche Interpretation quellsystemspezifischer Record-/Work-IDs,
- automatische MatchDecision.

Der Import schafft ausschließlich eine gemeinsame persistierte Ausgangsbasis für diese nachfolgenden Verarbeitungspfade.