# WP3-001-003 – Candidate Discovery Adapter Contract

- **Status:** Draft
- **Version:** 0.1
- **Scope:** WP3 – Discovery Framework Foundation
- **Owner:** ED
- **Review:** PL, LA

## Referenzen

- WP3-001 – Discovery Framework Foundation
- WP3-001-001 – Discovery Route Model
- WP3-001-002 – Discovery Configuration Registry
- PRE_WP3-001 – Architekturübersicht Discovery Framework
- DM001 – Domain Model

---

# 1. Ziel

Dieses Work Package definiert den gemeinsamen technischen Vertrag für alle Candidate Discovery Adapter.

Der Vertrag stellt sicher, dass unterschiedliche technische Implementierungen über eine einheitliche Schnittstelle angesprochen werden können.

Die konkrete Discovery-Logik ist nicht Bestandteil dieses Work Packages.

---

# 2. Scope

Dieses Work Package umfasst ausschließlich

- Einführung des Interface `CandidateDiscoveryAdapter`
- Definition des gemeinsamen Adapter Contracts
- Bereitstellung eines Test- bzw. Dummy-Adapters
- Contract Tests

Nicht Bestandteil sind

- Local Reconciliation Store Adapter
- xTree Adapter
- HTTP-Kommunikation
- REST
- SPARQL
- Candidate Discovery Router
- Runtime Integration

---

# 3. Architekturbezug

PRE_WP3 beschreibt den **Technical Adapter** als technische Umsetzung einer Discovery Route.

WP3-001-003 konkretisiert diesen Architekturbaustein durch das Interface

`CandidateDiscoveryAdapter`.

Alle zukünftigen technischen Discovery-Implementierungen verwenden diesen gemeinsamen Vertrag.

---

# 4. Klassenübersicht

| Klasse | Typ | Status | Verantwortung |
|---------|-----|--------|----------------|
| CandidateDiscoveryAdapter | Interface | Neu | Gemeinsamer technischer Vertrag |
| DummyCandidateDiscoveryAdapter | Testklasse | Neu | Testimplementierung |
| DiscoveryRoute | Class | Bestehend | Referenziert einen Adapter |

---

# 5. Verantwortung

Ein CandidateDiscoveryAdapter ist verantwortlich für

- Entgegennahme einer Discovery-Anfrage
- Durchführung der technischen Discovery
- Rückgabe von Candidate Items

Ein CandidateDiscoveryAdapter ist nicht verantwortlich für

- Auswahl einer Discovery Route
- Verwaltung der Discovery Configuration
- Routing
- Match Decision
- Persistenz
- Runtime Configuration

---

# 6. Adapter Contract

Alle Adapter erfüllen denselben Vertrag.

Beispiele zukünftiger Implementierungen

- LocalReconciliationStoreAdapter
- XTreeJsonApiAdapter
- LobidAdapter
- QLeverAdapter
- QdrantAdapter

Dadurch bleibt der Router unabhängig von technischen Implementierungen.

---

# 7. Invarianten

Alle CandidateDiscoveryAdapter

- implementieren denselben Contract
- liefern CandidateItem zurück
- kennen keine DiscoveryConfigurationRegistry
- treffen keine Routingentscheidung
- kennen keine weiteren Adapter

---

# 8. Implementierungsreihenfolge

1. Interface CandidateDiscoveryAdapter erstellen
2. DummyAdapter implementieren
3. Contract Tests erstellen
4. Bestehende Tests ausführen

---

# 9. Deliverables

Neue Klassen

- CandidateDiscoveryAdapter
- DummyCandidateDiscoveryAdapter

Neue Tests

- CandidateDiscoveryAdapterContractTest

---

# 10. Akzeptanzkriterien

Das Work Package ist abgeschlossen wenn

- das Interface implementiert ist
- DummyAdapter den Contract erfüllt
- Contract Tests erfolgreich sind
- bestehende Tests weiterhin erfolgreich sind

---

# 11. Out of Scope

Nicht Bestandteil sind

- produktive Adapter
- Local Reconciliation Store
- xTree
- HTTP
- REST
- SPARQL
- CandidateDiscoveryRouter
- Runtime Integration

---

# 12. Auswirkungen auf Folgepakete

WP3-001-004 verwendet den CandidateDiscoveryAdapter Contract zur Delegation der Discovery.

WP3-002 implementiert den ersten produktiven Adapter für den Local Reconciliation Store.

WP3-003 implementiert den zweiten produktiven Adapter für die xTree JSON API.