# IA001 — Impact Analysis ADR002 on DM and ME

**Status:** Draft ED  
**Basis:** `ADR002_SOURCE_DELIVERY_MODEL_V4.md`  
**Affected baseline:**  
- `DM001_Domain_Model_v0.4_DRAFT.md`
- `DM002_Persistence_Model_v0.3.md`
- `ME001_Interpretation_Properties_and_Vocabulary_Matching_Patterns_v0.2_ALPHA.md`
- `ME002_Interpretation_Driven_Reconciliation_v0.6_DRAFT.md`

## 1. Purpose

Diese Impact-Analyse bestimmt, welche Änderungen ADR002 in den bestehenden Domain- und Methodology-Dokumenten auslöst.

ADR002 führt drei fachlich getrennte Begriffe ein:

- `SourceSystem`: fachliches Ursprungssystem
- `SourceDelivery`: konkrete Datenlieferung
- `DeliveryChannel`: optionaler technischer Übertragungsweg

Zugleich legt ADR002 fest:

```text
SourceSystem
    │
    └── SourceDelivery ─── DeliveryChannel [0..1]
            │
            └── SourceValue [1..*]
```

`SourceValue` bleibt ein eigenständiges Aggregate und referenziert genau eine `SourceDelivery`.

## 2. Overall Impact

| Document | Impact | Required action |
|---|---:|---|
| DM001 v0.4 | high | neue Domain Objects, Beziehungen, Invarianten und UML-Erweiterung |
| DM002 v0.3 | high | neue Tabellen/Referenzen, Anpassung von `source_value`, Lösch- und Repository-Regeln |
| ME001 v0.2-alpha | none / editorial only | keine fachliche Änderung erforderlich; Related-Verweis prüfen |
| ME002 v0.6 | low to medium | Eingang des Workflows und Processing Context um `SourceDelivery` präzisieren |
| Code / Runtime | future implementation impact | nicht Bestandteil dieser Analyse; nach Freigabe von DM001 und DM002 planen |

## 3. Impact on DM001

### 3.1 Purpose and Core Model

Der bisherige fachliche Kern beginnt unmittelbar mit `SourceValue`:

```text
SourceValue
→ InterpretationGraph
→ InterpretationNode
→ ReconciliationResult
→ CandidateItem
→ MatchDecision
```

Dieser Reconciliation-Kern bleibt unverändert.

DM001 v0.5 muss jedoch eine vorgelagerte Provenienz- und Gruppierungsebene ergänzen:

```text
SourceSystem
    │
    └── SourceDelivery ─── DeliveryChannel [0..1]
            │
            └── SourceValue [1..*]
                    │
                    └── InterpretationGraph [1..*]
```

Wichtig: `SourceSystem`, `SourceDelivery` und `DeliveryChannel` gehören nicht zur iterativen Interpretation Pipeline. Sie bilden deren fachlichen Eingangskontext.

### 3.2 New Domain Objects

#### `SourceSystem`

Erforderliche fachliche Mindestattribute:

| Attribute | Meaning |
|---|---|
| `id` | stabile interne Identität |
| `name` | lesbare Bezeichnung des Ursprungssystems |
| `uri` | optionale stabile fachliche URI |

Empfehlung für DM001:
- `id` verpflichtend
- `name` verpflichtend
- `uri` optional

Die Frage, ob `uri` bereits in v0.5 verpflichtend sein soll, sollte LA prüfen.

#### `SourceDelivery`

Erforderliche fachliche Mindestattribute:

| Attribute | Meaning |
|---|---|
| `id` | stabile interne Identität |
| `sourceSystemId` | Referenz auf genau ein `SourceSystem` |
| `deliveryChannel` | optionale Referenz bzw. Klassifikation |
| `receivedAt` | Zeitpunkt, zu dem Reconcilix die Lieferung übernommen hat |
| `externalDeliveryId` | optionale Kennung aus dem Quell- oder Transportprozess |

Empfehlung:
- Nur Attribute aufnehmen, die für Identität, Zuordnung und Nachvollziehbarkeit notwendig sind.
- Importstatus, Batchstatus, Dateiname, API Request oder technische Payload bleiben außerhalb von DM001 v0.5.

#### `DeliveryChannel`

ADR002 führt `DeliveryChannel` konzeptionell ein, legt aber Identität, Attribute und Persistenz bewusst nicht fest.

Für DM001 v0.5 ist deshalb eine schlanke Modellierung angemessen:

```text
DeliveryChannel = controlled value / value object
```

Mögliche Werte:

```text
OPENREFINE_RECONCILIATION_API
CSV_IMPORT
REST_API
BATCH_IMPORT
```

Empfehlung:
- In DM001 zunächst als optionaler klassifizierender Wert bzw. Value Object modellieren.
- Noch kein eigenständiges Aggregate.
- Keine vollständige Lifecycle-Modellierung.
- Eine spätere URI-basierte kontrollierte Liste bleibt möglich.

### 3.3 Change to `SourceValue`

DM001 v0.4 enthält aktuell:

- `provenance`
- `sourceField`
- `sourceRecordId`

ADR002 macht eine Präzisierung erforderlich.

Empfohlene Änderung:

| Current | DM001 v0.5 |
|---|---|
| `provenance` | entfernen oder klar auf wertbezogene Rest-Provenienz begrenzen |
| `sourceDeliveryId` | neu, verpflichtend |
| `sourceField` | bleibt |
| `sourceRecordId` | bleibt |

Begründung:

`SourceSystem` und `DeliveryChannel` dürfen nach ADR002 nicht weiter undifferenziert in `SourceValue.provenance` verborgen bleiben. Andernfalls existierten strukturierte und unstrukturierte Provenienz parallel.

Empfehlung:
- `sourceDeliveryId` wird verpflichtende Referenz.
- `provenance` wird nicht ersatzlos gelöscht, sondern als optionale wertbezogene Zusatzprovenienz präzisiert, z. B. Transformationshinweise oder quellwertspezifische Metadaten.
- DM001 muss ausdrücklich festhalten, dass `provenance` nicht die Rollen von `SourceSystem`, `SourceDelivery` oder `DeliveryChannel` dupliziert.

### 3.4 Aggregate Boundaries

ADR002 bestätigt:

- `SourceValue` bleibt eigenständiges Aggregate.
- `SourceDelivery` gruppiert `SourceValue`.
- `SourceDelivery` übernimmt nicht deren vollständigen Lebenszyklus.

Daraus folgen für DM001 v0.5:

1. `SourceSystem` ist ein eigenständiges Aggregate.
2. `SourceDelivery` ist ein eigenständiges Aggregate.
3. `SourceValue` ist weiterhin ein eigenständiges Aggregate.
4. Beziehungen zwischen den Aggregaten werden über stabile Identitäten ausgedrückt.
5. `DeliveryChannel` wird vorerst als Value Object oder kontrollierter Wert innerhalb von `SourceDelivery` behandelt.

### 3.5 New Invariants

DM001 v0.5 sollte mindestens folgende Invarianten aufnehmen:

1. Jede `SourceDelivery` referenziert genau ein existierendes `SourceSystem`.
2. Jede `SourceDelivery` referenziert höchstens einen `DeliveryChannel`.
3. Jeder `SourceValue` referenziert genau eine existierende `SourceDelivery`.
4. Eine `SourceDelivery` gruppiert fachlich mindestens einen `SourceValue`.
5. `SourceValue.provenance` darf die strukturierte Zuordnung zu `SourceSystem`, `SourceDelivery` und `DeliveryChannel` nicht ersetzen.
6. Ein `DeliveryChannel` ist kein fachliches Ursprungssystem.
7. Ein Wechsel des technischen Übertragungswegs erzeugt nicht automatisch ein neues `SourceSystem`.

Die Mindestkardinalität `SourceDelivery → SourceValue [1..*]` ist fachlich eindeutig. Technisch kann während einer Transaktion kurzzeitig eine leere Lieferung entstehen; dieser technische Zwischenzustand gehört in DM002 bzw. die Application Layer, nicht in die fachliche Definition.

### 3.6 Existing Naming Conflict

DM001 v0.4 verwendet bei `CandidateItem` das Attribut:

```text
sourceSystem
```

mit der Bedeutung:

```text
Zielsystem oder Datenquelle
```

Das kollidiert semantisch mit dem neuen, klar definierten `SourceSystem` aus ADR002.

Empfehlung für DM001 v0.5:

```text
CandidateItem.sourceSystem
```

umbenennen in beispielsweise:

```text
targetSourceSystemUri
```

oder präziser:

```text
candidateSourceUri
```

Bevorzugte Variante:

```text
candidateSourceSystemUri
```

Damit bleibt klar:

- `SourceValue → SourceDelivery → SourceSystem` beschreibt die Herkunft des Eingangswerts.
- `CandidateItem.candidateSourceSystemUri` beschreibt das Ziel- bzw. Herkunftssystem des Candidates.

Diese Namensbereinigung ist ein notwendiger Bestandteil von DM001 v0.5, auch wenn sie nicht unmittelbar durch neue Kardinalitäten ausgelöst wird.

### 3.7 Sections to Update in DM001

| DM001 section | Change |
|---|---|
| 1 Purpose | vorgelagerte Herkunfts- und Lieferungsebene ergänzen |
| 2 Use Cases | klarstellen, dass alle Use Cases in einer `SourceDelivery` verarbeitet werden |
| 3 Core Domain Classes | `SourceSystem`, `SourceDelivery`, `DeliveryChannel` ergänzen; `SourceValue` ändern |
| 3.6 CandidateItem | `sourceSystem` semantisch präzisieren/umbenennen |
| 5 UML Class Diagram | neues Modell und Kardinalitäten ergänzen |
| 7 Implementation Boundary | Delivery Objects zunächst unabhängig von Transportimplementierung halten |
| 8 Deferred Design Questions | URI-Pflicht, DeliveryChannel-Vokabular und Lifecycle-Fragen aufnehmen |

## 4. Impact on DM002

### 4.1 New Relational Structures

DM002 v0.4 benötigt mindestens:

```text
source_system
source_delivery
source_value.source_delivery_id
```

Für `DeliveryChannel` bestehen zwei mögliche Persistenzvarianten:

#### Option A — scalar value in `source_delivery`

```text
source_delivery.delivery_channel_uri NULL
```

Vorteile:
- KISS
- entspricht der derzeit bewusst schlanken Modellierung
- keine unnötige Tabelle

#### Option B — separate `delivery_channel` table

```text
delivery_channel
source_delivery.delivery_channel_id NULL
```

Vorteile:
- kontrollierte, zentral verwaltete Werte
- zusätzliche Metadaten später möglich

Empfehlung für DM002 v0.4:

**Option A: `delivery_channel_uri` als nullable Spalte.**

Begründung:
ADR002 führt `DeliveryChannel` nur konzeptionell ein. Eine eigene Tabelle würde bereits Identität und Lifecycle festlegen, die ausdrücklich noch offen sind.

### 4.2 Proposed Tables

#### `source_system`

Vorläufige Mindeststruktur:

| Column | Type | Constraint |
|---|---|---|
| `id` | BIGINT UNSIGNED | PK |
| `name` | VARCHAR | NOT NULL |
| `uri` | VARCHAR(512) | NULL oder UNIQUE |
| `created_at` | DATETIME(6) | NOT NULL |

#### `source_delivery`

Vorläufige Mindeststruktur:

| Column | Type | Constraint |
|---|---|---|
| `id` | BIGINT UNSIGNED | PK |
| `source_system_id` | BIGINT UNSIGNED | FK, NOT NULL |
| `delivery_channel_uri` | VARCHAR(512) | NULL |
| `external_delivery_id` | VARCHAR | NULL |
| `received_at` | DATETIME(6) | NOT NULL |
| `created_at` | DATETIME(6) | NOT NULL |

#### `source_value`

Neue Spalte:

| Column | Type | Constraint |
|---|---|---|
| `source_delivery_id` | BIGINT UNSIGNED | FK, NOT NULL |

`provenance_json` kann vorerst bestehen bleiben, muss aber semantisch auf ergänzende wertbezogene Provenienz begrenzt werden.

### 4.3 Referential Integrity

Neue Referenzen:

```text
source_delivery.source_system_id
    → source_system.id

source_value.source_delivery_id
    → source_delivery.id
```

Empfohlene Löschregeln:

- `source_system` mit vorhandenen `source_delivery` darf nicht gelöscht werden (`RESTRICT`).
- `source_delivery` mit vorhandenen `source_value` darf nicht gelöscht werden (`RESTRICT`).
- Kaskadierung von `source_delivery` nach `source_value` wird nicht empfohlen, weil `SourceValue` ein eigenständiges Aggregate bleibt.

### 4.4 Repository Impact

DM002 v0.4 muss die Repository Boundary erweitern um:

```text
SourceSystemRepository
SourceDeliveryRepository
```

`SourceValueRepository` bleibt eigenständig, benötigt jedoch:

- Persistenz von `sourceDeliveryId`
- Rehydration der Referenz
- Validierung bzw. Übersetzung referenzieller Fehler

Keine Aggregate-übergreifende automatische Speicherung:

```text
SourceDeliveryRepository.save()
```

speichert nicht automatisch alle zugeordneten `SourceValue`.

### 4.5 Transaction Impact

Das Anlegen einer vollständigen Lieferung verlangt typischerweise:

```text
SourceSystem resolve/create
→ SourceDelivery create
→ SourceValue create*
```

Diese Koordination gehört in einen Application Service und kann eine Transaktion verwenden.

Sie verändert jedoch nicht die Aggregate-Grenzen.

### 4.6 Migration Impact

DM002 v0.4 muss eine Migrationsstrategie für bestehende `source_value`-Datensätze definieren.

Da `source_delivery_id` fachlich verpflichtend wird, sind mindestens folgende Schritte nötig:

1. Default-/Legacy-`SourceSystem` anlegen.
2. Legacy-`SourceDelivery` anlegen.
3. Bestehende `source_value` diesem Datensatz zuordnen.
4. `source_delivery_id` auf `NOT NULL` setzen.

Die konkrete Benennung des Legacy-Systems darf nicht mit einem realen Quellsystem verwechselt werden. Denkbar:

```text
Legacy / Unknown Source
```

Diese Frage gehört zur DM002- und Migrationsfreigabe durch LA.

### 4.7 Existing Schema Naming Conflict

`candidate_item.source_system_uri` ist bereits vorhanden und bezeichnet das System des Candidates.

Mit ADR002 entsteht zusätzlich `source_system` als Entität des Eingangssystems.

Empfehlung:

- fachlich in DM001 präzisieren,
- in DM002 prüfen, ob `candidate_item.source_system_uri` zu `candidate_source_system_uri` migriert werden soll.

Eine sofortige Datenbankumbenennung ist nicht zwingend, erhöht aber langfristig die semantische Klarheit.

## 5. Impact on ME001

ME001 definiert:

- `InterpretationProperty`
- `VocabularyMatchingPattern`

ADR002 verändert weder die intrinsischen Eigenschaften einer `InterpretationNode` noch die relationale Klassifikation eines `ReconciliationResult`.

Daher:

```text
ME001: keine fachliche Änderung erforderlich
```

Empfohlene redaktionelle Prüfung:

- `Related`-Angabe auf DM001 v0.5 aktualisieren.
- Keine neuen `InterpretationProperty` oder `VocabularyMatchingPattern` aus Herkunft oder Delivery Channel ableiten.
- Insbesondere darf `DeliveryChannel` nicht als Matching Pattern modelliert werden.

Ergebnis:

**Keine neue ME001-Version allein aufgrund ADR002 erforderlich.**

## 6. Impact on ME002

ME002 beschreibt derzeit die Verarbeitung beginnend mit:

```text
1. Receive SourceValue and ContextItems
```

Mit ADR002 muss der fachliche Eingang präzisiert werden.

Empfohlene Änderung:

```text
1. Receive or resolve SourceDelivery
2. Receive SourceValue and ContextItems within that SourceDelivery
3. Determine one or more interpretable spans
...
```

Alternativ schlanker:

```text
1. Receive SourceValue, its SourceDelivery reference and ContextItems
```

### 6.1 Processing Objects

Die Reconciliation Pipeline bleibt:

```text
SourceValue
→ InterpretationGraph
→ InterpretationNode
→ ReconciliationResult
→ CandidateItem
→ MatchDecision
```

`SourceDelivery` ist kein neuer Pipeline-Schritt.

ME002 sollte jedoch klarstellen:

- Jeder verarbeitete `SourceValue` besitzt einen Delivery Context.
- `SourceSystem` und `DeliveryChannel` sind Provenienz, keine Matching Technique.
- Sie beeinflussen die Matching Strategy nicht automatisch.
- Eine spätere strategy-relevante Verwendung von Herkunftsinformationen benötigt eine eigene methodische Entscheidung.

### 6.2 Context Boundary

ADR002 wirft eine Abgrenzungsfrage zu `ContextItem` auf.

Empfehlung:

- `SourceSystem`, `SourceDelivery` und `DeliveryChannel` sind keine `ContextItem`.
- Fachliche Informationen aus der Lieferung können weiterhin als `ContextItem` vorliegen.
- Delivery Metadata wird nicht automatisch in interpretativen Kontext umgedeutet.

### 6.3 Evaluation and Reporting

ME002 kann optional ergänzen, dass Ergebnisse künftig nach

- `SourceSystem`
- `SourceDelivery`
- `DeliveryChannel`

gruppiert oder ausgewertet werden können.

Das ist Reporting-Provenienz, keine Veränderung der Reconciliation Methodology.

### 6.4 Version Consequence

Empfehlung:

```text
ME002 v0.7
```

erst nach Abschluss und LA-Freigabe von DM001 v0.5 und DM002 v0.4 erstellen.

Der erwartete Änderungsumfang ist klein, aber fachlich relevant genug für eine neue Version.

## 7. Recommended Sequence

```text
ADR002 V4 (Accepted)
    ↓
Impact Analysis ADR002 on DM + ME
    ↓
DM001_Domain_Model_v0.5_DRAFT_ED
    ↓
DM002_Persistence_Model_v0.4_DRAFT_ED
    ↓
LA Review of DM001 + DM002
    ↓
consolidated DM001 v0.5 + DM002 v0.4
    ↓
ME001 consistency check
    ↓
ME002 v0.7 draft if confirmed
    ↓
LA / methodological review as appropriate
    ↓
implementation planning
```

## 8. Decisions Recommended for DM001/DM002 Drafting

The following working decisions are recommended:

1. `SourceSystem`, `SourceDelivery` and `SourceValue` remain separate aggregates.
2. `DeliveryChannel` is initially a controlled value / Value Object, not an aggregate.
3. `SourceValue.sourceDeliveryId` is mandatory.
4. `SourceValue.provenance` remains only for supplementary value-level provenance.
5. `CandidateItem.sourceSystem` is renamed semantically to avoid collision.
6. DM002 uses `source_delivery.delivery_channel_uri` rather than a separate table.
7. Foreign-key deletion rules use `RESTRICT`, not aggregate-spanning cascades.
8. ME001 remains unchanged apart from references.
9. ME002 receives a small update after DM001 and DM002 are accepted.

## 9. Open Questions for LA Review of DM001/DM002

1. Soll `SourceSystem.uri` bereits verpflichtend sein oder zunächst optional bleiben?
2. Ist `DeliveryChannel` in DM001 als Value Object oder als controlled classification zu bezeichnen?
3. Soll `candidate_item.source_system_uri` bereits in DM002 v0.4 umbenannt werden?
4. Wie soll die Legacy-Migration bestehender `source_value` fachlich benannt werden?
5. Gehört `externalDeliveryId` bereits in v0.5/v0.4 oder soll es zunächst zurückgestellt werden?
6. Soll die Invariante `SourceDelivery [1..*] SourceValue` nur fachlich oder auch unmittelbar technisch erzwungen werden?