fix p52

patch_history/RETRIEX_PATCH_52_DIRECT_PRODUCT_PRIMARY_IDENTITY_REPAIR_README.md

@@ -0,0 +1,114 @@
+# RetrieX Patch p52 - Direct Product Primary Identity Repair
+
+## Ziel
+
+Korrigiert die p51-Regression bei direkten Shop-Produktlisten, bei der echte Store-API-Treffer intern auf `Shop-Treffer: 0` fallen konnten.
+
+Betroffener Fall:
+
+```text
+welche neomeris puffer gibt es für Kalibrierung von pH-Messgeräten
+```
+
+Die angezeigte Shopquery bleibt korrekt und soll nicht wieder mit Geräte-/Darstellungslogik vermischt werden:
+
+```text
+neomeris puffer kalibrierung ph messgeräten
+```
+
+Wenn die Store API mit dieser Suche Treffer liefert, darf RetrieX diese nicht intern durch den direkten Produkt-Guard verlieren.
+
+## Ursache
+
+p51 hat den Direct-Product-Guard bewusst verschärft: Bei direkten Produktlisten sollten nur noch Produkte ausgegeben werden, deren primäre Identität, also Produktname/URL, zur angefragten Produktart passt. Das verhindert Geräte/Koffer als Ersatztreffer für Verbrauchsmaterialien.
+
+Der Guard war aber zu hart, wenn die vorliegende Shop-Trefferliste bereits durch Shopware-Ranking/Repair/Guardrails in Richtung Geräte verschoben war. Dann konnte der Guard alle Treffer entfernen und der Status fiel auf:
+
+```text
+Shop-Treffer: 0
+```
+
+obwohl die Store API für die Suchquery echte Produktkandidaten liefert.
+
+## Änderung
+
+p52 ergänzt einen kleinen, defensiven Retry nur für diesen Fall:
+
+1. Die normale Shopquery bleibt unverändert.
+2. Der p51-Primary-Identity-Guard läuft weiterhin.
+3. Nur wenn der Guard aus einer nicht-leeren Shopliste **alles** entfernt, wird eine bereinigte Repair-Query gebaut.
+4. Diese Repair-Query entfernt nur konfigurierte Zielgeräte-Wörter wie `Messgerät`, `Gerät`, `Koffer` und behält Produktart/Brand/Kontext wie `neomeris`, `puffer`, `ph`.
+5. Die Repair-Ergebnisse laufen erneut durch denselben Primary-Identity-Guard.
+6. Wenn danach weiterhin nichts passt, bleibt die saubere Keine-Treffer-Antwort erhalten; es werden keine Geräte als Ersatz ausgegeben.
+
+Beispiel Repair-Query:
+
+```text
+neomeris puffer kalibrierung ph
+```
+
+statt die Anfrage als Geräte-/Koffer-Liste zu behandeln.
+
+## Wichtig
+
+- Keine Änderung an der angezeigten primären Shopquery.
+- Keine Änderung an Shopware-Kriterien.
+- Kein Neomeris-/pH-/Redox-Sonderfall im PHP-Core.
+- Die entfernten Zielgeräte-Wörter sind YAML-konfiguriert unter `shop_prompt.direct_result_guard.primary_identity_repair.stop_terms`.
+- p51 bleibt erhalten: Geräte/Koffer werden nicht als Pufferliste ausgegeben.
+- p48, p45/p46 und der Artikelnummer-Fix p47 bleiben unverändert.
+
+## Geänderte Dateien
+
+```text
+config/retriex/agent.yaml
+src/Agent/AgentRunner.php
+src/Config/AgentRunnerConfig.php
+patch_history/RETRIEX_PATCH_52_DIRECT_PRODUCT_PRIMARY_IDENTITY_REPAIR_README.md
+```
+
+## Erwartetes Verhalten
+
+```text
+welche neomeris puffer gibt es für Kalibrierung von pH-Messgeräten
+```
+
+soll wieder echte Pufferprodukte ausgeben, sofern sie von der Store API geliefert werden, zum Beispiel:
+
+```text
+Neomeris pH-Pufferlösung pH 4.01
+Neomeris pH-Pufferlösung pH 7.00
+Neomeris pH-Pufferlösung pH 9.21
+Neomeris pH-Pufferlösung pH 10.01
+Neomeris Redox-Pufferlösung 200 mV / 475 mV / 650 mV
+```
+
+Es sollen nicht mehr nur Geräte/Koffer erscheinen, und es soll nicht fälschlich `Shop-Treffer: 0` entstehen, wenn die Store API passende Pufferprodukte liefert.
+
+## Lokale Checks
+
+Ausgeführt:
+
+```bash
+php -l src/Agent/AgentRunner.php
+php -l src/Config/AgentRunnerConfig.php
+python3 - <<'PY'
+import yaml
+from pathlib import Path
+for f in ['config/retriex/agent.yaml', 'config/retriex/vocabulary.yaml']:
+    yaml.safe_load(Path(f).read_text())
+print('YAML ok')
+PY
+```
+
+`bin/console` wurde lokal nicht ausgeführt, weil `vendor/` im ZIP nicht enthalten ist.
+
+## Nach dem Einspielen prüfen
+
+```bash
+bin/console cache:clear
+bin/console mto:agent:config:validate
+bin/console mto:agent:regression:test
+bin/console mto:agent:config:audit-source --details
+bin/console mto:agent:config:audit-patterns --details
+```