Massnahmenpaket: Katalog

Diese Datei beschreibt das umsetzbare Massnahmenpaket fuer den Aufbau eines Katalogbereichs unter /katalog auf Basis der API rm_catalog_api.

Die API ist unter https://jtlshop-api.recent.digital erreichbar und liefert die erforderlichen Katalog-, Kategorie- und Produktdaten. Ziel ist kein isolierter Shop-Prototyp, sondern ein sauber in recent.digital integrierter Produktbereich mit konsistenter Markenwirkung, klarer Informationsarchitektur und belastbarer technischer Grundlage.

Zielbild

Unter /katalog entsteht ein dreistufiger Katalogbereich:

  1. Shop-Startseite
  2. Shop-Kategorieseite
  3. Shop-Detailseite

Der Bereich soll:

Verbindliche Gestaltungsleitplanken

Fuer die UI des Katalogs gelten dieselben Marken- und Layoutregeln wie fuer den Rest der Seite:

Bestehende Komponenten sollen bevorzugt wiederverwendet werden, insbesondere:

Zielseiten und Inhaltslogik

1. Shop-Startseite

Ziel: Orientierung geben und den Einstieg in den Katalog vereinfachen.

Aufbau:

Anforderungen:

2. Shop-Kategorieseite

Ziel: Produkte innerhalb einer Kategorie schnell erfassbar machen.

Aufbau:

Anforderungen:

3. Shop-Detailseite

Ziel: Produktdaten verstaendlich, vertrauenswuerdig und conversion-orientiert darstellen.

Aufbau:

Anforderungen:

API-Grundlage

Die folgenden Endpunkte bilden den MVP-Rahmen:

Alle Endpunkte sind per API-Key geschuetzt und erwarten den Header X-API-Key.

Beispiel:

curl -H "X-API-Key: <dein-api-key>" \
  "https://shop.example.test/api/catalog/v2/categories/tree"

Technisches Basispaket fuer die API-Anbindung

Neben den sichtbaren Seiten ist eine eigene Integrationsschicht verpflichtender Bestandteil des MVP. Der Katalog darf nicht direkt in den Seiten aus Roh-Responses aufgebaut werden.

Ziel der Integrationsschicht

Die API-Anbindung soll:

Empfohlene Projektstruktur

Fuer die Frontend-Integration sollen diese Bausteine eingeplant werden:

Verantwortung der einzelnen Bausteine

src/lib/catalog/config.ts

src/lib/catalog/client.ts

src/lib/catalog/service.ts

src/lib/catalog/mapper.ts

src/lib/catalog/errors.ts

src/lib/catalog/guards.ts

src/api/Interfaces/catalog.ts

docs/catalog-api-integration.md

Mindestumfang fuer Types und Interfaces

Folgende Typgruppen muessen mindestens definiert werden:

Grundsatz fuer die Umsetzung

Seiten unter /katalog konsumieren keine ungefilterten API-Responses direkt. Sie verwenden ausschliesslich die Integrationsschicht aus src/lib/catalog und die zentralen Types aus src/api/Interfaces/catalog.ts.

Massnahmenpakete

Paket A: Architektur und Routing festziehen

Ziel: Eine saubere Grundlage fuer Katalog-Startseite, Kategorien und Produktdetails schaffen.

Umfang:

Ergebnis:

Paket B: Datenanbindung an rm_catalog_api

Ziel: Die benoetigten API-Daten sicher und konsistent im Frontend nutzbar machen.

Umfang:

Ergebnis:

Paket C: Shop-Startseite gestalten

Ziel: Einen hochwertigen, markenkonformen Einstieg in den Katalog schaffen.

Umfang:

Ergebnis:

Paket D: Kategorieseiten auf Scanbarkeit optimieren

Ziel: Kategorien muessen auf Desktop und Mobile schnell bedienbar und klar lesbar sein.

Umfang:

Ergebnis:

Paket E: Produktdetailseite ausarbeiten

Ziel: Eine fokussierte Detailseite mit hoher Verstaendlichkeit und klarer CTA-Fuehrung.

Umfang:

Ergebnis:

Paket F: Qualitaet, Tests und Betriebsfaehigkeit absichern

Ziel: Der Katalogbereich soll nicht nur gut aussehen, sondern auch verifizierbar stabil laufen.

Umfang:

Ergebnis:

Technische Leitplanken fuer die API

Die API rm_catalog_api verfolgt fuer den aktuellen MVP diese Grundsaetze:

Interne Bausteine des API-Plugins:

Performance-Grundsaetze:

Abhaengigkeiten und Voraussetzungen

Vor oder waehrend der Umsetzung muessen folgende Punkte geklaert oder bereitgestellt sein:

Verifikation

Empfohlener Verifikationspfad fuer die API:

  1. GET /api/catalog/v2/catalog auf gruppierte Startdaten pruefen.
  2. GET /api/catalog/v2/categories/tree pruefen und gueltigen Kategorie-Slug bestaetigen.
  3. GET /api/catalog/v2/categories/by-slug/:slugPath gegen dieselbe Kategorie pruefen.
  4. GET /api/catalog/v2/categories/by-slug/:slugPath/products auf mindestens einen Artikel pruefen.
  5. GET /api/catalog/v2/products/by-slug/:productSlug fuer einen Artikel aus der Liste pruefen.

Vorhandene Referenzen:

Zu dokumentieren im Frontend:

Direkter Aufruf:

SHOP_BASE_URL="https://shop.example.test" \
API_KEY="dein-api-key" \
CATEGORY_ID="123" \
PRODUCT_ID="456" \
./rm_catalog_api/tests/api_smoke_tests.sh

Definition of Done

Das Massnahmenpaket gilt fuer den MVP als erfolgreich umgesetzt, wenn:

Priorisierte Umsetzungsreihenfolge

  1. Paket A: Architektur und Routing
  2. Paket B: Datenanbindung
  3. Paket C: Shop-Startseite
  4. Paket D: Kategorieseiten
  5. Paket E: Produktdetailseite
  6. Paket F: Qualitaet, Tests und Abnahme

Naechste Ausbaustufen nach MVP

Status

Stand 31.03.2026: