einfach-produktiv/README.md

# einfach-produktiv — Frontend

Next.js frontend for [einfach-produktiv.mk360.de](https://einfach-produktiv.mk360.de),
Coolify-managed and deployed from this repo (`git.mk360.de/Marco/einfach-produktiv`).
For the VPS-wide infrastructure this app runs on (Caddy, Coolify, Gitea, the
shared Payload instance), see `~/dev/README.md` — this file only covers what's
specific to this project.

## Stack

- **Next.js 16.2.9** (App Router, `output: "standalone"` for a small Docker
  image — see `AGENTS.md` before touching anything version-specific, this
  Next.js release differs from older training-data conventions)
- **React 19.2.4**, **Tailwind CSS 4**, **Motion** for animation
- No local database — all editable content (and now orders/customer
  accounts) lives in the shared Payload CMS at `payload.mk360.de` (see
  below). Customer auth is Payload's own (a second, separate `auth: true`
  collection there, `customers` — not this app's own user store), bridged
  via an httpOnly session cookie this app mints itself; see "Orders &
  customer accounts" below.

## Getting started

```bash
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). `npm run build && npm run
start` reproduces the production build locally — do this before pushing,
since Coolify builds with `--no-cache` and a failed build only surfaces there
otherwise.

**Environment variables:** `PAYLOAD_URL` (defaults to `https://payload.mk360.de`
if unset, see `app/lib/payload.ts`). `PAYLOAD_PREVIEW_SECRET` (no safe
default — required for Live Preview, see below; must match the value set on
the Payload backend). `NEXT_PUBLIC_PAYLOAD_URL` (optional, defaults to the
same `https://payload.mk360.de` — only needed if the client-side Live
Preview components should ever point somewhere else). `DISCOUNT_SERVICE_SECRET`
(no safe default — required for discount codes to validate/redeem at all;
must match the value set on the Payload backend). `ORDER_SERVICE_SECRET`
(no safe default — required for `/api/checkout` to persist an order in
Payload at all, and for `/api/account/verify-email` to look up a customer
by their verification token; must match the value set on the Payload
backend — also used there for the same header). `SMTP_USER`/`SMTP_PASSWORD`
(no safe default — required for `app/lib/alertAdmin.ts`'s critical-failure
alerts and resend-verification emails; **does not** need to match anything
on the Payload side — this app's SMTP connection is deliberately
independent, see the "Monitoring & alerting" section). Set in Coolify's
app settings for production, not in a committed `.env`.

## Pages

| Route | Purpose |
|---|---|
| `/` | Home — hero, product spotlight, tools grid, trust row |
| `/shop` | Product grid (all active products for this tenant) |
| `/blog`, `/blog/[slug]` | Blog overview + post detail |
| `/cart` | Cart (localStorage-backed, see below) |
| `/checkout` | Shipping + payment method selection, order summary |
| `/bestellbestaetigung` | Order confirmation — reads the one-time snapshot `/checkout` wrote |
| `/konto/login` | Customer login |
| `/konto/bestellungen`, `/konto/bestellungen/[orderNumber]` | Order history + order detail (own orders only) |
| `/konto/profil` | Profile/address editing + password change |
| `/challenge` | "Mini-Challenge" tool |
| `/todo-cards` | "Todo-Karten" tool |
| `/newsletter` | Newsletter signup |
| `/versand` | Shipping policy (timeframes, costs) |
| `/impressum`, `/datenschutz`, `/agb`, `/widerruf` | Legal pages (from Payload, see `legal-pages` below) |

## Content backend: Payload CMS

This app is one **tenant** in a shared, multi-tenant Payload instance also
used by other projects on the same VPS (see `docker/payload/` in the infra
repo). All content queries go through `app/lib/payload.ts`, which hardcodes
`TENANT_SLUG = "einfach-produktiv"` and filters every request with
`where[tenant.slug][equals]=einfach-produktiv` — the tenant field itself is
injected automatically into every collection below by Payload's
`multiTenantPlugin`, not defined in this app.

`/api/products` is this app's own same-origin proxy route (`app/api/products/route.ts`)
in front of `getProducts()` — used by client components (cart, related
products) that need the catalog reactively, so they don't talk to Payload's
API directly and reuse Next.js's fetch cache instead of an extra round trip.

### Collections used by this tenant

All reads are public (`access.read: () => true`) **except `discount-codes`**
(see its own row below); writes are admin-gated in the Payload admin UI at
`payload.mk360.de/admin`.

| Collection (slug) | Used for | Key fields |
|---|---|---|
| `products` | `/shop` grid, homepage spotlight, cart, checkout | `name`, `slug` (cart item id — **not** Payload's numeric id, so existing localStorage carts survive catalog changes), `description`, `price`, `compareAtPrice` (optional strikethrough), `image`, `detailHref`, `sortOrder`, `active` (hides a product from the shop grid/spotlight/related-products only — cart/checkout/its own detail page still resolve it regardless, see Discount codes section below for the same opt-in-filtering principle), `spotlight` + `spotlightEyebrow`/`spotlightHeadline`/`spotlightText`/`spotlightImage` (homepage "Neu im Shop" section — falls back to `image` if no dedicated spotlight image is set; forced onto the sole active product when exactly 1 exists, see `getSpotlightProduct()`) |
| `discount-codes` | Cart discount input (`/cart`, display-only on `/checkout`) | `code`, `type` (`percent`/`fixed`), `value`, `validFrom`/`validUntil`, `minOrderValue`, `maxRedemptions`, `redemptionCount` (server-incremented only), `active`. **Not public-read** — see Discount codes section below |
| `posts` | `/blog`, `/blog/[slug]` | `title`, `slug`, `category` (relation to `categories`), `excerpt`, `thumbnail`, `content` (richText), `readTime` (auto-calculated on save from word count), `featured` (shown as the `/blog` hero post; most-recently-published wins if several are marked), `publishedAt`, `quoteLabel` (label + icon + underline shown next to every blockquote in `content`, default `"Merke dir:"` — leave empty to hide that framing, the blockquote text itself still renders), `relatedProduct` (optional relation to `products`, powers the "Passend dazu" card at the end of the post — leave empty to hide that card, or empty if the linked product has no `detailHref`) |
| `categories` | Blog post categorization | `name`, `slug` (unique per tenant, not globally) |
| `legal-pages` | `/impressum`, `/datenschutz`, `/agb`, `/widerruf` | `type` (`impressum`/`datenschutz`/`agb`/`widerruf`, one doc per type per tenant), `title`, `content` (richText), `attachment` (optional file, e.g. the Muster-Widerrufsformular PDF) |
| `trust-badges` | Horizontal "Schneller Versand / Versandkostenfrei / Mit Liebe verpackt" row — shown on `/shop`, `/cart`, `/checkout`, `/widerruf`, `/agb`, 404 | `title`, `description` (supports `{{lieferzeit}}`/`{{kostenfreiab}}` placeholders, resolved by the frontend from `shipping-settings`/`shipping-methods` at render time — not by Payload itself), `icon`, `sortOrder` |
| `cart-trust-badges` | Sidebar bullets on `/cart` (title only) and `/checkout` (title + description) — deliberately a separate collection from `trust-badges` so the two pages can't drift into showing different claims | `title`, `description`, `icon`, `sortOrder` |
| `shipping-methods` | `/checkout` shipping selection | `title` (no day-range in the title text — that lives in `shipping-settings` now, keeping both in one title used to drift), `description`, `price`, `freeShippingThreshold` (per-method, optional — leave empty for a method that should never be free, e.g. Express), `active` (inactive methods are hidden, not shown disabled), `sortOrder` |
| `shipping-settings` | Delivery-time disclosure shown on `/shop`, homepage spotlight, ToDo-Karten, `/cart`, `/checkout`, `/versand` (Art. 246a §1 Abs.1 Nr.8 EGBGB requires this visible before checkout) | `handlingDaysMin`/`handlingDaysMax` (processing time before it ships), `transitDaysMin`/`transitDaysMax` (carrier time) — the app derives the combined total itself. One row per tenant. |
| `payment-methods` | `/checkout` payment selection | `title`, `icons` (array — e.g. 3 logos for "Kreditkarte"), `active`, `sortOrder` |
| `werkzeuge-cards` | Homepage "Meine Werkzeuge" 3-card grid | `title`, `description`, `icon`, `ctaLabel`, `ctaHref`, `sortOrder` |
| `testimonials` | Customer testimonial grids on `/todo-cards`, `/newsletter`, `/challenge` | `quote`, `name`, `role`, `avatar`, `page` (`todo-cards`/`newsletter`/`challenge` — which page's grid this appears in), `sortOrder`. The single-quote "photo band" testimonials on `/not-found` and `/bestellbestaetigung` are a different shape (no avatar/role) and stay hardcoded, not part of this collection. |
| `media` | Shared upload collection backing every `image`/`icon`/`thumbnail`/`attachment` field above | `alt` (required for images), `title` (optional display name for download links) |

All of the above (except `media`, `users`, `tenants`) are grouped in the
Payload admin sidebar under **Commerce** (`products`, `discount-codes`,
`shipping-methods`, `shipping-settings`, `payment-methods`, `trust-badges`,
`cart-trust-badges`) or **Content** (`posts`, `categories`, `legal-pages`,
`werkzeuge-cards`, `testimonials`); `media`/`users`/`tenants` sit under
**Platform** — `users` and `tenants` are hidden from non-super-admins' nav
entirely, and every tenant-scoped collection's own "assigned tenant" field
is hidden from non-super-admins in the edit view (though not yet the list
view's column — see the infra README's Payload CMS section for why that
one's a harder fix).

Editorial changes (prices, copy, images, toggling a shipping/payment method
on or off) all happen in the Payload admin UI — no code deploy needed. Adding
a *new field* to any collection above requires editing the collection file in
`docker/payload/src/collections/` and a migration, which does need a deploy
of the Payload service.

### Live Preview

`posts`, `legal-pages`, and `testimonials` support Payload's Live Preview —
opening a document in the Payload admin shows this app's real rendered page
in an iframe, updating as you type, no save required.

- **`app/api/preview/route.ts`** — validates `PAYLOAD_PREVIEW_SECRET`
  (matching value required on the Payload side too, or this route 401s) and
  a `path`, enables Next.js Draft Mode, then redirects into the real page.
  This is the link Payload's `livePreview.url` resolvers point at (see
  `docker/payload/src/lib/previewUrl.ts` in the infra repo) — never the page
  directly.
- Each supported page checks `draftMode().isEnabled` and renders a
  `"use client"` Live-Preview-aware component instead of the plain static
  one only when it's `true` — ordinary visitors are never in Draft Mode, so
  they always get the plain version with zero extra client JS:
  - `app/components/LiveRichText.tsx` — the 4 legal pages' body content
    (their headings/sidebars are hardcoded per page, not CMS-sourced, so
    `content` is the only field worth live-previewing there)
  - `app/blog/[slug]/components/LivePostContent.tsx` — title/excerpt/
    thumbnail/body of a blog post (the author bio card, "Weiterlesen" card,
    and Footer stay static — they either aren't post-specific or are about
    a *different* post, not the one open in the admin)
  - `app/components/LiveTestimonialsGrid.tsx` — the one testimonial
    currently open in the admin, merged by `id` into the rest of that
    page's already-fetched grid (Live Preview is inherently single-document,
    but this page renders several at once)
- All three use `@payloadcms/live-preview-react`'s `useLivePreview` hook and
  reuse the same mapping functions (`mapPayloadPost`, `mapPayloadTestimonial`,
  exported from `app/lib/payload.ts`) the plain server-side fetchers use, so
  the two code paths can't silently drift apart.
- `app/lib/payload.ts` deliberately never imports `next/headers` itself —
  callers (the Server Component pages) call `draftMode()` themselves and
  pass the result in as a plain `{ draft: boolean }` option. Importing
  `next/headers` anywhere in that module breaks the production build the
  moment a `"use client"` component (which also needs this file's mapping
  functions/types) tries to bundle it — a real RSC-boundary regression hit
  once already when adding this feature.

## Discount codes

Applied in `/cart` only (`/checkout` displays the already-applied result,
no second input) — real server-side validation, not just a client-side
check against Payload's public API, unlike most content on this site.

- **`app/lib/discountServer.ts`** (server-only, imported exclusively by the
  two route handlers below — never by a `"use client"` component, same
  reasoning as Live Preview's `next/headers` lesson above) talks to
  Payload's `discount-codes` collection using an `x-discount-service-secret`
  header (`DISCOUNT_SERVICE_SECRET`), since that collection isn't
  public-read.
- **`app/api/discount/validate/route.ts`** — read-only check (active /
  validity window / minimum order value / remaining redemptions), called
  when a shopper clicks "Anwenden" in the cart.
- **`app/api/discount/redeem/route.ts`** — re-validates, then increments
  the collection's `redemptionCount`. Called exactly once, from
  `CheckoutContent.tsx`'s `handlePurchase()`, right before the
  `OrderSnapshot` is written — a code that expired or hit its redemption
  cap between being applied in the cart and the actual purchase click
  fails the purchase with an inline error instead of silently completing.
- **`app/lib/discount.ts`** mirrors `lib/cart.ts`'s exact `localStorage` +
  `useSyncExternalStore` pattern, so the applied code survives the
  `/cart` → `/checkout` navigation the same way the cart itself does.
- **`app/lib/cartTotals.ts`** — `computeSubtotal()`/`computeCartTotals()`,
  factored out of what used to be independently-duplicated subtotal/
  savings/total math in `CartContent.tsx`, `CheckoutContent.tsx`, and
  `BestellbestaetigungContent.tsx`; now also folds in the discount amount
  (clamped so a total can never go negative). `OrderSnapshot` persists the
  applied `discountCode`/`discountAmount` so the confirmation page shows
  what actually happened, not a fresh re-derivation.
- Known, accepted limitation: the redeem route's read-then-increment isn't
  atomic against a true concurrent race on a capped code's very last
  redemption — not worth custom atomic SQL at this shop's traffic level.

## Cart & checkout

- **Cart** (`app/lib/cart.ts`) is entirely client-side, stored in
  `localStorage` under `ep_cart`, keyed by each product's `slug`. Still the
  source of truth while browsing — the server-side mirror (see below) only
  exists to carry a logged-in customer's cart across devices/browsers.
- **`app/cart/components/RelatedProducts.tsx`** only ever suggests products
  not already in the cart — it stopped falling back to re-suggesting an
  already-in-cart product just to pad the grid out to 3 cards, so with a
  small catalog it can render fewer cards (down to 1, centered in the
  12-column grid) rather than recommending something already added.
- **`/checkout`'s "Jetzt kaufen" always goes through
  `POST /api/checkout`.** That route re-prices the entire cart server-side
  from Payload's live product data (never trusts client-submitted prices),
  re-validates+redeems a discount code exactly once, registers a new
  account inline if nobody's logged in yet ("Konto Pflicht" — see below),
  and only then creates the order in Payload's `orders` collection via
  `app/lib/orderServer.ts`. `app/lib/order.ts`'s `OrderSnapshot` is still
  written to `sessionStorage` for `/bestellbestaetigung` to read once, but
  its `orderNumber`/`orderDateIso` now come back from that Payload create
  call, not generated client-side.
- Still not built: real payment processing (the checkout button is
  labelled "zahlungspflichtig" but nothing captures a payment) and a
  transactional confirmation email — see `project_backend_checkout_plan`
  in the assistant's own memory for what's deliberately deferred to a
  later stage.

## Orders & customer accounts

An account is required to buy — there is no guest checkout. Registration
happens inline in `/checkout`'s "1. Rechnungsadresse" card (a password
field appears there when nobody's logged in); returning customers can
instead expand a small "Schon Kundin? Einloggen" toggle in the same place
without leaving the page.

- **`app/lib/customerAuth.ts`** (server-only) is the single place that
  talks to Payload's `customers` collection — a second, fully separate
  `auth: true` collection from any admin login, existing purely for this
  storefront's own accounts. Payload issues a JWT on register/login; this
  app never relies on Payload's own auth cookie (different origin —
  `einfach-produktiv.mk360.de` vs `payload.mk360.de`) and instead mints its
  **own** httpOnly `ep_customer_token` cookie holding that JWT, forwarded
  as an `Authorization: JWT <token>` header on every subsequent Payload
  call.
- **`app/api/account/*`** — thin route handlers around `customerAuth.ts`:
  `register`, `login`, `logout`, `me`, `orders` (list), `profile`
  (GET/PATCH incl. the one saved default address), `password` (verifies
  the current password via a real login attempt before changing it,
  doesn't just trust the caller), `cart` (GET/POST, see below),
  `verify-email`, `resend-verification`, `delete`, `export` (see "Email
  verification" and "GDPR self-service" below), and
  `orders/[orderNumber]` (PATCH — cancel/return-request, see "Order
  cancellation & returns" below).
- **`/konto/bestellungen`** lists a customer's own orders;
  **`/konto/bestellungen/[orderNumber]`** shows one order's full detail
  (items, address, totals, `status`). `status` (`received` → `processing`
  → `shipped` → `delivered`, plus `cancelled`/`return_requested`/`returned`)
  is maintained by hand in the Payload admin for the shipping states — no
  shipping-carrier API integration.
- **`/konto/profil`** edits name + the one saved default address (deliberately
  a single address, not a full address book — see the assistant's memory
  note on optionally expanding this later), changes the password, shows
  the email-verification banner, and has the GDPR export/delete section.
- **Cart sync**: `app/components/CartSync.tsx` (mounted once in
  `app/layout.tsx`) watches the local cart via `useCart()` and
  debounce-POSTs it to `/api/account/cart` on every change; the route
  401s (silently, by design) when nobody's logged in. On login
  (`LoginForm.tsx`, and `CheckoutContent.tsx`'s inline toggle),
  `mergeServerCartIntoLocal()` (`app/lib/cart.ts`) folds whatever was
  saved server-side into the local cart by quantity — CartSync's own
  effect then pushes the merged result back up on its own, so there's no
  separate explicit "save after merge" call.
- Still out of scope: a full address book (single default address only —
  see the assistant's memory note), single-currency.

### Rate limiting

`app/lib/rateLimit.ts` — an in-memory, per-IP sliding-window limiter
(`checkRateLimit(key, {limit, windowMs})`), deliberately no Redis: this
app runs as a single Coolify container, so a plain `Map` is enough and
needs no new infra. Resets on redeploy/restart — acceptable at this
shop's traffic level; revisit with a shared store if this ever scales to
multiple instances. Applied (keyed by `X-Forwarded-For`, which Caddy
already sets) to `/api/account/register`, `/api/account/login`,
`/api/account/password`, and `/api/account/resend-verification`.

This complements, not replaces, Payload's own **per-account** login
lockout (`customers.auth`, `maxLoginAttempts: 5` / `lockTime: 10min`,
Payload defaults — see the Payload README's "Login rate limiting"
section) — that stops brute-forcing one known email, this stops an IP
spraying attempts across many, or hammering registration.

### Session refresh

`proxy.ts` (project root — Next.js 16 renamed `middleware.ts` to
`proxy.ts`; see `node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/proxy.md`
if this ever looks wrong against older docs/training data). Runs on
`/checkout`, `/konto/*`, `/api/account/*`. Decodes (not verifies — Payload
verifies for real on every actual API call) the `ep_customer_token`
cookie's JWT `exp` claim; if less than 15 minutes remain, silently calls
Payload's built-in `POST /api/customers/refresh-token` and swaps in the
refreshed token. Net effect: an actively-browsing customer never gets
logged out mid-session, but someone who walks away is logged out within
~2h of their last request (Payload's `tokenExpiration` default, unchanged
on the Payload side).

### Email verification

Non-blocking by design — see the Payload README's `customers.emailVerified`
section for why this is a custom flag rather than Payload's built-in
`auth.verify: true` (short version: that would hard-block login for a
brand-new customer trying to finish the purchase they just registered
mid-checkout for). The initial email is sent by Payload itself (an
`afterChange` hook on `customers`, fires on create). `/konto/profil`'s
`VerificationBanner.tsx` shows a non-blocking "bitte bestätigen" hint with
a resend link when `!profile.emailVerified`; resending
(`/api/account/resend-verification`) is sent directly from this app
instead (`app/lib/alertAdmin.ts`'s `sendVerificationEmail()` — same
Hostinger SMTP, no Payload hook to piggyback on for a plain field update).

### GDPR self-service

`/konto/profil`'s "Konto & Daten" section:
- **Export** (`/api/account/export`, GET) — profile + every order's full
  detail as one downloadable JSON (`Content-Disposition: attachment`).
  Genuinely complete, not a summary — Art. 20 data portability.
- **Delete** (`/api/account/delete`, POST, password re-verified via a real
  login attempt first) — deletes the `customers` document. Past orders
  are **not** touched: `orders.customer` is `ON DELETE SET NULL` in
  Payload, so an order keeps its own name/address/items snapshot (already
  stored independently for exactly this kind of reason) for tax-retention
  purposes (§147 AO / GDPR Art. 17(3)(b) explicitly permits this) — only
  the account/login itself disappears. The UI says this explicitly before
  deleting, not as a surprise afterward.

### Order cancellation & returns

`/konto/bestellungen/[orderNumber]` shows one self-service button when
applicable: "Bestellung stornieren" while `status === 'received'`, or
"Rücksendung anfragen" while `status` is `'shipped'` or `'delivered'`
(`customerOrderAction()` in `customerAuth.ts` decides which, if any).
Posts to `/api/account/orders/[orderNumber]` (PATCH), which re-checks the
transition is still valid (friendlier error than a bare 403 if it's gone
stale — two tabs open, order shipped in the meantime) before calling
`requestOrderStatusChange()`.

**The real security boundary is in Payload**, not here: `orders.access.update`
already scoped a customer's JWT to their own order, but with no
field-level restriction — before this stage, a logged-in customer could in
principle PATCH *any* field of their own order (`total`, `items`,
anything), just because nothing in the frontend had ever exercised that
path yet. `Orders.ts`'s `beforeChange` hook now rejects a
customer-authenticated update unless the only changed field is `status`,
via an allowed transition. See the Payload README's own writeup for the
full detail.

No hard 14-day return-window check in code (no separately tracked delivery
date exists yet) — relies on the existing `/widerruf` legal text plus
manual admin review. No automatic refund (no payment provider exists yet)
— a return/cancellation request is just captured structurally instead of
arriving by email/phone; the admin still processes it by hand in the
Payload admin.

### Monitoring & alerting

Base uptime (is the site/Payload reachable at all) is already covered by
existing Uptime Kuma HTTP monitors with email alerting (`monitor.mk360.de`
— see `~/dev/README.md`'s Kuma section) and isn't part of this app. What's
new here is the one failure mode Kuma structurally can't see: the site is
up, a customer completes checkout, and the order still doesn't get
persisted (`createOrder()` returns `null` in `/api/checkout/route.ts`).
That path calls `app/lib/alertAdmin.ts`'s `sendCriticalAlert()` — its own,
independent SMTP connection (same Hostinger account, but **not** routed
through Payload, since Payload being the actual problem is one of the
scenarios this needs to still report on). Fire-and-forget, its own
try/catch, never blocks or fails the actual error response the customer
sees.

`/api/health` (GET) — checks Payload's public API is actually reachable
(3s timeout), not just that this page rendered; added as a Kuma HTTP
monitor in the existing "Content & API" group (`~/dev/README.md`'s
documented `sqlite3`-insert method, Kuma 1.x has no REST API for this).

## Deployment

- **Dockerfile**: 3-stage build (`deps` → `builder` → `runner`) with
  BuildKit cache mounts, producing a ~100 MB standalone image. This is the
  reference `Dockerfile` copied when scaffolding new projects on this VPS
  (see the infra repo's new-project workflow).
- Deploys via `git push` → Gitea webhook → Caddy `/deploy/einfach-produktiv`
  bridge → Coolify API → rebuild + restart. Full mechanics in
  `~/dev/README.md`.

## Related design source

- `~/dev/einfach-produktiv/mockups/` — Figma-stage mockup PNGs
- `~/dev/einfach-produktiv/styleguide.md` — design tokens (colors, type, spacing)
- `~/dev/einfach-produktiv/einfachproduktiv_figma_prompt_guide_v3.md` — Figma rebuild prompt guide