fix p51

patch_history/RETRIEX_PATCH_51_DIRECT_PRODUCT_PRIMARY_IDENTITY_GUARD_README.md

@@ -0,0 +1,122 @@
+# RetrieX Patch p51 - Direct Product Primary Identity Guard
+
+## Ziel
+
+Behebt die verbleibende Regression bei direkten Shop-Produktlisten, bei der eine Anfrage nach Pufferlösungen Geräte/Koffer ausgeben konnte.
+
+Beispiel:
+
+```text
+welche neomeris puffer gibt es für Kalibrierung von pH-Messgeräten
+```
+
+Die Shopquery ist korrekt und soll unverändert bleiben:
+
+```text
+neomeris puffer kalibrierung ph messgeräten
+```
+
+Trotzdem wurden zuletzt nur pH-Messgeräte/Messkoffer ausgegeben, obwohl der Shop Pufferlösungen liefert.
+
+## Ursache
+
+Der direkte Produkt-Guard aus p45/p49/p50 hat Produktmatches über den gesamten Produkt-Corpus zugelassen:
+
+- Produktname
+- Beschreibung
+- Highlights
+- Custom Fields
+- URL
+
+Dadurch konnten Hauptgeräte oder Koffer als Treffer für `puffer` gelten, wenn ihre Beschreibung oder ihr Zubehörtext Pufferlösungen erwähnt. Für eine direkte Produktlistenfrage nach einer Produktart ist das zu breit: Ein Gerät, das Pufferlösungen im Zubehörtext erwähnt, ist selbst keine Pufferlösung.
+
+## Änderung
+
+Für direkte Produktlisten mit erkanntem Produkttyp gilt nun:
+
+1. Es werden zuerst nur Produkte behalten, deren primäre Identität den angefragten Produkttyp matcht.
+   - primäre Identität = Produktname + Produkt-URL
+2. Corpus-Matches über Beschreibung/Custom Fields werden nicht mehr als Ersatzliste ausgegeben, wenn der direkte Guard aktiv ist.
+3. Compound-Matches bleiben erhalten:
+   - `puffer` matcht `pufferlösung`
+   - `kalibrierpuffer` matcht zusammengesetzte Kalibrierpuffer-Begriffe
+4. Puffer-/Kalibrierbegriffe sind weiterhin YAML-konfigurierbare Zubehör-/Verbrauchsmaterialbegriffe.
+
+Damit werden Produkte wie diese akzeptiert:
+
+```text
+Neomeris pH-Pufferlösung pH 7.00
+Neomeris Redox-Pufferlösung 475 mV
+```
+
+und Produkte wie diese nicht mehr als Pufferliste ausgegeben:
+
+```text
+Professional pH/mV/Redox/Temperatur Handmessgerät ...
+Wassermeister Messkoffer
+```
+
+## Wichtig
+
+- Keine Änderung an der Shopquery.
+- Keine Änderung an Shopware-Kriterien.
+- Keine Neomeris-/pH-/Redox-Sonderlogik im PHP-Core.
+- Keine neuen fachlichen Tokenlisten im Core; die Begriffe bleiben in YAML.
+- Der Patch enthält die p50-Compound-/Puffer-Konfiguration vollständig, damit er auf dem aktuellen Arbeitsstand sicher anwendbar ist.
+- Der p48-Referential-Anchor-Fallback-Guard bleibt enthalten, damit referenzielle Shop-Preisfragen nicht regressieren.
+
+## Geänderte Dateien
+
+```text
+config/retriex/agent.yaml
+config/retriex/vocabulary.yaml
+src/Agent/AgentRunner.php
+src/Config/AgentRunnerConfig.php
+patch_history/RETRIEX_PATCH_51_DIRECT_PRODUCT_PRIMARY_IDENTITY_GUARD_README.md
+```
+
+## Erwartetes Verhalten
+
+```text
+welche neomeris puffer gibt es für Kalibrierung von pH-Messgeräten
+```
+
+soll Pufferlösungen ausgeben, sofern sie in den Shopdaten enthalten sind, z. B.:
+
+```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
+```
+
+Falls die Shopdaten tatsächlich keine primären Pufferprodukte enthalten, soll RetrieX keine Geräte/Koffer als Ersatzprodukte listen, sondern sauber "keine passenden Shopdaten" ausgeben.
+
+## 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
+```