MtoRagSystem/RETRIEX_PATCH_54_SINGLE_GENRE_CONFIG_SURFACE_README.md

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

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:

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:

GenreConfig => retriex.genre.config

Damit wird die neue Config-Klasse im Audit sauber einem YAML-Parameter zugeordnet.

Lokale Pruefungen

Ausgefuehrt im entpackten Patch-Arbeitsstand:

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:

Dependencies are missing. Try running "composer install".

Empfohlene Projektchecks nach dem Einspielen

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.