2026-11-11 14:27:21 +01:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-07-06 13:37:08 +02:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-09-17 16:02:51 +02:00
2026-10-27 08:03:57 +01:00

place4bees – vereinte Webseite

Selbst-hostbare Architektur: Medusa.js (Shop-Backend + Admin) + Astro (handgebautes Frontend).

place4bees ist die neue, einzige Unternehmensmarke. "Imkerei Björn Schumann" / "hhonig" taucht im Auftritt nirgends mehr auf (außer ggf. später im Impressum aus rechtlichen Gründen).

Struktur

backend/    Medusa-Backend (Node.js, Turborepo), self-hosted via Docker
            → apps/backend enthält die eigentliche Medusa-Instanz
frontend/   Astro-Frontend
docker-compose.yml   Postgres + Redis + Medusa-Backend (self-hosted)

Eine Website, zwei Domains, zwei Bereiche

Es gibt keine zwei Marken mehr, sondern eine Website mit zwei Bereichen ("Sections"), gesteuert über frontend/src/lib/sections.ts:

  • Privatkunden (private): Start, Shop, Über uns, Kontakt
  • Business (business): Start, Angebot, Anfrage (nur Formular, kein Checkout)

Ein persistenter Tab-Umschalter im Header ("Privatkunden" / "Business") ist auf jeder Seite sichtbar und wechselt zwischen den Bereichen – unabhängig davon, auf welcher Domain man sich befindet:

  • hhonig.de → / zeigt automatisch den Privatkunden-Bereich
  • place4bees.com → / zeigt automatisch den Business-Bereich
  • Auf beiden Domains sind beide Bereiche vollständig erreichbar über die stabilen Pfade /privatkunden und /business (die Tabs verlinken immer auf diese festen Pfade, nie auf das host-abhängige /, damit kein Klick-Loop entsteht).

Die Zuordnung passiert in frontend/src/lib/sections.ts (resolveSection, isBusinessHost) anhand des Host-Headers – rein serverseitig, keine Cookies/Redirects nötig.

SEO-Konzept

  • Canonical-Konsolidierung: Da dieselben Inhalte technisch auf zwei Domains erreichbar sind, zeigt jede Seite ihren <link rel="canonical"> fest auf https://place4bees.com/<pfad> (in Layout.astro), unabhängig davon, über welche Domain sie aufgerufen wurde. Damit bündelt Google die Rankings auf einer Domain, statt sie zwischen hhonig.de und place4bees.com aufzuteilen. hhonig.de bleibt für Bestandsbesucher/Backlinks nutzbar, ohne hart per 301 umgeleitet zu werden.
  • 301-Weiterleitungen alter Adressen: erledigt in frontend/src/middleware.ts (26.10.2026). Alle 59 Adressen aus den Sitemaps von hhonig.de, shop.hhonig.de und place4bees.com landen auf einer Seite des neuen Shops; Shopify-Produkte /products/<handle> gehen auf /shop/<handle>, shop.hhonig.de komplett auf place4bees.com.
  • Google Search Console für beide Domains einrichten/aktualisieren, aktualisierte Sitemap einreichen.
  • Produktseiten sollten vor Launch noch strukturierte Daten (schema.org Product) bekommen; der Privatkunden-Bereich zusätzlich LocalBusiness.

Design / Theming

Farben sind als semantische Tokens in frontend/src/styles/global.css definiert (--color-brand-primary, --color-brand-ink, …) statt als rohe Tailwind-Farben in den Komponenten. Ein komplettes Reskinning bedeutet: Werte in dieser einen Datei ändern – Komponenten bleiben unangetastet. Für einen eigenen Akzent nur im Business-Bereich gibt es bereits den Haken [data-section="business"] { ... } in derselben Datei.

Aktuelles Look & Feel (2. Iteration, bewusst kontrastreicher): dunkle Ink-Hero- und Footer-Flächen mit gestaffelter Hexagon-Grafik (.hex-shape in global.css, mehrere überlappende Sechsecke statt einer einzelnen Fläche), große Fraunces-Serifen-Headlines in Creme auf Dunkelbraun, Honiggold als Primärfarbe im Privatkunden-Bereich, Petrolgrün im Business-Bereich (automatisch über [data-section="business"]). Shop-Karten mit Schatten, Hover-Lift-Animation und Kategorie-Badges.

Checkout-Flow

Voll funktionsfähig gegen die Medusa Store API, End-to-End getestet:

  1. Produktseite (/shop/[handle]) → AddToCartButton legt bei Bedarf einen Cart an (Cookie cart_id) und fügt die gewählte Variante hinzu.
  2. Warenkorb (/warenkorb) → Menge ändern / Position entfernen.
  3. Kasse (/kasse) → Adresse, Versandart (aus Medusa geladen), Zahlung.
  4. Bestellbestätigung (/bestellung/danke).

Zahlung läuft im Frontend aktuell noch über Medusas eingebauten pp_system_default-Provider (kein echtes Zahlungs-Gateway). Das PayPal-Backend ist bereits vorbereitet (siehe unten), die Frontend-Anbindung fehlt noch.

Alle Cart/Checkout-Aufrufe laufen direkt vom Browser aus gegen die Medusa Store API (frontend/src/lib/cart.ts), ohne eigene Backend-Route dazwischen.

Die Kasse (/kasse) ist zweispaltig aufgebaut: links Kontakt-/Adressformular + Versandart in Karten gruppiert, rechts eine sticky Bestellübersicht (Positionen, Zwischensumme, Versand, Gesamt), die sich beim Wechsel der Versandart live aktualisiert. Ist ein Kunde angemeldet, werden E-Mail/Name aus dem Kundenprofil vorausgefüllt.

Kundenkonten: Anmelden, Bestellungen ansehen & verfolgen

Nutzt Medusas eingebautes Customer-Auth (kein eigenes Modul nötig): POST /auth/customer/emailpass/register (Registrierung) → POST /store/customers (Profil anlegen) → POST /auth/customer/emailpass (Login, liefert das eigentliche mit der Kundennummer verknüpfte Token – das Registrierungstoken ist zu diesem Zeitpunkt noch nicht verknüpft und funktioniert für authentifizierte Routen nicht).

  • frontend/src/lib/auth.ts – registerCustomer, loginCustomer, getCustomerMe, listMyOrders, getMyOrder, transferCartToCustomer.
  • Token liegt in einem normalen (nicht httpOnly) Cookie customer_jwt – bewusst wie im offiziellen Medusa Next.js-Starter, damit sowohl Browser-JS (Cart-Aufrufe) als auch Astro-SSR-Frontmatter (Kontoseiten) denselben Cookie lesen können, ohne eine eigene Proxy-Route zu brauchen. AUTH_CORS/STORE_CORS sind dafür schon passend gesetzt.
  • Konto-Seiten: /konto/anmelden, /konto/registrieren, /konto (Bestellübersicht), /konto/bestellungen/[id] (Details + Sendungsverfolgung: 4-stufiger Status Bestellt→Verpackt→Versendet→Zugestellt, Tracking-Links, Rechnungs-Download).
  • Cart ↔ Kunde verknüpfen: Ein Warenkorb bekommt nur dann automatisch eine customer_id, wenn er bereits authentifiziert erstellt wurde. Da bei uns meist erst der Warenkorb gefüllt und danach (an der Kasse) eingeloggt wird, ruft kasse.astro beim Absenden zusätzlich POST /store/carts/:id/customer auf, um den bestehenden Cart nachträglich dem Kunden zuzuordnen – sonst würde die fertige Bestellung nicht unter "Meine Bestellungen" auftauchen.
  • Backend: src/api/store/customers/me/orders/[id]/route.ts – eigene Route für Bestelldetails inkl. Tracking. Kombiniert bewusst zwei einzeln erprobte Techniken statt einer riskanten Kombination: OrderModuleService.retrieveOrder() für Positionen/Adresse/Versandarten (wie schon bei den Rechnungen), plus einen gezielten query.graph()-Aufruf nur für fulfillments.labels/Tracking-Zeitstempel (die als verlinktes Fulfillment-Modul nicht über retrieveOrder erreichbar sind). Geschützt automatisch durch Medusas eigene ALL /store/customers/me*-Middleware; zusätzlicher eigener Ownership-Check (order.customer_id === auth_context.actor_id), da Medusas öffentliche /store/orders/:id-Route laut eigenem Code-Kommentar bewusst (noch) keine Auth-Prüfung hat.
  • End-to-End per Playwright verifiziert: Registrierung → Produkt in den Warenkorb → Kasse (Vorausfüllung geprüft) → Bestellung abschließen → Bestellung erscheint unter "Meine Bestellungen" → Detailseite zeigt Adresse/Positionen/Status → Rechnungs-Download funktioniert.

Zahlungsanbieter: PayPal

Hinweis zur Wahl: Medusa pflegt offiziell nur eine Stripe-Integration. Für PayPal gibt es kein offizielles Plugin, nur Community-Pakete einzelner kleiner Anbieter – hier verwendet: @easypayment/medusa-payment-paypal (aktuell das am aktivsten gepflegte). Das ist ein bewusst in Kauf genommenes Risiko (Wartung/Sicherheit liegen bei einem kleinen Drittanbieter, nicht bei Medusa selbst) – wurde nach Rücksprache trotzdem gewünscht.

Bereits erledigt (Backend):

  • Plugin installiert, in medusa-config.ts registriert (Plugin + zwei Payment-Provider: paypal für Smart Buttons/Wallet, paypal_card für Karten-Zahlung über PayPal).
  • Datenbank-Migration ausgeführt.
  • Beide Provider (pp_paypal_paypal, pp_paypal_card_paypal_card) für die Europe-Region aktiviert.
  • Server startet fehlerfrei mit der neuen Konfiguration.

Noch offen (braucht dich):

  1. PayPal-Konto verbinden: Medusa Admin → Settings → PayPal → PayPal Connection → zunächst Sandbox wählen (Test-Modus, kostenlos und ohne Geschäftskonto-Prüfung sofort über developer.paypal.com anlegbar) → "Connect to PayPal" oder Client-ID/Secret manuell eintragen.
  2. Frontend-Anbindung fehlt noch: Das mitgelieferte UI-Paket (@easypayment/medusa-paypal-ui) ist explizit für Next.js-Storefronts gebaut und passt nicht zu unserem Astro-Frontend. Die PayPal-Buttons müssen wir selbst gegen PayPal's JS-SDK und die Medusa-Payment-Session bauen – das kann ich erst sinnvoll umsetzen und testen, sobald ein Sandbox-Konto verbunden ist (sonst baue ich ungetesteten Zahlungscode).
  3. Sobald Sandbox läuft: echte End-to-End-Bestellung testen, dann auf Live umschalten (im selben Admin-Screen, ohne Server-Neustart laut Plugin-Doku).
  4. Optional: PAYPAL_ENCRYPTION_KEY (beliebiger starker Zufallsstring) in .env setzen, damit die gespeicherten PayPal-Zugangsdaten in der Datenbank verschlüsselt statt im Klartext liegen.

Produktdaten: Preis, MwSt., Grundpreis, Lieferzeit

  • Preise sind inkl. MwSt. und werden auch so angezeigt (Pflicht im B2C-Verkauf in Deutschland). Technisch über Medusas "Price Preferences" gelöst (/admin/price-preferences, is_tax_inclusive: true für Währung UND Region – beide müssen übereinstimmen, siehe Bugfix unten).
  • Zwei Steuersätze eingerichtet für die Deutschland-Steuerregion: 7% ermäßigt für alle 13 Honig-Produkte (Lebensmittel), 19% Standard für alles andere (Bienenprodukte, Süßigkeiten, Kurse, Gutscheine, Patenschaft). Bitte mit einem Steuerberater gegenprüfen – insbesondere Gutscheine und Kurse/Patenschaften können abweichende umsatzsteuerliche Behandlung erfordern, das habe ich nur nach bestem Wissen als Entwickler, nicht als Steuerexperte eingerichtet.
  • Grundpreis (Preis pro kg) wird auf Produktseite und in der Shop-Übersicht angezeigt, wo vorhanden – berechnet aus dem tatsächlichen Nettofüllgewicht (z.B. "500 Gramm" aus dem Variantennamen), nicht aus dem Versandgewicht. Gespeichert als metadata.net_weight_grams pro Variante. Nur bei den 13 Honigsorten vorhanden (einzige Produkte, die nach Gewicht verkauft werden – für Gutscheine, Kurse, Kerzen etc. ist kein Grundpreis vorgeschrieben).
  • Lieferzeit ("2-3 Werktage") als metadata.delivery_time pro Produkt hinterlegt und auf der Produktseite separat angezeigt (vorher stand das nur unstrukturiert im Beschreibungstext).
  • Kategorie-Badge (Honig, Bienenprodukte, Süßigkeiten mit Honig, Geschenkgutschein, Kurse, Bienenpatenschaften) aus den ursprünglichen Shopify-Tags als metadata.category übernommen, auf Shop-Karte und Produktseite sichtbar.

Wichtiger Bugfix: Medusa hatte Produktpreise und Versandkosten inkonsistent besteuert – Produkte inkl. MwSt. (Bruttopreis blieb gleich), Versand exkl. MwSt. (Steuer wurde zusätzlich draufgerechnet, 10€ Versand wurden im Warenkorb zu 11,90€). Ursache: zwei widersprüchliche Price-Preference-Einträge (currency_code: eur → inklusiv, region_id Deutschland → exklusiv). Behoben, indem die Region-Preference ebenfalls auf is_tax_inclusive: true gesetzt wurde. End-to-End getestet: 7,90€ Honig + 10€ Versand = 17,90€ Gesamtsumme, keine versteckte Aufpreisung mehr.

Lokal starten

# Postgres + Redis + Backend
docker compose up -d

# oder Backend lokal für Entwicklung (schneller iterieren):
cd backend/apps/backend && npm run dev   # läuft auf Port 9001 (9000 war lokal belegt)

# Frontend
cd frontend && npm run dev               # läuft auf Port 4321

Admin-Oberfläche für Produktpflege: http://localhost:9001/app (Login wurde angelegt: admin@hhonig.de / ChangeMe123! – bitte nach dem ersten Login ändern.)

Host-abhängiges Verhalten lokal testen:

curl -H "Host: hhonig.de" http://localhost:4321/       # → Privatkunden
curl -H "Host: place4bees.com" http://localhost:4321/  # → Business

(server.allowedHosts in astro.config.mjs erlaubt diese Test-Hostnamen gegen den Dev-Server.)

Bereits erledigt

  • Medusa-Backend lokal lauffähig (Postgres + Redis via Docker), Admin-User angelegt, Admin-UI getestet.
  • Astro-Frontend mit Tailwind, Node-SSR-Adapter, zentralen Design-Tokens.
  • Eine Website, zwei Bereiche (Privatkunden/Business) mit persistentem Tab-Umschalter, host-abhängigem Default, konsistent auf beiden Domains erreichbar.
  • Shop-Anbindung an Medusa Store API funktioniert End-to-End (Produktliste + Produktdetail).
  • Kompletter Checkout-Flow (Cart → Adresse → Versand → Zahlung → Bestellung) gebaut und End-to-End getestet, Bestellung erscheint im Admin.
  • Produktkatalog von shop.hhonig.de migriert: alle 23 Produkte (Honig, Bienenprodukte, Patenschaften, Kurse, Gutscheine, Süßigkeiten) über Shopifys öffentliche products.json-API ausgelesen und per Medusa Admin API angelegt – inkl. Varianten (Größen/Nennwerte), Preisen und Bildern. Migrations-Skript: siehe unten.
  • Preis-Darstellung im Frontend korrigiert: Medusa v2 speichert Beträge als Dezimalwert (10 = 10,00 €, keine Cent-Umrechnung) – frühere /100-Division in Warenkorb/Kasse/Produktseite entfernt.
  • Produktseite zeigt bei mehreren Größen/Varianten jetzt den zur aktuellen Auswahl passenden Preis (aktualisiert sich beim Wechsel der Variante).
  • Produktseite wechselt beim Wechsel der Variante zusätzlich das große Produktbild, sofern der Variante im Medusa Admin ein eigenes Bild zugewiesen wurde (variant.thumbnail – ein normales, direkt setzbares Feld, kein automatisch berechnetes: POST /admin/products/:id/variants/:variant_id mit {thumbnail: "<Bild-URL>"}). Ohne zugewiesenes Bild bleibt beim Variantenwechsel einfach das zuletzt gezeigte Bild stehen, statt zu verschwinden. Aktuell hat noch keine Variante ein eigenes Bild – am sinnvollsten wäre das bei "Bienenwachskerzen" (4 optisch komplett unterschiedliche Kerzenformen, 5 vorhandene Produktfotos), das müsste aber jemand mit Blick auf die tatsächlichen Fotos zuordnen, da die Dateinamen (PhotoRoom_..., WhatsApp...) keinen Rückschluss auf die passende Kerze zulassen.
  • Produktbilder selbst gehostet (nicht mehr auf Shopify-CDN verlinkt), siehe Produktmigration unten.
  • PayPal-Backend vorbereitet (Plugin, Provider, Region-Aktivierung) – Frontend-Buttons folgen, siehe "Nächste Schritte".
  • MwSt. (7%/19%, inkl.-Anzeige), Grundpreis (€/kg) und Lieferzeit je Produkt ergänzt, siehe eigener Abschnitt unten.
  • Redesign: dunkle Hero-/Footer-Flächen mit gestaffelter Hexagon-Grafik, überarbeitete Shop-Karten mit Preis/Grundpreis/Kategorie-Badge.
  • Startseiten (Privatkunden/Business) mit Scroll-Animationen aufgewertet: Hero-Hintergrundbilder haben jetzt einen echten Parallax-Effekt (JS berechnet die Verschiebung jeder .parallax-layer relativ zu ihrer eigenen Position im Viewport, nicht am rohen scrollY, sodass es unabhängig davon funktioniert, wie weit unten auf der Seite eine Sektion sitzt – Layout.astro). Das bestehende .reveal-Fade-up wurde um Richtungs-Varianten ergänzt (.reveal-left, .reveal-right, .reveal-scale, alle setzen beim Sichtbarwerden auf denselben neutralen Transform-Zustand zurück, damit die Observer-Logik unverändert bleibt), Kennzahlen zählen beim Scrollen hoch (data-count-to, [data-count-to] in Layout.astro), und die Privatkunden-Seite hat eine neue Produkt-Teaser-Sektion (3 echte Shop-Produkte) sowie eine Sticky-Text/Stats-Sektion analog zur Business-Seite bekommen. Alles respektiert prefers-reduced-motion (Parallax-Listener wird dann gar nicht erst angehängt, Reveal-Übergänge werden auf ~0 verkürzt) und wurde per Playwright verifiziert (Parallax-Bewegung, Count-up-Endwert, reduced-motion-Stillstand).
  • Design komplett auf die place4bees-CI-Vorlage umgestellt (Honig-Orange, Oswald/Inter, Wellen-Rand, fliegende Bienen, Timeline/Stats-Sektionen), echte Fotos/Partnerlogos von place4bees.com eingebunden, Business-Bereich um 5 echte Unterseiten erweitert (Ihr Projekt, Über uns, Philosophie, Presse, Kontakt).
  • Mit dem originalen Website-Briefing (10.01.2022) abgeglichen und Lücken/Fehler behoben:
    • Markenfarbe korrigiert: #f5a623 → #f8ac11 – Pixel-Extraktion aus dem echten Logo (logo-badge.png) ergab #f8ac15, praktisch identisch mit dem im Briefing spezifizierten #f8ac11 und klar abweichend vom bisher verwendeten Wert. Global über --color-brand-primary sowie an allen Stellen mit hartkodiertem Hex-Wert (Kasse, Admin-Widget) korrigiert.
    • Drei ergänzende CI-Farben aus dem Briefing als Variablen ergänzt (--color-brand-green #9fc7aa, --color-brand-gray #737373, --color-brand-indigo #5a6aab) und für Abschnitts-Farbvielfalt genutzt (indigo-Hintergrund für die neue Prinzipien-Sektion auf der Philosophie-Seite, passend zur Briefing-Vorgabe „klare Abschnitte – farblich").
    • /business/ihr-projekt: generische 8-Punkte-Liste durch die 10 echten, ausführlichen Leistungspunkte aus dem Briefing ersetzt (inkl. der vom Kunden im Dokument selbst korrigierten Kachel „Kommunikation" statt „Branding der Bienenbox").
    • /business/philosophie: um die 4 echten Mission-Statements ("Wir möchten…") sowie eine neue 6er-Prinzipien-Reihe (Verantwortungsbewusstsein, Biodiversität, Regionalität, Nachhaltigkeit, Leuchtturmwirkung, Ganzheitlichkeit) aus dem Briefing ergänzt.
    • Bewusst NICHT übernommen (da durch spätere/aktuellere Infos bereits überholt): die Adresse "Heimhuder Str. 60" aus dem 2022-Briefing – alle Rechtstexte und Kontaktseiten nutzen bereits konsistent "Isestraße 109" aus einer neueren echten Rechnung; die 5-Punkte-Navigation (Unternehmensbienen/Philosophie/Über uns/Bienenwissen/Kontakt) – die aktuelle, umfangreichere Navigation mit Presse/Angebot/Anfrage ist eine spätere, bewusste Erweiterung; das echte Team samt Fotos/Zitaten auf „Über uns" existiert bereits vollständiger als im Briefing (das dort noch „–Platzhalter–" vermerkt). Falls „Heimhuder Str. 60" doch noch aktuell sein sollte, bitte Bescheid geben.
  • Echte Medusa-Produktkategorien angelegt (Honig, Bienenprodukte, Geschenkgutschein, Kurse, Bienenpatenschaften, Süßigkeiten mit Honig) und alle 23 Produkte anhand ihres bisherigen metadata.category-Werts zugeordnet; die 4 ungenutzten Demo-Kategorien aus dem Medusa-Seed (Shirts/Merch/Sweatshirts/Pants) gelöscht. Shop-Seite, Produktdetailseite und Filter-Pills nutzen jetzt product.categories (inkl. rank für die Reihenfolge) statt des metadata.category-Strings – Kategorien sind damit im Medusa-Admin wirklich verwaltbar (umbenennen/Reihenfolge wirkt sich direkt auf den Shop aus).
  • Rechnungs-PDF (selbst gebaut, kein Drittanbieter-Plugin) und Sendcloud-Versandanbindung (Code fertig, wartet auf echten Account) – siehe eigener Abschnitt unten.
  • Kundenkonten: Registrierung/Login, Bestellübersicht und Bestelldetails mit Sendungsverfolgung – siehe eigener Abschnitt oben ("Kundenkonten").
  • Shop-Seite modernisiert (/shop/index.astro): dunkle Hero-Sektion mit Trust-Badges, sticky Toolbar (Kategorie-Pills + Live-Suche + Sortierung nach Preis/Name), Karten im 4:5-Format mit Kategorie-Badge, Lieferzeit-Hinweis und einem Quick-Add-Button, der bei Hover über dem Produktbild einblendet. Karten mit nur einer Variante lassen sich so direkt aus der Liste in den Warenkorb legen (ohne die Produktseite zu öffnen); Produkte mit mehreren Varianten zeigen stattdessen einen Hinweis „X Varianten – Auswahl im Produkt“, da die Größenwahl dort stattfinden muss. Technisch: Karte ist ein <div> mit einem absolut positionierten, die ganze Karte überspannenden <a> („stretched link") plus dem Quick-Add-<button> darüber (höherer z-index) – so bleibt die Karte komplett klickbar, ohne ein ungültiges <button> in <a>-Nesting zu erzeugen. Alle Interaktionen (Filter/Suche/Sortierung/Quick-Add) laufen rein clientseitig auf den beim Seitenaufruf bereits geladenen 23 Produkten, ohne Nachladen. 3 Produkte (Presshonig, Kornblumenhonig, Geschenkgutschein) haben aus der ursprünglichen Migration heraus kein Bild – dafür zeigt die Karte jetzt einen dezenten Bienen-Platzhalter statt einer leeren Fläche; echte Produktfotos für diese 3 wären ein guter nächster Schritt.
  • Honigwaben-Motiv (frontend/src/styles/global.css, Klassen .honeycomb-edge/.honeycomb-bg): der untere Rand jedes Produktfotos ist per clip-path in eine Reihe von Hexagon-Zacken geschnitten (das hellgraue Karten-Innere schimmert in den Kerben durch, wie ein angebrochenes Wabenstück) – geclippt wird bewusst nur ein eigener Bild-Wrapper, nie die ganze Karte, damit Badge/Quick-Add-Button und der unterschiedlich lange Textblock nie mit abgeschnitten werden können. Shop- und Warenkorb-Sektion haben zusätzlich eine sehr dezente Hexagon-Gitter-Textur als Hintergrund (SVG-Tile, ca. 7% Deckkraft) statt der bisherigen schlichten Fläche.
  • Warenkorb neugestaltet (/warenkorb): gleiches zweispaltiges Karten-Layout wie die Kasse (Positionen links, sticky Zusammenfassung rechts), Mengenauswahl jetzt als +/–-Stepper statt nacktem Zahlenfeld, leerer Warenkorb zeigt eine echte Karte mit CTA statt eines reinen Textsatzes. Nutzt dieselbe honeycomb-bg-Hintergrundtextur wie der Shop für ein konsistentes Bild über beide Seiten hinweg.

Produktmigration (Shopify → Medusa)

Einmalig ausgeführtes Node-Skript, kein Teil der laufenden App: holt den Katalog über Shopifys öffentliche https://shop.hhonig.de/products.json-API und legt jedes Produkt per Medusa Admin API an (Varianten, Preise, Bilder). Nicht im Repo abgelegt (lief aus dem Scratchpad); bei Bedarf einfach neu schreiben oder erneut anfragen.

Bewusste Vereinfachungen beim Import, die noch nachgezogen werden sollten:

  • Bilder waren extern auf cdn.shopify.com verlinkt – erledigt: alle 52 Bilder heruntergeladen und über Medusas lokales File-Modul selbst gehostet (/static/... auf dem Medusa-Server). Konfiguriert in medusa-config.ts (@medusajs/file-local, backend_url aus MEDUSA_BACKEND_URL). Für Produktion: MEDUSA_BACKEND_URL auf die echte Backend-Domain setzen, sonst zeigen die Bild-URLs auf localhost.
  • Tags/Kategorien wurden nicht übernommen (Medusas Tag-API verlangt vorab angelegte Tag-IDs). Die Shopify-Kategorien (Honig, Bienenprodukte, Bienenpatenschaften, Kurse, Geschenkgutschein, Süßigkeiten) liegen aber in den Rohdaten vor und lassen sich bei Bedarf nachträglich als Medusa-Kategorien/Collections anlegen, sobald es eine Kategorie-Navigation im Frontend gibt.
  • Varianten sind auf manage_inventory: false gesetzt (immer bestellbar, keine Lagerbestandsprüfung) – für den Start pragmatisch, sollte aber vor Go-Live durch echte Lagerbestände ersetzt werden, damit nichts verkauft wird, was nicht vorrätig ist.
  • Ein Medusa-Demo-Produkt ("Medusa T-Shirt") ließ sich nicht löschen, da eine Testbestellung eine Lagerreservierung dafür hält – unschädlich, kann später im Admin entfernt werden, sobald die Testbestellung storniert/gelöscht ist.

Produktfotos freistellen & Hintergrund austauschen (selbst gehostet, keine externe API)

Neues Admin-Widget auf jeder Produktseite ("Hintergrund freistellen", unterhalb von Variants): eines der vorhandenen Produktbilder auswählen, Hintergrund per KI automatisch entfernen lassen, dann als neuen Hintergrund eine Farbe (Presets oder freier Farbwähler), ein anderes bereits hochgeladenes Bild, oder eines von zwei kuratierten Motiv-Presets wählen – das Ergebnis wird als zusätzliches Bild zur Produktgalerie hinzugefügt, das Original bleibt unangetastet.

Motiv-Presets: Zwei echte Fotos aus dem bestehenden Bildbestand der Seite (backend/apps/backend/src/assets/backgrounds/, kopiert aus frontend/public/images/) – "Bienenstock" (business-hero.jpg) und "Biene auf Blüte" (business-hero-2.jpg) – direkt im Widget als Miniaturansicht anklickbar, kein manueller Bild-Upload pro Produkt nötig. Ausgeliefert über zwei neue Routen: GET /admin/background-presets (Liste für die Vorschau) und GET /admin/background-presets/:key (liefert die eigentlichen Bilddaten, wird sowohl fürs <img>-Thumbnail im Widget als auch – lokal von der Festplatte gelesen, kein HTTP-Umweg – vom apply-background-Endpunkt zum Kompositieren genutzt). Weitere Presets: einfach eine neue Datei in den Ordner legen und in background-presets.ts eintragen.

  • Ursprünglicher Anstoß: Bitte um ein KI-generiertes Bienenstock-Bild – das kann ich nicht (kein Bildgenerierungs-Tool), aber ein Test mit dem bereits vorhandenen business-hero.jpg als Hintergrund sah bereits überzeugend aus, daher die Presets aus echten, vorhandenen Fotos statt generierter Bilder.

Lizenz-Hintergrund, warum nicht einfach IMG.LY: Die naheliegende Lösung (@imgly/background-removal-node) ist AGPL-lizenziert, was bei kommerziellem Einsatz entweder Quellcode-Offenlegung oder eine kostenpflichtige Lizenz von IMG.LY erfordert. Stattdessen selbst gebaut mit einem sauber lizenzierten Modell:

  • Modell: isnet-general-use.onnx (backend/apps/backend/src/assets/isnet-general-use.onnx, ~179 MB) von danielgatis/rembg (MIT), das wiederum das IS-Net-Modell von xuebinqin/DIS ("Highly Accurate Dichotomous Image Segmentation", ECCV 2022, Apache-2.0) als ONNX exportiert. Durchgehend permissive Lizenzkette, bewusst nicht eines der IMG.LY-Modelle verwendet.
    • Zuerst mit dem kleineren u2netp.onnx (U-2-Net, ~4,5 MB, 320px) gebaut und getestet – funktionierte, aber die Kanten waren sichtbar ungenau. Auf isnet-general-use umgestiegen (1024px Eingabe, ~800ms statt ~300ms pro Bild, deutlich schärfere Kanten, gleiche saubere Lizenzkette). u2netp.onnx danach aus dem Repo entfernt, da nicht mehr referenziert.
    • Wichtige Falle beim Umstieg: IS-Net erwartet eine andere Preprocessing-Normalisierung als U2Net – nicht die ImageNet-Werte (mean 0.485/0.456/0.406), sondern flach mean=0.5/0.5/0.5, std=1.0/1.0/1.0. Sogar rembgs eigene Referenzimplementierung hatte das bis März 2025 falsch (per PR gefixt) – vorher stillschweigend geprüft (Rohausgabe des Modells als ASCII-Grid kontrolliert), bevor es in die Pipeline eingebaut wurde.
  • Inferenz: onnxruntime-node (MIT, native Bindings – kein Python-Sidecar nötig) + sharp fürs Bild-Preprocessing/Compositing. Läuft komplett lokal auf dem Medusa-Server, keine externe API, keine Kosten pro Bild.
  • Code: backend/apps/backend/src/lib/background-removal.ts (removeBackground, replaceBackground), zwei Admin-Routen (POST /admin/products/:id/remove-background, POST /admin/products/:id/apply-background) und das Widget backend/apps/backend/src/admin/widgets/product-background-widget.tsx.
  • Beim ersten Bauen (mit u2netp) zwei reale, stille Bugs gefangen und gefixt (beide haben KEINEN Fehler geworfen, nur falsche/verrauschte Ergebnisse produziert), die beim Modellwechsel unverändert mitgelten: (1) das hochskalierte Masken-Bild wurde ohne .raw() zurückgegeben, wodurch sharp es PNG-kodiert hat und die kodierten Bytes später als rohe Pixel fehlinterpretiert wurden; (2) sharp().resize() auf einem Einkanal-Graustufen-Rohbuffer wandelt intern zu 3 Kanälen um (Bufferlänge exakt 3× erwartet), was ein explizites .extractChannel(0) danach nötig macht. Beides nur durch Ausgabe einer ASCII-Grafik der tatsächlichen Alpha-Werte auffindbar – rein visuell im Bildbetrachter (Transparenz wird als Weiß gerendert) nicht erkennbar.

Rechnungen & Versand (selbst gebaut, kein Drittanbieter-Plugin)

Bei beiden hatten wir zuerst Community-Plugins evaluiert (@rsc-labs/medusa-documents-v2 für Rechnungen, @saphes/medusa-sendcloud-plugin für Sendcloud) – die Rechnungs-Plugin-Automatisierung (E-Mail-Versand) steckt hinter einer kostenpflichtigen Pro-Version, das Sendcloud-Plugin ist mit Versionsnummer 0.0.11 sehr unreif. Auf Wunsch daher beides selbst gebaut, direkt gegen die jeweilige Rohdatenbasis bzw. offizielle API.

Rechnungen

  • backend/apps/backend/src/lib/invoice-pdf.ts – erzeugt das PDF (pdfkit), Design orientiert an einer echten Beispielrechnung (Logo oben rechts, Adressblock + Rechnungs-Meta zweispaltig, schattierte Positionstabelle inkl. Versandkosten als eigene Zeile, Netto/Steuer/Brutto-Summenblock je Steuersatz getrennt (§14 UStG-konform bei gemischten Sätzen), 4-spaltige Fußzeile mit Firmen-/Kontakt-/Handelsregister-/Bankdaten). Logo liegt unter backend/apps/backend/src/assets/place4bees-logo.png.
  • backend/apps/backend/src/lib/invoice-tax.ts – berechnet die Steuer-Aufschlüsselung selbst aus dem bekannten Kategorie→Satz-Mapping (Honig = 7%, sonst 19%), da die in der Bestellung gespeicherten tax_lines sich beim Testen als unzuverlässig/leer herausstellten.
  • backend/apps/backend/src/lib/invoice-handler.ts – gemeinsame Logik für Admin- und Store-Route. Nutzt bewusst OrderModuleService.retrieveOrder() statt des Workflow-basierten getOrderDetailWorkflow – Positionen/Summen ließen sich über die Workflow-Felder-Syntax nicht zuverlässig laden (mehrfach getestet), die direkte Service-Abfrage lieferte konsistent korrekte Rohdaten. Summen (Zwischensumme, Versand, Gesamt) werden daraus selbst berechnet (Menge × Einzelpreis), nicht aus Medusas berechneten Order-Feldern übernommen.
  • Admin: GET /admin/orders/:id/invoice – Rechnung für dich als PDF (Admin-Auth erforderlich).
  • Kunde: GET /store/orders/:id/invoice + Download-Button auf /bestellung/danke im Frontend. Läuft technisch als Fetch-mit-Publishable-Key + Blob-Download (ein normaler Link-Klick hätte den nötigen Header nicht mitgeschickt – das war ein echter Bug, den der End-to-End-Test aufgedeckt hat).
  • Automatischer E-Mail-Versand fehlt noch – dafür braucht Medusa einen konfigurierten Notification-Provider (Resend/Postmark/SMTP). Sobald du einen Anbieter hast, ergänzen wir einen Subscriber auf das order.placed-Event, der die Rechnung anhängt.
  • Admin-UI: backend/apps/backend/src/admin/widgets/order-invoice-widget.tsx – eigenes Widget in der Zone order.details.side.after, zeigt auf jeder Bestellseite im Medusa-Dashboard eine Karte "Rechnung" mit Button "Rechnung herunterladen" (ruft /admin/orders/:id/invoice per Fetch+Blob auf, nutzt die vorhandene Admin-Session). Kein manuelles URL-Eintippen mehr nötig – per Playwright-Test verifiziert (Login, Klick auf Bestellung, Klick auf Button, echter PDF-Download).

Versand (Sendcloud)

  • backend/apps/backend/src/modules/sendcloud-fulfillment/ – eigener Fulfillment-Provider gegen Sendclouds offizielle v2-REST-API (Basic Auth mit Public/Secret Key). Implementiert getFulfillmentOptions (lädt verfügbare Versandarten), createFulfillment (erstellt Sendungen + Label, liefert Tracking-Nummer/-URL zurück – die dann automatisch in Bestellstatus/Kundenansicht erscheinen, da das ein Medusa-Bordmittel ist), cancelFulfillment.
  • Ungetestet: Es gab beim Bau noch keinen echten Sendcloud-Account – die Implementierung folgt der dokumentierten API, wurde aber nie gegen echte Zugangsdaten verifiziert. Vor dem produktiven Einsatz unbedingt mit einem echten (auch testweise kostenlosen) Sendcloud-Account einmal Ende-zu-Ende durchspielen und dabei die Anfrage-/Antwortformate gegen die aktuelle Sendcloud-Doku (https://api.sendcloud.dev) gegenprüfen.
  • Das Modul wird in medusa-config.ts nur registriert, wenn SENDCLOUD_PUBLIC_KEY/SENDCLOUD_SECRET_KEY gesetzt sind (aktuell leer in .env) – so bricht der Server ohne Account nicht, und die Aktivierung ist später nur das Eintragen der Zugangsdaten + Neustart.
  • Danach: Provider im Admin für die Region freischalten (wie bei PayPal) und eine echte Versandart damit verknüpfen.

Audit-Ergebnis vor dieser Änderung: Impressum, Datenschutzerklärung, AGB und Widerrufsbelehrung existierten überhaupt nicht (keine Seiten, keine Footer-Links), an der Kasse fehlte die AGB/Widerruf-Checkbox, und weder die Bestellbestätigung noch die Rechnung erwähnten das Widerrufsrecht. Cookies (cart_id, customer_jwt) sind beide technisch notwendig – keine Analytics/Tracker gefunden, Schriften bereits selbst gehostet (kein Google-Fonts-Risiko).

Wichtig: Die aktuellen Live-Seiten (hhonig.de, shop.hhonig.de) weisen im Impressum "Imkerei Björn Schumann" (Einzelunternehmer, USt-ID DE323619957) aus, während unsere Rechnungsvorlage "PLACE4BEES GmbH" (USt-ID DE350889068) verwendet – zwei unterschiedliche Rechtsträger. Nach Rücksprache wurde PLACE4BEES GmbH als der Rechtsträger bestätigt, der den neuen Shop betreibt; alle unten genannten Seiten nutzen diese Daten.

  • Neue Seiten: /impressum, /datenschutz, /agb, /widerrufsrecht (inkl. Muster-Widerrufsformular), verlinkt im Footer (Footer.astro). Jede Seite zeigt oben eine gelbe Entwurf-Notiz (components/DraftNotice.astro) – die Texte basieren auf den uns bekannten Firmendaten und gängigen Standardformulierungen für Waren/Kurse/Gutscheine/Patenschaften, wurden aber nicht von einer Anwältin/einem Anwalt geprüft. Notiz erst entfernen, wenn das passiert ist.
  • Cookie-Hinweis (components/CookieNotice.astro, in Layout.astro eingebunden): reiner Informations-Banner mit „Verstanden"-Button, kein Opt-in-Consent-Gate – weil aktuell ausschließlich technisch notwendige Cookies gesetzt werden, ist nach § 25 Abs. 2 Nr. 2 TTDSG keine Einwilligung nötig. Dismiss-Status liegt in localStorage, nicht in einem weiteren Cookie. Falls später Analytics/Marketing-Cookies dazukommen, muss das durch einen echten Opt-in-Consent-Manager ersetzt werden.
  • Kasse: neue Pflicht-Checkbox „Ich habe die AGB und die Widerrufsbelehrung gelesen und akzeptiere sie" vor dem Bestellen-Button (kasse.astro) – blockiert den Submit nativ per HTML5 required, keine zusätzliche JS-Validierung nötig.
  • Rechnung: invoice-pdf.ts hängt jetzt automatisch eine vollständige Widerrufsbelehrung als weitere Seite(n) an (Art. 246a § 1 Abs. 2 EGBGB verlangt Bereitstellung auf einem dauerhaften Datenträger, spätestens bei Lieferung). Da die Widerrufsbelehrung als frei fließender Text gerendert wird (Länge vorher nicht bekannt) statt wie Seite 1 mit festen Koordinaten, nutzt der Code bufferPages: true + doc.bufferedPageRange(), um Seitenzahlen ("Seite X von Y") erst ganz am Schluss zu stempeln, wenn die tatsächliche Gesamtseitenzahl feststeht. Dabei zunächst ein echter Bug: die Seitenzahl wurde 20pt über dem Seitenende platziert, 5pt innerhalb des reservierten unteren Rands (25pt) – pdfkit interpretierte das als "passt nicht mehr drauf" und fügte automatisch leere Zusatzseiten ein. Behoben durch Verschieben auf 40pt über dem Seitenende.
  • Bestellbestätigung (bestellung/danke.astro): kurzer Hinweis-Satz mit Link auf /widerrufsrecht.
  • Alles End-to-End mit Playwright verifiziert: Cookie-Banner erscheint/verschwindet und bleibt es nach Reload, Footer-Links korrekt, Checkout-Submit ohne Haken blockiert, Rechnung hat nach dem Fix exakt 2 Seiten mit korrekter Paginierung.

Nächste Schritte

  1. Sendcloud-Account anlegen, Zugangsdaten in .env eintragen, End-to-End mit echtem Label testen.
  2. E-Mail-Anbieter (Resend/Postmark/SMTP) einrichten, damit Rechnungen automatisch per Mail rausgehen.
  3. PayPal-Sandbox-Konto verbinden (Medusa Admin → Settings → PayPal) und danach die PayPal-Buttons im Frontend bauen (siehe oben).
  4. Steuersätze/-zuordnung von einem Steuerberater gegenprüfen lassen (siehe oben), bevor echte Bestellungen laufen.
  5. Echte Lagerbestände pflegen statt manage_inventory: false (aktuell immer bestellbar, keine Bestandsprüfung).
  6. Kontakt-/Anfrage-Formulare (/kontakt, /business/anfrage) an einen Versand-Endpunkt anbinden (z.B. E-Mail-Versand über eigenes API-Route in Astro).
  7. Produktions-Deployment: Reverse-Proxy/Server so einrichten, dass beide Domains (hhonig.de, place4bees.com) auf dieselbe Astro-Instanz zeigen (Host-Header muss unverändert durchgereicht werden) und 301-Redirect-Mapping für geänderte Alt-URLs erstellen.
  8. Redis-gestützte Event-Bus/Cache-Module für Produktionsbetrieb ergänzen (aktuell nutzt Medusa lokal In-Memory-Fallback).
  9. Rechtstexte von einer Anwältin/einem Anwalt prüfen lassen (siehe eigener Abschnitt unten) – erst danach den gelben Entwurf-Hinweis auf den 4 Rechtsseiten entfernen und live schalten.
  10. Passwort-vergessen-Flow für Kundenkonten ergänzen – erledigt (26.10.2026): /konto/passwort-vergessen und /konto/passwort-neu, dazu die Bestätigung der Mailadresse, nach der Gastbestellungen ins Konto übernommen werden.
  11. Echte Produktfotos für Presshonig, Kornblumenhonig und Geschenkgutschein ergänzen (aktuell Platzhalter im Shop, da für diese 3 Produkte bei der Migration kein Bild übernommen wurde).
S
Description
No description provided
Readme 240 MiB
Languages
TypeScript 58.1%
Astro 33.2%
CSS 4.2%
HTML 3.5%
Shell 0.6%
Other 0.4%