Produktadressen und Site-Vorlagen manuell umstellen

Diese Betriebsanleitung richtet sich an Administratoren und Site-Entwickler, die einen bestehenden Shop auf vollständige ProductRoute-Pfade umstellen. Sie überführen Produktadressen, Snippet-Vorlagen und Produktshells gemeinsam. Nach der Umstellung liefert jede Site ihre gepflegten Produktpfade aus, ohne Slugs oder Präfixe zur Laufzeit zusammenzusetzen.

Die Anleitung ändert weder Produktveröffentlichungen noch Preise, Warenkorb oder Checkout. Führen Sie die Arbeiten zuerst in einer Vorschau- oder Testumgebung aus und planen Sie Redirects für Adressen, die sich tatsächlich ändern. Workspace ergänzt oder korrigiert bestehende Routen nicht automatisch. Es gibt weder einen impliziten Backfill noch einen geratenen Site-Präfix.

Voraussetzungen

• Sie kennen alle Sites, Sprachen und derzeit öffentlich verlinkten Produktadressen.
• Sie können ProductRoutes, Snippet-Vorlagen und Site-Dateien bearbeiten.
• Für jede Site gibt es eine eindeutige Produktshell je Sprache und Jurisdiction.
• Sie haben einen Rückfallplan für den bisher veröffentlichten Site-Release.

1. Bestehende Adressen inventarisieren

Erfassen Sie je Produktadresse mindestens Site, Sprache, Zielprodukt, bisherigen öffentlichen Pfad und gewünschte Hauptadresse. Leiten Sie den neuen Wert nicht aus einem gespeicherten Slug ab. Berücksichtigen Sie Groß- und Kleinschreibung, Prozentkodierung und einen bewusst gesetzten abschließenden Slash. Ein Site- oder Shop-Präfix gehört nur dann zum Pfad, wenn Sie ihn ausdrücklich als Teil der öffentlichen Adresse eintragen.

ProductRoute.path ist ein origin-relativer Pfad. Ein gültiger Wert beginnt mit / und enthält weder Domain noch Query oder Fragment. Beispiel:

/de/produkte/rucksack/

Prüfen Sie außerdem Produktkarten, Navigation, Sitemap, Merchant-Feeds, Chat-Links und externe Kampagnen. So erkennen Sie, welche alten Adressen nach dem Umschnitt einen Redirect benötigen.

2. ProductRoutes registrieren

Öffnen Sie die Routenpflege der Produktvariante oder des Katalogprodukts. Wählen Sie die Site und die Sprache und tragen Sie den vollständigen Pfad ein. Der Vertriebskanal folgt aus der Site und ist keine zweite Eingabequelle.

Unvollständige Altzeilen lassen sich einmalig registrieren. Nach der Registrierung sind Site, Sprache, Pfad und Produktziel unveränderlich. Wenn ein Produkt eine neue Adresse erhalten soll, legen Sie eine neue ProductRoute an, wählen sie ausdrücklich als Hauptadresse und pflegen den benötigten Redirect. Archivieren oder Löschen gibt einen registrierten Pfad nicht für ein anderes Produkt frei.

Wählen Sie pro Produkt, Site und Sprache genau eine Hauptadresse. Workspace bestimmt keine Ersatzadresse nach Alter oder Sortierung. Eine fehlende oder inaktive Hauptadresse bleibt deshalb sichtbar als Konfigurationslücke.

3. Snippet-Vorlagen aktualisieren

Entfernen Sie aus Produkt-Snippet-Vorlagen alle URL-Konstruktionen aus product_url, route_slug, route_href, SKU, Locale oder einem Produktshell-Präfix. Markieren Sie Links auf das dargestellte Produkt stattdessen mit dem v1-Anker:

<a class="product-card" data-nucleus-product-link="v1:self">
  {{ .name }}
</a>

Setzen Sie kein geratenes href. Workspace trägt beim Ausliefern den vollständigen Pfad ein. Fehlt eine auslieferbare Route, bleibt der Inhalt stehen, aber der Link entfällt. Weitere typisierte Anker und die Grenzen des Materialisierers beschreibt Snippet-Vorlagen entwickeln.

Starten Sie danach einen vollständigen Snippet-Rebuild für die betroffenen Sprachen und Vertriebskanäle. Ein reiner Site-Build erzeugt keine neuen Produkt-Snippet-Artefakte.

4. Produktshells aktualisieren

Behalten Sie dynamicRoute.kind: productDetail, entfernen Sie jedoch das Feld dynamicRoute.prefix und alle Annahmen, nach denen die Shell mit einem Slug zur öffentlichen Adresse verbindet. Der Site-Build weist das entfernte Feld als Fehler zurück. Die Shell bestimmt Layout, Navigation, Zugriff und erforderliche Snippet-Bereiche. Die ProductRoute bestimmt den vollständigen Besucherpfad. Auch eine canonicalPath-Einstellung der Shell verändert diesen Pfad nicht. Verwenden Sie für abweichende Besucheradressen einen ausdrücklich gepflegten Redirect.

Prüfen Sie eigene JavaScript-Dateien ebenfalls. Produktkarten und Variantenauswahl müssen die vom Server gelieferten Pfade verwenden. Sie dürfen keine Ersatzadresse aus SKU, Attributen oder Sprache bauen. Headless-Frontends lesen dazu das optionale route-Objekt der öffentlichen Produktantwort mit id, path und canonicalPath. Statische Snippets verwenden stattdessen die v1-Anker; beide Verträge dürfen nicht miteinander vermischt werden.

5. Bauen, prüfen und veröffentlichen

1. Prüfen Sie im Bearbeitungsstand jede neue Produktadresse mit der Routendiagnose.
2. Bauen Sie einen neuen Site-Release und prüfen Sie dieselben Pfade gegen dessen Release-ID.
3. Rufen Sie den öffentlichen Resolver mit dem vollständigen Pfad als genau einen Query-Wert auf:

   GET /api/v1/public/v1/catalog/products/by-route?path=%2Fde%2Fprodukte%2Frucksack%2F

1. Öffnen Sie eine servergerenderte Produktkarte und folgen Sie ihrem tatsächlichen Link. Prüfen Sie Produktdetail, Variantenwechsel, Warenkorb und Checkout in allen betroffenen Sprachen.
2. Kontrollieren Sie Sitemap, strukturierte Produktdaten, Merchant-Feed und Chat-Produktlinks. Sie müssen dieselbe auslieferbare Hauptadresse nutzen.
3. Pflegen Sie dauerhaft benötigte Weiterleitungen in der Redirect-Verwaltung der Site. Eine alte Route darf nicht als versteckter Ersatzpfad im Template oder in JavaScript erhalten bleiben.
4. Veröffentlichen Sie erst danach den geprüften Site-Release und aktivieren die vorbereiteten Redirects.

Eine Redirect-Quelle darf keinen aktiven oder geplanten Produktpfad belegen. Archivieren Sie die alte ProductRoute, bevor Sie genau diesen Pfad als Redirect-Quelle verwenden. Das Redirect-Ziel darf die neue Produktadresse sein. Belegt eine statische Seite, eine öffentliche Datei oder ein reservierter Systempfad dieselbe Adresse, scheitern Registrierung beziehungsweise Site-Veröffentlichung mit einem Kollisionsfehler.

Die Umstellung ist abgeschlossen, wenn keine aktive Vorlage mehr alte Slug-/Präfixfelder verwendet, alle öffentlichen Verbraucher denselben vollständigen Pfad liefern und ein natürlicher Klick von der Produktkarte zur Detailseite erfolgreich ist.

Scheitert die Abnahme vor der Veröffentlichung, bleibt der bisherige Release aktiv und der neue Stand wird korrigiert. Nach der Veröffentlichung ist ein Rückfall nur auf einen Release zulässig, dessen ProductRoutes, Snippets, Produktshell und Redirects weiterhin zusammenpassen. Ein Rückfall einzelner Vorlagen oder Routen würde wieder gemischte Adressverträge erzeugen und ist deshalb keine sichere Rollback-Grenze.

Häufige Fehler

Nächste Schritte

• Prüfen Sie die technische Snippet-Syntax unter Snippet-Vorlagen entwickeln.
• Prüfen Sie Produktshell und Routendiagnose unter Sites und CMS.
• Veröffentlichen Sie den geprüften Stand mit CMS-Site prüfen und veröffentlichen.