# ED-01-003 – Application Integration
## Status
Draft v0.1
## Übergeordnetes Arbeitspaket
[ED-01 – Context Mapping](ED-01_Context_Mapping.md)
## Vorgänger
- [ED-01-001 – Domain Model](ED-01-001_Domain_Model.md)
- [ED-01-002 – Transport Mapping](ED-01-002_Transport_Mapping.md)
## Ziel
Dieser Arbeitsschritt integriert die in `ED-01-002` gemappten Context-Daten in die Command- und Application-Schicht von Reconcilix.
Die Context-Daten werden an den bestehenden Verarbeitungsfluss übergeben und beim Aufbau eines `SourceValue` in `ContextItem`-Objekte überführt.
Am Ende dieses Arbeitsschritts stehen die von OpenRefine gelieferten Context Properties vollständig im Domain Model zur Verfügung.
Es erfolgt weiterhin
- keine Persistierung,
- keine fachliche Interpretation,
- keine Verwendung in der Candidate Discovery.
## Ausgangssituation
`ED-01-001` führt das Domain-Objekt `ContextItem` ein und erweitert `SourceValue` um eine Menge von ContextItems.
`ED-01-002` erweitert das OpenRefine-Request-Mapping um eine transportnahe Repräsentation der Context Properties.
Der bestehende Verarbeitungsfluss ist sinngemäß:
```text
OpenRefine Request
↓
OpenRefineRequestMapper
↓
Reconciliation Command
↓
Application Service
↓
SourceValue
```
Dieser Arbeitsschritt erweitert den Fluss um die Context-Daten:
```text
OpenRefine Request
↓
OpenRefineRequestMapper
↓
Reconciliation Command
├── source value
└── context inputs*
↓
Application Service
↓
SourceValue
└── ContextItem*
```
## Verantwortlichkeiten
### Transport-Schicht
Die Transport-Schicht liefert die bereits strukturell gemappten Context-Daten.
Beispiel:
```text
ContextInput
------------
contextTypeUri
value
```
Sie erzeugt noch keine Domain-Objekte, sofern dies der bestehenden Schichtentrennung des Projekts entspricht.
### Command-Schicht
Der Reconciliation Command wird um die Context-Daten erweitert.
Sinngemäß:
```text
ReconcileCommand
----------------
...
contextInputs*
```
Die konkrete Benennung richtet sich nach der bestehenden Command-Struktur.
Der Command transportiert die Context-Daten unverändert in die Application-Schicht.
### Application-Schicht
Der Application Service ist verantwortlich für
- die Entgegennahme der Context-Daten,
- die Erzeugung von `ContextItem`-Objekten,
- die Zuordnung der ContextItems zum zugehörigen `SourceValue`,
- die unveränderte Fortführung des bestehenden Verarbeitungsflusses.
## Erzeugung von ContextItem
Für jeden übergebenen Context-Eintrag wird genau ein `ContextItem` erzeugt.
Mapping:
```text
ContextInput.contextTypeUri
↓
ContextItem.contextTypeUri
ContextInput.value
↓
ContextItem.value
```
Beispiel:
```text
ContextInput
------------
contextTypeUri =
https://reconcilix.vocnet.org/context/0001
value =
...
```
wird zu:
```text
ContextItem
-----------
contextTypeUri =
https://reconcilix.vocnet.org/context/0001
value =
...
```
## Zuordnung zu SourceValue
Alle ContextItems eines Requests werden dem SourceValue zugeordnet, auf den sich der jeweilige OpenRefine-Reconciliation-Request bezieht.
Sinngemäß:
```text
SourceValue
-----------
originalValue = Bronze
contextItems =
- TEI Context
- Text Context
```
Ein ContextItem darf in diesem Arbeitsschritt nicht unabhängig von einem SourceValue weitergegeben oder verwaltet werden.
## Verhalten ohne Context
Enthält der Request keine Context Properties, wird der bestehende Verarbeitungsfluss unverändert ausgeführt.
Sinngemäß:
```text
contextInputs = []
↓
SourceValue.contextItems = []
```
Es entstehen keine Platzhalter- oder Null-Objekte.
## Verhalten mit mehreren ContextItems
Werden mehrere Context Properties übertragen, werden alle ContextItems erzeugt und demselben SourceValue zugeordnet.
Die Reihenfolge aus dem Transport-Mapping bleibt erhalten.
Beispiel:
```text
SourceValue: Kiel
ContextItems:
1. Parent Place
2. Geographic Coordinates
3. Text Context
```
## Fehlerverhalten
Die Application-Schicht setzt voraus, dass die strukturelle Prüfung bereits im Transport-Mapping erfolgt ist.
Verletzt ein Context-Eintrag dennoch die Domain-Invarianten von `ContextItem`, ist das bestehende Domain-Fehlerverhalten anzuwenden.
Es wird keine separate Fehlerstrategie ausschließlich für ContextItems eingeführt.
Insbesondere erfolgt keine
- automatische Korrektur,
- Ersetzung unbekannter Context Types,
- inhaltliche Normalisierung,
- stille Erzeugung unvollständiger ContextItems.
## Rückwärtskompatibilität
Bestehende Aufrufer ohne Context-Daten müssen unverändert funktionieren.
Neue Command-Parameter für Context-Daten müssen daher so integriert werden, dass bestehende Tests und interne Aufrufe weiterhin gültig bleiben.
Je nach bestehender Konstruktion kann dies beispielsweise erfolgen durch
- eine optionale leere Collection,
- einen Default-Wert,
- eine kompatible Factory-Methode.
Die konkrete Lösung richtet sich nach den vorhandenen Projektkonventionen.
## Betroffene Komponenten
Voraussichtlich betroffen:
- Reconciliation Command oder vergleichbares Input-Objekt,
- zugehörige Command Factory,
- Application Service,
- Factory oder Builder für `SourceValue`,
- gegebenenfalls Composition Root,
- Unit-Tests der Command- und Application-Schicht.
Nicht betroffen:
- Repositories,
- Persistence Mapper,
- Datenbankschema,
- Candidate Discovery Adapter,
- xTree-Adapter.
## Implementierungsschritte
### 1. Command-Struktur erweitern
Die vorhandene Command-Struktur erhält eine Collection für Context-Eingaben.
Anforderungen:
- nullfreie Collection,
- leere Collection als Standardfall,
- unveränderte Übergabe der gemappten Werte.
### 2. Request Mapper anbinden
Die in `ED-01-002` erzeugten Context-Eingaben werden beim Aufbau des Commands übergeben.
### 3. Domain-Objekte erzeugen
Die Application-Schicht erzeugt aus jedem Context-Eingang ein `ContextItem`.
### 4. SourceValue erweitern
Die erzeugten ContextItems werden dem zugehörigen `SourceValue` hinzugefügt.
### 5. Bestehenden Verarbeitungsfluss fortführen
Nach der Domain-Erzeugung läuft die vorhandene Reconciliation-Verarbeitung unverändert weiter.
Die Candidate Discovery ignoriert die ContextItems bis `ED-03`.
## Tests
Mindestens folgende Fälle sind innerhalb dieses Arbeitsschritts vorzubereiten beziehungsweise abzudecken:
### Command ohne Context-Daten
Erwartung:
- Command ist gültig,
- Context-Collection ist leer,
- bestehende Verarbeitung bleibt unverändert.
### Command mit einem Context-Eintrag
Erwartung:
- genau ein `ContextItem` wird erzeugt,
- `contextTypeUri` und `value` werden unverändert übernommen,
- das ContextItem ist dem richtigen SourceValue zugeordnet.
### Command mit mehreren Context-Einträgen
Erwartung:
- alle ContextItems werden erzeugt,
- alle ContextItems gehören zum selben SourceValue,
- Reihenfolge bleibt erhalten.
### Ungültiges ContextItem
Erwartung:
- Domain-Invariante greift,
- vorhandenes Fehlerverhalten wird verwendet,
- kein unvollständiges ContextItem gelangt in das SourceValue.
### Rückwärtskompatibilität
Erwartung:
- bestehende Aufrufe ohne Context-Daten funktionieren unverändert,
- alle bisherigen Application-Tests bleiben erfolgreich.
## Nicht Bestandteil
Nicht Bestandteil von `ED-01-003` sind:
- Persistierung von ContextItems,
- Änderungen am relationalen Schema,
- Verwendung der ContextItems bei Candidate Discovery,
- Interpretation von XML, Text, Datumsangaben oder Koordinaten,
- Validierung gegen `VOC001_Context_Types`,
- Prüfung der Zulässigkeit für Entity Types,
- Abhängigkeiten von Vocabulary, Tenant oder Provider,
- Einführung von SourceDelivery oder SourceSystem in den Laufzeitfluss.
## Abnahmekriterien
- Die Command-Schicht transportiert Context-Daten vollständig.
- Die Application-Schicht erzeugt für jeden Context-Eintrag ein `ContextItem`.
- Alle erzeugten ContextItems werden dem korrekten `SourceValue` zugeordnet.
- Requests ohne Context-Daten verhalten sich unverändert.
- Mehrere ContextItems werden vollständig und in stabiler Reihenfolge verarbeitet.
- Domain-Invarianten werden eingehalten.
- Candidate Discovery und Persistenz bleiben unverändert.
- Alle bestehenden Tests bleiben erfolgreich.
## Nachfolger
[ED-01-004 – Tests](ED-01-004_Tests.md)