# 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 `` fest auf `https://place4bees.com/` (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/` gehen auf `/shop/`, 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`](https://www.npmjs.com/package/@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](https://developer.paypal.com/dashboard/) 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 ```bash # 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:** ```bash 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: ""}`). 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 `
` mit einem absolut positionierten, die ganze Karte überspannenden `` („stretched link") plus dem Quick-Add-`