# WP3-001-004 – Candidate Discovery Router

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

## Änderungsstand

### Version 0.2

Einarbeitung von LA Review 001.

**Änderungen**

- Router implementiert `CandidateDiscoveryGateway`.
- `CandidateDiscoveryAdapterRegistry` ergänzt.
- Rückgabetyp auf `DiscoveredCandidate[]` umgestellt.
- Validierung der Route-Kardinalität ergänzt.
- Verantwortlichkeiten präzisiert.

---

## Referenzen

- WP3-001 – Discovery Framework Foundation
- WP3-001-001 – Discovery Route Model
- WP3-001-002 – Discovery Configuration Registry
- WP3-001-003 – Candidate Discovery Adapter Contract and Registry
- PRE_WP3-001 – Architekturübersicht Discovery Framework
- DM001 – Domain Model

---

# 1. Ziel

Dieses Work Package führt den `CandidateDiscoveryRouter` als zentralen Einstiegspunkt des Discovery Frameworks ein.

Der Router implementiert den bestehenden `CandidateDiscoveryGateway`.

Er verbindet

- DiscoveryConfigurationRegistry
- CandidateDiscoveryAdapterRegistry
- DiscoveryRoute
- CandidateDiscoveryAdapter

zu einem einheitlichen Discovery-Ablauf.

Der Router enthält keine technische Discovery-Implementierung.

---

# 2. Scope

Dieses Work Package umfasst ausschließlich

- Einführung der Klasse `CandidateDiscoveryRouter`
- Implementierung des `CandidateDiscoveryGateway`
- Verwendung der DiscoveryConfigurationRegistry
- Verwendung der CandidateDiscoveryAdapterRegistry
- Validierung der Route-Kardinalität
- Delegation an einen CandidateDiscoveryAdapter
- Unit Tests

Nicht Bestandteil sind

- Runtime Integration
- produktive Adapter
- HTTP
- REST
- SPARQL
- Candidate Discovery Implementierungen

---

# 3. Architekturbezug

Gemäß PRE_WP3 bildet der CandidateDiscoveryRouter den zentralen Einstiegspunkt des Discovery Frameworks.

Der Router

- implementiert den CandidateDiscoveryGateway,
- verwendet die DiscoveryConfigurationRegistry,
- verwendet die CandidateDiscoveryAdapterRegistry,
- führt selbst keine Candidate Discovery durch.

---

# 4. Klassenübersicht

| Klasse | Typ | Status | Verantwortung |
|---------|-----|--------|----------------|
| CandidateDiscoveryRouter | Class | Neu | Zentraler Einstiegspunkt des Discovery Frameworks |
| DiscoveryConfigurationRegistry | Class | Bestehend | Liefert passende Discovery Routes |
| CandidateDiscoveryAdapterRegistry | Class | Bestehend | Liefert Candidate Discovery Adapter |
| CandidateDiscoveryAdapter | Interface | Bestehend | Führt technische Discovery aus |

---

# 5. Verantwortlichkeiten

Der CandidateDiscoveryRouter ist verantwortlich für

- Entgegennahme einer Discovery-Anfrage
- Ermittlung aller passenden Discovery Routes
- Validierung der Route-Kardinalität
- Auflösung des referenzierten CandidateDiscoveryAdapter
- Delegation der Discovery
- Rückgabe von `DiscoveredCandidate[]`

Der CandidateDiscoveryRouter ist nicht verantwortlich für

- Verwaltung der Discovery Configuration
- technische Discovery
- Adapterverwaltung
- HTTP-Kommunikation
- Match Decisions
- Persistenz

---

# 6. Ablauf

Der Router verarbeitet eine Discovery-Anfrage in folgenden Schritten:

1. Discovery-Anfrage entgegennehmen.
2. Passende Discovery Routes über die DiscoveryConfigurationRegistry ermitteln.
3. Route-Kardinalität prüfen.

```
0 Routes
→ DiscoveryConfigurationException

1 Route
→ Route verwenden

>1 Routes
→ AmbiguousDiscoveryRouteException
```

4. CandidateDiscoveryAdapter über die CandidateDiscoveryAdapterRegistry auflösen.
5. Discovery delegieren.
6. `DiscoveredCandidate[]` zurückgeben.

---

# 7. Laufzeitmodell

```text
CandidateDiscoveryGateway
        │
        ▼
CandidateDiscoveryRouter
        │
        ├── DiscoveryConfigurationRegistry
        │
        ├── CandidateDiscoveryAdapterRegistry
        │
        ▼
CandidateDiscoveryAdapter
        │
        ▼
DiscoveredCandidate[]
```

---

# 8. Invarianten

Der Router

- implementiert den CandidateDiscoveryGateway,
- kennt keine technischen Protokolle,
- erzeugt keine Candidate Items,
- kennt keine konkreten Adapterimplementierungen,
- verändert Discovery Routes nicht,
- delegiert jede technische Discovery an einen CandidateDiscoveryAdapter.

---

# 9. Implementierungsreihenfolge

1. CandidateDiscoveryRouter erstellen.
2. CandidateDiscoveryGateway implementieren.
3. DiscoveryConfigurationRegistry integrieren.
4. CandidateDiscoveryAdapterRegistry integrieren.
5. Validierung der Route-Kardinalität implementieren.
6. Delegation an CandidateDiscoveryAdapter implementieren.
7. Unit Tests ergänzen.

---

# 10. Deliverables

## Neue Klasse

- CandidateDiscoveryRouter

## Neue Tests

- CandidateDiscoveryRouterTest

---

# 11. Akzeptanzkriterien

Das Work Package ist abgeschlossen, wenn

- CandidateDiscoveryRouter den CandidateDiscoveryGateway implementiert,
- DiscoveryConfigurationRegistry verwendet wird,
- CandidateDiscoveryAdapterRegistry verwendet wird,
- Route-Kardinalität korrekt validiert wird,
- CandidateDiscoveryAdapter korrekt delegiert wird,
- `DiscoveredCandidate[]` unverändert zurückgegeben werden,
- bestehende Tests weiterhin erfolgreich sind,
- neue Unit Tests erfolgreich sind.

---

# 12. Out of Scope

Nicht Bestandteil sind

- Runtime Integration
- Composition Root
- produktive Adapter
- HTTP
- REST
- SPARQL
- parallele Discovery
- Priorisierung
- Hybrid Discovery
- Ranking
- Result Fusion

---

# 13. Auswirkungen auf Folgepakete

## WP3-001-005 – Runtime Integration

Bindet den CandidateDiscoveryRouter als Implementierung des CandidateDiscoveryGateway in den produktiven Runtime-Pfad ein.

## WP3-002

Implementiert den ersten produktiven CandidateDiscoveryAdapter für den Local Reconciliation Store.

## WP3-003

Implementiert den ersten produktiven CandidateDiscoveryAdapter für die xTree JSON API.