fix p54

RETRIEX_PATCH_54_SINGLE_GENRE_CONFIG_SURFACE_README.md

@@ -0,0 +1,140 @@
+# RetrieX Patch p54 - Single-Genre Configuration Surface
+
+## Ziel
+
+Dieser Patch macht die Konfiguration **genre-faehig fuer eine Installation mit genau einem Genre**.
+
+Er baut **keine** Multi-Genre-, Multi-Tenant- oder SaaS-Umschaltung. Es gibt keinen Request-/Host-/API-Key-Resolver und keine Laufzeit-Auswahl zwischen mehreren Genres.
+
+Stattdessen fuehrt der Patch eine zentrale Konfigurationsflaeche ein, die alle fuer eine spaetere Umwidmung relevanten Parametergruppen sichtbar macht:
+
+- Produktrollen
+- Produktattribute und Constraints
+- Marken und kanonische Begriffe
+- Intent-/Routing-Signale
+- Follow-up-/Kontextanker
+- Shopquery-Runtime
+- Ergebnisidentitaet und Antwortregeln
+- Search Repair
+- Retrieval-/Language-Begriffe
+- Shopdaten-Mapping
+- Governance-/Regression-Guardrails
+
+Damit ist klar dokumentiert, welche Parameter fuer ein anderes Genre wie Fashion, Moebel, Ersatzteile oder Elektronik geprueft und angepasst werden muessen.
+
+## Bewusste Nicht-Ziele
+
+- Keine Multi-Domain-/Multi-Genre-Architektur
+- Keine Tenant-Logik
+- Keine Runtime-Umschaltung pro Request
+- Keine neuen fachlichen Defaults
+- Keine neuen Tokenlisten im PHP-Core
+- Keine Ranking-, Retrieval- oder Shopware-Kriterienaenderung
+- Keine LLM-Verhaltensaenderung
+- Keine Umbenennung bestehender Rollen wie `device`/`accessory`
+
+## Geaenderte Dateien
+
+```text
+config/retriex/genre.yaml
+config/services.yaml
+src/Config/GenreConfig.php
+src/Config/RetriexEffectiveConfigProvider.php
+src/Config/ConfigSourceAuditProvider.php
+```
+
+## Neue Datei `config/retriex/genre.yaml`
+
+Die neue Datei enthaelt:
+
+```yaml
+retriex.genre.config:
+  id: water_analysis
+  label: 'Water analysis / measurement devices'
+  mode: single_installation_single_genre
+  adaptation_surface:
+    ...
+```
+
+`adaptation_surface` ist ein nach Umwidmungsbereichen gruppiertes Inventar. Die dort genannten `paths` zeigen auf bestehende effektive oder rohe Config-Pfade.
+
+Wichtig: Die Eintraege verschieben noch keine fachlichen Werte physisch in `genre.yaml`. Der Patch ist absichtlich ein sicherer Oberflaechen-/Guardrail-Schritt. Bestehende Configs bleiben weiterhin die Quelle der Runtime-Werte.
+
+## Neue Klasse `GenreConfig`
+
+`src/Config/GenreConfig.php` kapselt die neue Genre-Konfiguration:
+
+- `getId()`
+- `getLabel()`
+- `getMode()`
+- `getDescription()`
+- `getAdaptationSurface()`
+- `toArray()`
+
+Die Klasse enthaelt keine PHP-only Fachlisten.
+
+## Effective Config / Validation
+
+`RetriexEffectiveConfigProvider` gibt nun zusaetzlich den Bereich `genre` aus und validiert:
+
+- `genre.id` ist gesetzt
+- `genre.mode` ist gesetzt
+- `genre.adaptation_surface` ist eine nicht-leere Map
+- jede Gruppe enthaelt eine nicht-leere `paths`-Liste
+- referenzierte Pfade werden gegen effektive Config und rohe Symfony-Parameterpfade geprueft
+
+Unbekannte Pfade erzeugen Warnungen, keine Runtime-Fehler. So werden veraltete Surface-Eintraege sichtbar, ohne die Installation hart zu blockieren.
+
+## Config Source Audit
+
+`ConfigSourceAuditProvider` kennt nun auch:
+
+```text
+GenreConfig => retriex.genre.config
+```
+
+Damit wird die neue Config-Klasse im Audit sauber einem YAML-Parameter zugeordnet.
+
+## Lokale Pruefungen
+
+Ausgefuehrt im entpackten Patch-Arbeitsstand:
+
+```bash
+php -l src/Config/GenreConfig.php
+php -l src/Config/RetriexEffectiveConfigProvider.php
+php -l src/Config/ConfigSourceAuditProvider.php
+```
+
+Ergebnis: alle PHP-Lints gruen.
+
+Zusaetzlich wurden alle YAML-Dateien unter `config/retriex/*.yaml` per Python/YAML-Parser geprueft.
+
+Ergebnis: YAML-Parsing gruen.
+
+Die `genre.adaptation_surface.paths` wurden statisch gegen die vorhandenen Config-Pfade geprueft.
+
+Ergebnis: keine fehlenden Pfadreferenzen.
+
+## Nicht lokal ausfuehrbar
+
+`bin/console` konnte lokal nicht ausgefuehrt werden, weil im ZIP kein `vendor/` enthalten ist:
+
+```text
+Dependencies are missing. Try running "composer install".
+```
+
+## Empfohlene Projektchecks nach dem Einspielen
+
+```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
+```
+
+## Naechster moeglicher Schritt
+
+Wenn p54 gruen ist, koennte ein spaeterer Patch einzelne besonders genreabhaengige Werte schrittweise physisch in diese Surface ueberfuehren oder von dort referenzieren.
+
+Das sollte separat und klein passieren, z. B. zuerst nur Produktrollen/Vocabulary-Views, ohne Runtime-Logik zu aendern.