# WP3-001 – Discovery Framework Foundation

- **Status:** Closed (PL, 2026-08-01, 13:00 Uhr)
- **Version:** 0.2
- **Scope:** WP3 – Candidate Discovery
- **Owner:** ED
- **Review:** PL, LA

## Änderungsstand

### Version 0.2

Einarbeitung von LA Review 001 sowie Konsolidierung der Teilpakete WP3-001-001 bis WP3-001-005.

**Änderungen**

- Foundation-Dokument als Index- und Steuerungsdokument geschärft.
- Discovery Scope (`scopeVocabularyUri`) ergänzt.
- DiscoveryConfigurationRegistry liefert `DiscoveryRoute[]`.
- CandidateDiscoveryAdapterRegistry ergänzt.
- CandidateDiscoveryRouter implementiert den `CandidateDiscoveryGateway`.
- Runtime Integration über `LegacyDiscoveryCompatibilityAdapter` präzisiert.
- Rückgabetyp auf `DiscoveredCandidate[]` umgestellt.

---

## Referenzen

- PRE_WP3-001 – Architekturübersicht Discovery Framework
- ADR002 – Source Delivery Model
- DM001 – Domain Model
- DM002 – Persistence Model

---

# 1. Ziel

WP3-001 überführt die in PRE_WP3-001 akzeptierte Architektur des Discovery Frameworks schrittweise in die bestehende Reconcilix-Implementierung.

Dieses Dokument dient als **Index- und Steuerungsdokument** für die Teilpakete WP3-001-001 bis WP3-001-005.

Das Work Package führt schrittweise folgende Infrastrukturkomponenten ein:

- Discovery Route Model
- Discovery Configuration Registry
- Candidate Discovery Adapter Contract
- Candidate Discovery Adapter Registry
- Candidate Discovery Router
- Runtime Integration

Das bestehende Candidate-Discovery-Verhalten wird während WP3-001 fachlich nicht verändert.

---

# 2. Engineering-Grundsatz

WP3-001 wird nicht als einzelnes umfassendes Implementierungspaket umgesetzt.

Die Einführung des Discovery Frameworks erfolgt in fünf voneinander abgegrenzten Teilpaketen.

Jedes Teilpaket

- führt genau eine neue Verantwortung ein,
- besitzt eigene Akzeptanzkriterien,
- wird separat reviewt,
- wird separat implementiert,
- wird separat getestet,
- und bildet die Grundlage für das jeweils folgende Teilpaket.

Damit folgt WP3-001 dem bereits in WP2 und ED-04 bewährten iterativen Vorgehen.

---

# 3. Zielstruktur

Nach Abschluss von WP3-001 besitzt Reconcilix folgende grundlegende Laufzeitstruktur:

```text
ReconciliationApplicationService
        │
        ▼
CandidateDiscoveryGateway
        │
        ▼
CandidateDiscoveryRouter
        │
        ├── DiscoveryConfigurationRegistry
        │       └── DiscoveryRoute[]
        │
        ├── CandidateDiscoveryAdapterRegistry
        │       └── CandidateDiscoveryAdapter
        │
        ▼
LegacyDiscoveryCompatibilityAdapter
        │
        ▼
bestehende Candidate Discovery
        │
        ▼
DiscoveredCandidate[]
```

Während WP3-001 bleibt die bestehende Candidate Discovery unverändert.

Lediglich die Infrastruktur und die Runtime-Verdrahtung werden schrittweise ersetzt.

---

# 4. Teilpakete

## WP3-001-001 – Discovery Route Model

Einführung der Klasse `DiscoveryRoute`.

Schwerpunkte:

- Trennung zwischen `targetVocabularyUri` und `scopeVocabularyUri`
- fachliche Discovery-Konfiguration
- Invarianten
- Unit Tests

---

## WP3-001-002 – Discovery Configuration Registry

Einführung der `DiscoveryConfigurationRegistry`.

Schwerpunkte:

- Verwaltung von `DiscoveryRoute`
- Auflösung über `scopeVocabularyUri`
- Rückgabe von `DiscoveryRoute[]`
- keine Auswahlentscheidung

---

## WP3-001-003 – Candidate Discovery Adapter Contract and Registry

Einführung

- des `CandidateDiscoveryAdapter`
- der `CandidateDiscoveryAdapterRegistry`

Schwerpunkte:

- gemeinsamer Adaptervertrag
- Adapterverwaltung
- Contract Tests

---

## WP3-001-004 – Candidate Discovery Router

Einführung des `CandidateDiscoveryRouter`.

Schwerpunkte:

- Implementierung des `CandidateDiscoveryGateway`
- Validierung der Route-Kardinalität
- Delegation an Candidate Discovery Adapter

---

## WP3-001-005 – Runtime Integration

Integration des Discovery Frameworks in die bestehende Reconcilix-Runtime.

Schwerpunkte:

- Composition Root
- LegacyDiscoveryCompatibilityAdapter
- Runtime-Verdrahtung
- Integrationstests
- Regressionstests

---

# 5. Paketabhängigkeiten

```text
WP3-001-001
Discovery Route Model
        │
        ▼
WP3-001-002
Discovery Configuration Registry
        │
        ▼
WP3-001-003
Candidate Discovery Adapter Contract and Registry
        │
        ▼
WP3-001-004
Candidate Discovery Router
        │
        ▼
WP3-001-005
Runtime Integration
```

Jedes Teilpaket setzt den erfolgreichen Abschluss und die Tests des vorhergehenden Teilpakets voraus.

---

# 6. Übergreifende Akzeptanzkriterien

WP3-001 ist abgeschlossen, wenn

1. Discovery Routes durch ein eigenes Modell repräsentiert werden.
2. Die DiscoveryConfigurationRegistry `DiscoveryRoute[]` bereitstellt.
3. Die CandidateDiscoveryAdapterRegistry Candidate Discovery Adapter verwaltet.
4. Der CandidateDiscoveryRouter den `CandidateDiscoveryGateway` implementiert und Discovery-Anfragen an genau einen CandidateDiscoveryAdapter delegiert.
5. Die Runtime den `LegacyDiscoveryCompatibilityAdapter` als Übergangslösung verwendet.
6. Die bestehende Discovery weiterhin dieselben `DiscoveredCandidate[]` liefert.
7. Alle bestehenden Tests weiterhin erfolgreich sind.
8. Für jedes Teilpaket eigene Unit- oder Integrationstests vorhanden sind.
9. Keine produktive xTree- oder Local-Store-Neuimplementierung Bestandteil von WP3-001 ist.

---

# 7. Out of Scope

Nicht Bestandteil von WP3-001 sind

- produktive Neuimplementierung des Local Reconciliation Store Adapters
- produktive Integration der xTree JSON API
- HTTP- oder SPARQL-Kommunikation
- mehrere parallel ausgeführte Discovery Routes
- Priorisierung
- Hybrid Discovery
- Ranking
- Result Fusion
- neue Matching- oder Discovery-Verfahren
- Änderungen am Domain Model
- Änderungen am Persistence Model
- fachliche Änderungen am Reconciliation Flow

---

# 8. Nachfolgende Work Packages

Nach Abschluss von WP3-001 gilt der vereinbarte Ablauf:

```text
WP3-001
Discovery Framework Foundation
        │
        ▼
ED-04-007
source_value.source_delivery_id
        │
        ▼
ED-04-008
delivery_id aus OpenRefine übernehmen
        │
        ▼
WP3-002
Local Reconciliation Store Adapter
        │
        ▼
WP3-003
xTree Candidate Discovery Adapter
        │
        ▼
WP3-004
Discovery Configuration Integration
        │
        ▼
WP3-005
End-to-End Candidate Discovery
```

---

# 9. Umsetzungsmethode

Für jedes Teilpaket gilt der etablierte Reconcilix-Workflow:

```text
ED erstellt das Work Package

        ↓

PL prüft Scope und Verständlichkeit

        ↓

LA prüft Architektur und Verantwortlichkeiten

        ↓

ED implementiert und testet

        ↓

ED liefert ausschließlich neue oder geänderte Dateien

        ↓

PL spielt das Update ein und führt die Gesamttests durch
```

Erst nach erfolgreicher Abnahme beginnt das nächste Teilpaket.