# RX-CLN-001(B) – Raw Discovery Response Snapshot

**Stand:** 2026-09-01  
**Status:** Implementiert im ED-Umzugsstand

## Entscheidung

`CandidateItem` bleibt die normalisierte Reconcilix-Sicht. Der vollständige externe Provider-Response wird separat und unverändert archiviert.

Persistenz ist zweistufig:

1. `discovery_response_snapshot`
   - deduplizierter technischer Snapshot
   - `candidate_provider_uri`
   - SHA-256 des Providers als technischer Indexschlüssel
   - SHA-256 über die unveränderten, unkomprimierten Response-Bytes
   - `media_type`
   - `content_encoding = gzip`
   - gzip-komprimierter Payload als `LONGBLOB`

2. `discovery_response_capture`
   - konkrete Verwendung eines Snapshots
   - `discovery_access_id` zur Korrelation mit dem bestehenden Discovery-Audit
   - optionale Relation auf `reconciliation_run_item`
   - Relation auf den deduplizierten Snapshot

Die Trennung ist erforderlich, weil derselbe Snapshot in mehreren Discovery-Vorgängen vorkommen kann und ein RunItem zukünftig mehrere Provider verwenden kann.

## Capture-Punkt

Der Raw Body wird in den bestehenden Provider-Clients unmittelbar nach `curl_exec()` bzw. beim Qdrant-Testtransport übernommen, bevor `json_decode()` bzw. fachliches Mapping erfolgt.

Erfasst werden derzeit:

- xTree JSON API
- lobid GND Reconciliation API
- Vector/Qdrant Reconciliation API

Der Local Reconciliation Store erhält bewusst keinen Raw Discovery Response Snapshot, weil dort kein externer Provider-Response existiert. Eine Serialisierung des lokalen Candidate-Modells wäre ein Reconcilix-eigenes Proxyformat und widerspräche der Entscheidung.

## RunItem-Relation

`ReconciliationCommand` besitzt optional `reconciliationRunItemId`.

Der Discovery Testbench übernimmt nach `definePopulation()` die persistierten RunItem-IDs und führt sie beim Provider-Aufruf mit. Damit bleibt der Response auch bei null Candidates eindeutig am tatsächlich bearbeiteten RunItem verankert. Die Relation ist nullable, damit bestehende nicht-runbasierte Aufrufpfade kompatibel bleiben.

## Deduplizierung

Deduplizierung erfolgt über:

- SHA-256 von `candidate_provider_uri`
- SHA-256 der unveränderten Raw Response Bytes

Der Provider-Hash dient nur als indexierbarer technischer Schlüssel; die originale `candidate_provider_uri` bleibt vollständig gespeichert.

## Tests

- PHP-Lint über `src`, `public`, `tools`, `tests`
- bestehende Application-/Runtime-/Provider-/Adapter-Regressionstests
- Migrationstest auf 0009 erweitert
- neuer Test `RawDiscoveryResponseCaptureTest.php`: bestätigt byteidentische Übergabe inklusive Whitespace/Zeilenumbrüchen sowie die RunItem-Relation

## Betrieb

Vor Nutzung auf einer bestehenden Installation Migration `0009_discovery_response_snapshot.sql` ausführen.