# RX-P5-001 – Discovery Execution & Evidence ## Architektur-Review für LA **Projekt:** Reconcilix **Phase:** 5 – Vorbereitung Discovery-Evaluation / Workbench / Profile Phase 6 **Status:** Entwurf zur Architekturprüfung **Rollen:** PL / ED → Review durch LA **Datum:** 2026-09-06 --- ## 1. Anlass Die Erstumsetzung der Discovery Profiles ist abgeschlossen und mit einer vollständigen Datenlieferung von 150 Records erfolgreich durchlaufen worden. Der aktuelle Profilpfad kann u. a. folgende fachliche Sequenz ausführen: ```text EXACT_STRING ALWAYS ↓ bei 0 Candidates MAPPED_VOCABULARY ON_ZERO_RESULTS ``` Für die nächste Ausbaustufe soll Reconcilix so vorbereitet werden, dass in **Phase 6 Discovery Profiles systematisch verändert, verglichen und evaluiert** werden können. Gleichzeitig soll die vorhandene Workbench perspektivisch Discovery-Evidenz gemeinsam mit intellektuellen Mapping-/Matching-Entscheidungen darstellen können. Phase 5 soll deshalb **noch keine intelligente Matching Engine** einführen. Schwerpunkt ist die persistente und nachvollziehbare Dokumentation der tatsächlichen Discovery-Ausführung. --- ## 2. Fachliche Leitplanken ### 2.1 Discovery und Matching bleiben getrennt ```text DISCOVERY → ermittelt CandidateItems und Discovery-Evidenz MATCHING / MAPPING → bewertet bzw. entscheidet über Candidates ``` Reconcilix liefert zunächst Empfehlungen. Insbesondere bei Sachbegriffen ist eine intellektuelle Bewertung bzw. Zuordnung durch Domainexpert:innen erforderlich. Für andere Entitätstypen, beispielsweise Personen, kann später auch eine automatische Matchentscheidung zulässig sein. Phase 5 soll diese spätere Differenzierung ermöglichen, aber noch keine automatische Matching-Strategie implementieren. ### 2.2 Plan und tatsächliche Ausführung müssen unterscheidbar bleiben Der `ReconciliationRun` enthält bereits einen unveränderlichen Konfigurations-Snapshot des geplanten Discovery-Verfahrens. Beispiel: ```text ReconciliationRun.configuration └── discovery_strategy └── steps ├── [0] EXACT_STRING / ALWAYS └── [1] MAPPED_VOCABULARY / ON_ZERO_RESULTS ``` Dieser Teil beantwortet: > Was sollte in diesem Run ausgeführt werden? Für Phase 6 fehlt dagegen eine persistente Antwort auf: > Was wurde für dieses konkrete RunItem tatsächlich ausgeführt und mit welchem Ergebnis? --- ## 3. Relevanter Ist-Zustand Vereinfacht besteht derzeit folgende Struktur: ```text SourceDelivery ↓ ReconciliationRun ↓ ReconciliationRunItem ↓ InterpretationGraph ↓ InterpretationNode ↓ ReconciliationResult ↓ CandidateItem ``` Für externe Discovery-Zugriffe existieren zusätzlich bereits: ```text ReconciliationRunItem ↓ DiscoveryResponseCapture ↓ DiscoveryResponseSnapshot ``` Die Snapshot-Infrastruktur dient der technischen Evidenz eines Provider-Zugriffs und soll erhalten bleiben. Der `DiscoveryProfileExecutor` kennt während der Laufzeit bereits den konkreten Step und dessen Ergebnis. Vereinfacht: ```text for each profile step evaluate condition if condition false skip execute discovery collect candidates ``` Nach Abschluss der Discovery wird dieses Step-Wissen derzeit jedoch nicht als eigenständige fachliche Ausführungsevidenz persistiert. Insbesondere ist später nicht zuverlässig feststellbar: - welcher Profile-Step tatsächlich ausgeführt wurde, - welcher Step aufgrund seiner Condition übersprungen wurde, - wie viele Candidates ein bestimmter Step erzeugte, - aus welchem Step ein konkreter Candidate stammt, - welcher externe Provider-Zugriff zu welchem Step gehörte. --- ## 4. Ziel von Phase 5 Phase 5 soll eine minimale persistente Execution-/Evidence-Schicht zwischen Discovery Plan und Discovery Result einführen. Zielbild: ```text ReconciliationRun │ │ PLAN ▼ configuration.discovery_strategy.steps[] │ ▼ ReconciliationRunItem │ │ EXECUTION ▼ DiscoveryStepExecution │ ├──────────────► DiscoveryResponseCapture │ │ │ ▼ │ DiscoveryResponseSnapshot │ └──────────────► CandidateDiscoveryEvidence │ ▼ CandidateItem ``` Damit sollen Phase 6 und die Workbench später nicht nur das Endergebnis, sondern den tatsächlichen Discovery-Pfad auswerten können. --- ## 5. ED-Vorschlag: `DiscoveryStepExecution` ### 5.1 Aufgabe `DiscoveryStepExecution` beschreibt die tatsächliche Ausführung eines geplanten Discovery-Steps für genau ein `ReconciliationRunItem`. Sie ersetzt **nicht** den Discovery-Step im Run-Konfigurations-Snapshot. Vorgeschlagene Minimalstruktur: ```text DiscoveryStepExecution ├── id ├── reconciliation_run_item_id ├── sequence ├── status ├── condition_result ├── candidate_count ├── started_at └── finished_at ``` Mögliche Statuswerte für v0.1: ```text EXECUTED SKIPPED FAILED ``` Beispiel bei `ON_ZERO_RESULTS`: ```text Step 0 sequence = 0 status = EXECUTED candidate_count = 1 Step 1 sequence = 1 status = SKIPPED condition_result = false ``` Bei fehlendem Exact-Treffer: ```text Step 0 sequence = 0 status = EXECUTED candidate_count = 0 Step 1 sequence = 1 status = EXECUTED condition_result = true candidate_count = 1 ``` ### 5.2 Bewusste Nicht-Duplizierung ED schlägt zunächst vor, folgende Planinformationen **nicht erneut** in `DiscoveryStepExecution` zu speichern: ```text family method resource options condition ``` Sie liegen bereits im unveränderlichen: ```text ReconciliationRun.configuration.discovery_strategy.steps[sequence] ``` Arbeitshypothese: ```text Run.configuration = PLAN DiscoveryStepExecution = EXECUTION ``` Zu prüfen ist insbesondere, ob `sequence` als Verbindung zwischen beiden Ebenen ausreichend stabil ist. --- ## 6. ED-Vorschlag: Candidate Discovery Evidence Ein `CandidateItem` kann perspektivisch über mehr als einen Discovery-Step gefunden werden. Beispiel: ```text EXACT_STRING → Candidate X RIGHT_TRUNCATED → Candidate X ``` Der Candidate sollte fachlich nicht doppelt gespeichert werden. Gleichzeitig darf die zweite Discovery-Evidenz nicht verloren gehen. Daher schlägt ED keine einfache 1:n-Relation ```text CandidateItem → DiscoveryStepExecution ``` vor, sondern eine n:m-Zuordnung über eine Evidence-Entität bzw. Relation: ```text CandidateDiscoveryEvidence ├── candidate_item_id ├── discovery_step_execution_id ├── step_rank └── step_score ``` Damit könnte gelten: ```text Candidate X ├── gefunden durch Step 0 / EXACT_STRING └── gefunden durch Step 1 / RIGHT_TRUNCATED ``` `step_score` und `step_rank` wären methoden-/providerbezogene Discovery-Werte und ausdrücklich keine Matching-Confidence. --- ## 7. ED-Vorschlag: Discovery Capture an Step Execution anbinden Die vorhandene Raw-Response-Infrastruktur soll nicht ersetzt werden. Vorgeschlagen wird lediglich eine präzisere Zuordnung: ```text DiscoveryStepExecution 1 │ n DiscoveryResponseCapture │ ▼ DiscoveryResponseSnapshot ``` Damit wäre bei einem Profile-Run mit mehreren externen Discovery-Schritten eindeutig erkennbar, welcher technische Provider-Zugriff zu welchem fachlichen Step gehört. Die bestehende Zuordnung zum `ReconciliationRunItem` kann je nach Integritäts-/Migrationsbedarf erhalten bleiben oder abgeleitet werden. --- ## 8. Erwarteter Nutzen für Phase 6 Phase 6 soll Discovery Profiles gezielt verändern und vergleichen können. Beispiel: ```text Profil v0.1 EXACT_STRING → MAPPED_VOCABULARY Profil v0.2 EXACT_STRING → RIGHT_TRUNCATED → MAPPED_VOCABULARY ``` Mit der vorgeschlagenen Execution-Schicht könnte anschließend pro RunItem ausgewertet werden: ```text welcher Step wurde ausgeführt? welcher Step wurde übersprungen? wie viele Candidates entstanden pro Step? welche Candidates entstanden über welchen Step? welcher Provider-/Resource-Zugriff lag zugrunde? ``` Damit wird nicht nur die Trefferzahl eines Profils vergleichbar, sondern dessen tatsächliches Verhalten. --- ## 9. Erwarteter Nutzen für die Workbench Die Workbench soll perspektivisch einen fachlich nachvollziehbaren Pfad darstellen können: ```text SourceValue ↓ Discovery Profile ↓ Discovery Step Execution ↓ Discovery Evidence ↓ Candidate ↓ intellektuelle / automatische Entscheidung ``` Beispiel: ```text SourceValue: Annakapelle 1. EXACT_STRING EXECUTED 0 Candidates 2. MAPPED_VOCABULARY EXECUTED Resource: additional_matching_dehio 1 Candidate → Kapelle MCT 49739000 Discovery score: 80 Expert:innenentscheidung: noch offen ``` Mapping-/Matching-Entscheidungen sind dabei bewusst **nicht Teil von `DiscoveryStepExecution`**. --- ## 10. Nicht-Ziele von Phase 5 Phase 5 soll ausdrücklich **nicht**: - eine automatische Matching Engine entwickeln, - neue fachliche Matching-Strategien erfinden, - Discovery und Matching zusammenführen, - einen generischen Rule Engine Layer einführen, - die vorhandene Snapshot-Infrastruktur ersetzen, - den gesamten Run-/Result-Domainbereich redesignen, - Dehio-spezifische Sonderlogik in Rx einbauen. Der Schnitt soll so klein wie möglich bleiben und primär Phase 6 sowie die Workbench vorbereiten. --- ## 11. Fragen an LA ED bittet um einen fokussierten Architektur-Review des beschriebenen Schnitts. ### LA-01 – Plan vs. Execution Ist die Trennung ```text ReconciliationRun.configuration = Discovery Plan DiscoveryStepExecution = tatsächliche Ausführung je RunItem ``` architektonisch sauber, oder sollte zwischen RunItem und Step Execution noch eine eigene übergeordnete `DiscoveryExecution`-Entität existieren? ### LA-02 – Step-Identität Reicht `sequence` als Referenz auf ```text configuration.discovery_strategy.steps[sequence] ``` aus? Oder sollte jeder geplante Discovery-Step bereits eine stabile `step_id` besitzen, die sowohl im Run-Snapshot als auch in `DiscoveryStepExecution` verwendet wird? ### LA-03 – Candidate-Provenienz Ist eine n:m-Relation ```text CandidateItem ↔ DiscoveryStepExecution ``` über `CandidateDiscoveryEvidence` angemessen? Oder sollte Candidate-Provenienz anders modelliert werden? Besonders relevant ist der Fall, dass derselbe Candidate in einem Profil über mehrere Discovery-Steps gefunden wird. ### LA-04 – Score/Rank auf Evidence-Ebene Sollten methodenspezifische `score`- und `rank`-Werte zusätzlich auf `CandidateDiscoveryEvidence` liegen, wenn derselbe Candidate über mehrere Steps unterschiedliche Werte erhalten kann? Oder reicht weiterhin ein kanonischer Wert am `CandidateItem`? ### LA-05 – Capture-Zuordnung Soll `DiscoveryResponseCapture` direkt mit `DiscoveryStepExecution` verbunden werden? Falls ja: Soll die bestehende Relation zu `ReconciliationRunItem` redundant erhalten bleiben oder künftig über die Step Execution ableitbar sein? ### LA-06 – Status und Condition Sind ```text EXECUTED SKIPPED FAILED ``` für v0.1 als Execution-Status ausreichend? Ist ein separates `condition_result` sinnvoll, oder lässt sich dies ohne Informationsverlust aus Status + Plan ableiten? ### LA-07 – Phase-6-Fähigkeit Ist das Modell ausreichend, um in Phase 6 unterschiedliche Discovery-Profile bzw. Profile-Versionen auf RunItem-/Step-/Candidate-Ebene belastbar miteinander zu vergleichen? Welche minimale zusätzliche Information wäre hierfür gegebenenfalls bereits jetzt erforderlich? ### LA-08 – Workbench-Fähigkeit Ist die vorgeschlagene Evidence-Kette ausreichend, um später in der Workbench ```text Discovery-Ausführung → Candidate-Evidenz → Mapping-/Matching-Entscheidung ``` nachvollziehbar darzustellen, ohne Discovery und Matching semantisch zu vermischen? ### LA-09 – KISS / Doppelhaltung Wo sieht LA im vorgeschlagenen Modell unnötige Doppelhaltung oder Overengineering? Insbesondere bitten PL/ED um Prüfung, ob für die erste Phase weniger Entitäten/Felder ausreichen, ohne die für Phase 6 benötigte Provenienz zu verlieren. --- ## 12. Gewünschtes Review-Ergebnis PL/ED wünschen keine allgemeine Neubewertung der Reconcilix-Architektur, sondern eine konkrete Empfehlung für den minimalen Phase-5-Schnitt: ```text ACCEPT oder ACCEPT WITH CHANGES oder REVISE ``` mit besonderem Fokus auf: 1. Step-Identität, 2. Candidate-Provenienz, 3. Capture-Zuordnung, 4. Vergleichbarkeit von Discovery Profiles in Phase 6, 5. spätere Workbench-Integration, 6. KISS. Nach dem LA-Review soll ED daraus die technische Detaildefinition und anschließend den ersten Phase-5-Patch ableiten.