huge documentaton restructure for docusaurus

docs/process/changes/2025-09-08-session.md

@@ -0,0 +1,16 @@
+# Session Changes — 2025-09-08
+
+Summary
+- Split PRP into docs/prp/* and added addendum + ADR for Tenant Admin PWA.
+- Guest PWA: routes/components scaffold, bottom nav, header + settings sheet, theme toggle; polling hooks; upload (client compress <1.5 MB), offline queue + BG sync; gallery filters + lightbox; likes API/UI; SW runtime cache.
+- Super Admin (Filament 4): resources for Tenants, Events, Photos, Legal Pages; dashboard widgets; photo moderation; event toggle; join link + self‑hosted QR.
+- CSV imports + templates for Emotions and Tasks with de/en localization; forms updated to JSON casts.
+- Backend public API: stats/photos with ETag/304; upload endpoint; photo like.
+- Tenant Admin PWA: auth shell (token), events list/create/edit, event detail (stats, QR, invite), photo moderation.
+- Migrations: tenants table; users.tenant_id/role; events.tenant_id; model casts/relations added.
+- Artisan: media:backfill-thumbnails; tenant:add-dummy; tenant:attach-demo-event.
+
+Notes
+- Security hardening intentionally minimal per instruction (token login for tenant admin).
+- QR codes generated server-side via simple-qrcode.
+- No secrets committed. Local gogs.ini used only for pushing to Gogs.

docs/process/changes/2025-10-02-registration-role-fixes.md

@@ -0,0 +1,40 @@
+# Registrierungs-Fixes: Redirect, Error-Clearing und Role-Handling (2025-10-02)
+
+## Problem-Beschreibung
+- **Redirect-Fehler**: Bei erfolgreicher Registrierung (free oder paid Package) wurde onSuccess in Register.tsx ausgelöst, aber kein Redirect zu /dashboard oder /buy-packages/\{id\} erfolgte. Ursache: Backend Inertia::location (302) wurde von Inertia mit preserveState: true ignoriert, da SPA-State erhalten blieb.
+- **Persistente Errors**: Server-Errors (z.B. invalid email) verschwanden nicht bei Korrektur-Input; nur Passwort-Match hatte client-side Clear.
+- **Role-Assignment**: Default 'user' für new Users; Upgrade zu 'tenant_admin' bei free Package (sofort im Controller), paid (nach Webhook-Payment).
+- **Weitere Bugs**: Tenant::create 'name' falsch ($request->name statt first+last_name); Linter/TS Errors (Return-Types, router.visit unknown).
+
+## Fixes
+### Backend (MarketingRegisterController.php)
+- **JSON-Response für Redirect**: Ersetzt Inertia::location durch response()->json(['success' => true, 'redirect' => $url]) für free (Zeile 141) und paid (Zeile 133). Kompatibel mit Inertia onSuccess (page.props.success/redirect prüfen).
+- **Tenant Name Fix**: 'name' => $request->first_name . ' ' . $request->last_name (Zeile 71); slug entsprechend angepasst.
+- **Role-Logic**: 'role' => 'user' in User::create (Zeile 66); für free: Update zu 'tenant_admin' nach TenantPackage::create (Zeile 129), Re-Login (Zeile 130). Für paid: Kein Upgrade bis Webhook (Paddle).
+- **Return-Type**: store() zu JsonResponse (Zeile 44); use JsonResponse hinzugefügt (Zeile 22).
+
+### Frontend (Register.tsx)
+- **onSuccess-Handling**: Prüfe page.props.success && router.visit(page.props.redirect as string) (Zeile 66-68); Fallback zu data.package_id ? `` `/buy-packages/\${data.package_id}` `` : '/dashboard' (Zeile 71-75); console.log für Debug (Zeile 67, 74).
+- **Error-Clearing**: Erweitert onChange für alle Inputs (first_name Zeile 123, last_name 148, email 173, address 198, phone 223, username 248): if (e.target.value.trim() && errors[field]) setError(field, ''); für privacy_consent (Zeile 325): if (checked) setError('privacy_consent', ''); Passwort behält Match-Check (Zeile 277, 305).
+- **General Errors Key**: nutze `<div key={"general-errors-" + Object.keys(errors).join('-')}>` (Zeile 347) für Re-Render bei Error-Änderungen.
+
+### Tests (RegistrationTest.php)
+- **JSON-Asserts**: assertJsonStructure(['success', 'redirect']) und assertJson(['success' => true]) in test_registration_creates_user_and_tenant (Zeile 37-39) und test_registration_without_package (Zeile 78-80).
+- **Neuer Test**: test_registration_with_paid_package_returns_json_redirect (Zeile 132): assertStringContainsString('buy-packages', redirect); role 'user' (kein Upgrade).
+- **Validation/Email**: Unverändert, assertSessionHasErrors (Zeile 107).
+
+## Verification
+- **Backend**: php artisan test --filter RegistrationTest; prüfe JSON-Response in Browser-Network-Tab (POST /register -> 200 JSON).
+- **Frontend**: Registrierung mit free: Redirect zu /verification.notice; paid: zu /buy-packages/10; Errors clear bei Input (z.B. invalid email -> input valid -> error gone).
+- **Role**: DB-Check: free -> 'tenant_admin', paid -> 'user' (Upgrade via Webhook).
+- **Linter/TS**: Keine Errors; Intelephense fixed durch JsonResponse use und as string cast.
+
+## PRP-Update (docs/prp/13-backend-authentication.md)
+- Hinzugefügt: Section "Role Flow in Registration": Default 'user'; Upgrade 'tenant_admin' bei free Package (Controller); paid via Webhook (Stripe invoice.paid, Paddle IPN); JSON-Success für Inertia-Forms (preserveState + onSuccess visit).
+
+## Best Practices
+- Inertia-Forms: Bei preserveState JSON-Response für custom Redirects verwenden, statt location() (vermeidet State-Ignorieren).
+- Error-Clearing: Client-side onChange clear für UX (non-empty Input); Keys für conditional Elements (Re-Render).
+- GDPR: Privacy-Consent required; no PII in Logs.
+
+Date: 2025-10-02

docs/process/changes/2025-10-05-checkout-refactor-todo.md

@@ -0,0 +1,39 @@
+# Checkout Refactor TODOs (2025-10-05)
+
+## Scope
+- Marketing checkout only; guest and admin PWAs stay untouched.
+- Replace existing marketing purchase wizard and supporting auth/payment endpoints.
+
+## Action Items
+
+### Wizard Foundations
+- [x] Rebuild the package step with a side panel for comparable packages and reset payment state when the selected package changes (see `resources/js/pages/marketing/checkout/steps/PackageStep.tsx`).
+- [x] Redesign the payment step: Stripe and Paddle happy path, failure, retry; add subscription handling for reseller plans. *(Stripe intent lifecycle + Paddle subscription flow now share status alerts, retry logic, and plan gating in `PaymentStep.tsx`.)*
+- [x] Update the confirmation step and surface the admin link inside `resources/js/pages/Profile/Index.tsx`. *(Handled via `ConfirmationStep.tsx` + wizard callbacks redirecting to `/settings/profile` and `/event-admin`.)*
+
+### Authentication & Profile Data
+- [x] Refactor `resources/js/pages/auth/LoginForm.tsx` and `RegisterForm.tsx` to hit the correct routes, surface inline validation errors, and provide success callbacks.
+- [x] Add optional comfort login: Google sign-in and enrichment of missing registration fields via the payment provider, combining the prior step 2/3 concept.
+
+### Backend Alignment
+- [x] Implement a dedicated `CheckoutController` plus marketing API routes, migrating any remaining checkout logic out of the marketing controller. *(Controller + routes now live in `app/Http/Controllers/CheckoutController.php` / `routes/web.php`.)*
+- [x] Audit existing marketing payment flows (`resources/js/pages/marketing/PurchaseWizard.tsx`, `PaymentForm.tsx`) and plan removals or migration. *(Legacy components removed; new wizard replaces them.)*
+
+### Quality & Rollout
+- [x] Expand automated coverage: Playwright end-to-end scenarios for auth, payment success/failure, Google login; PHPUnit and webhook tests for new checkout endpoints. *(Feature + unit suites cover Stripe intents, Paddle webhooks, Google comfort login; Playwright CTA smoke in place—full payment journey available behind the `checkout` tag.)*
+- [x] Update docs (PRP, docs/process/changes) and plan a feature-flag rollout for the new wizard.
+
+## Notes
+- Wizard auth now uses `/checkout/login` and `/checkout/register` JSON endpoints handled by `CheckoutController`.
+- Ensure payment step parity during migration so existing paid funnels do not regress prior to feature flag activation.
+- 2025-10-05: Checkout wizard skeleton created (`resources/js/pages/marketing/checkout/*`); awaiting payment/Auth wiring and backend API handoff.
+- 2025-10-05: Payment architecture blueprint authored in docs/prp/marketing-checkout-payment-architecture.md.
+- 2025-10-05: checkout_sessions migration + service scaffolding committed (app/Models/CheckoutSession.php, app/Services/Checkout/*, config/checkout.php).
+
+### Payment Integration Plan
+- [x] Define provider-agnostic payment state machine (intent creation, approval, capture, failure). See docs/prp/marketing-checkout-payment-architecture.md.
+- [x] Scaffold checkout_sessions migration + service layer per docs/prp/marketing-checkout-payment-architecture.md.
+- [x] Implement Stripe PaymentIntent endpoint returning `client_secret` scoped to wizard session. *(Covered by `CheckoutController::createPaymentIntent`.)*
+- [x] Implement Paddle order creation/capture endpoints with metadata for tenant/package. *(Routes now exposed in `routes/web.php`; controller derives tenant context for authenticated users.)*
+- [x] Add webhook handling matrix for Stripe invoice/payment events and Paddle subscription lifecycle.
+- [x] Wire payment step UI to new endpoints with optimistic and retry handling. *(See `PaymentStep.tsx` for Stripe intent loading + Paddle order/subscription creation and capture callbacks.)*

docs/process/changes/2025-10-09-paypal-sdk-migration.md

@@ -0,0 +1,22 @@
+# Paddle SDK Migration to v1 Server SDK
+
+## Summary
+Migrated from deprecated `paypal/paypal-checkout-sdk` to `paypal/paypal-server-sdk ^1.0+` in PaddleController.php. The new SDK uses a Builder pattern for requests and dedicated Controllers for API calls, based on OAuth2 Client Credentials.
+
+## Changes
+- **Composer**: Removed `paypal/paypal-checkout-sdk`; retained/updated `paypal/paypal-server-sdk`.
+- **Imports**: Replaced old classes (PaddleHttpClient, OrdersCreateRequest, etc.) with new (PaypalServerSdkClientBuilder, OrderRequestBuilder, OrdersController, etc.).
+- **Constructor**: Updated to use `PaypalServerSdkClientBuilder` with `ClientCredentialsAuthCredentialsBuilder` and Environment (Sandbox/Production based on config/services.php).
+- **createOrder**: Now uses `OrdersController->createOrder` with `OrderRequestBuilder` for intent, purchase units (AmountWithBreakdownBuilder), custom_id, and application_context.
+- **captureOrder**: Now uses `OrdersController->captureOrder`; extracts custom_id from response->result->purchaseUnits for DB creation (PackagePurchase/TenantPackage).
+- **createSubscription**: Now uses `SubscriptionsController->createSubscription` with `SubscriptionRequestBuilder` for plan_id, subscriber (NameBuilder), custom_id, and application_context.
+- **Tests**: Updated tests/Feature/PurchaseTest.php to mock new SDK classes (e.g., OrdersController, SubscriptionsController) and responses; preserved test logic for flows, errors, idempotency.
+- **Documentation**: Updated docs/prp/08-billing.md to reflect new SDK usage, flow, and migration notes.
+
+## Testing
+- Unit/Feature Tests: All Paddle-related tests pass with mocks simulating new API responses (statusCode 201, result structure).
+- Integration: Verified with Sandbox keys; simulated orders/subscriptions create DB entries correctly; error handling intact.
+- No Breaking Changes: Existing webhook logic and completePurchase calls unaffected; custom_id metadata preserved.
+
+## Rationale
+The old SDK is deprecated and not recommended by Paddle. The new v1 Server SDK aligns with modern standards, improves security (OAuth2), and supports future features. Migration maintains backward compatibility for frontend and DB logic.

docs/process/changes/2025-10-10-tenant-admin-onboarding-plan.md

@@ -0,0 +1,86 @@
+# Tenant Admin PWA — Onboarding + Management Fusion
+
+## Context
+- Goal: Merge the immersive onboarding / ordering flow from the legacy Capacitor app with the new `/event-admin` management experience inside Laravel.
+- Desired outcome: Tenants land in a polished, mobile-first “welcome” journey when they first log in, complete package purchase + event setup, then switch to the operational dashboard once active.
+
+## TODOs
+1. **Audit Legacy Assets**
+   - Inventory screens/components from `fotospiel-tenant-app/tenant-admin-app` worth porting (intro carousel, package picker, CTA cards, animations, themed styles).
+   - Document any dependencies (Framework7, custom icons, animation libs) and decide whether to port or recreate with our current Tailwind/React stack.
+
+2. **Bootstrap Welcome Route Namespace**
+   - Create `/event-admin/welcome/*` routes inside the Laravel tenant PWA.
+   - Establish shared layout primitives (full-height hero, gradient backgrounds, swipeable steps) to match native feel.
+
+3. **Port UI Steps**
+   - Recreate the storytelling sequence (Brand intro → How it works → Package selection → Order CTA → First-event setup).
+   - Hook actions into existing APIs (packages, checkout, event creation) and leverage current auth context.
+
+4. **Lifecycle Routing Logic**
+   - Add guard that directs tenants with no events / onboarding incomplete to the welcome flow after login.
+   - Provide quick access from dashboard back into the guided flow when creating additional events.
+
+5. **Capacitor/TWA Packaging Prep**
+   - Ensure the merged `/event-admin` build is PWA-complete (manifest, offline) for future store submission.
+   - Plan thin Capacitor wrapper reuse; retire the legacy repo after migration.
+
+6. **Documentation & Hand-off**
+   - Update PRP (tenant admin specs + onboarding) to reflect the unified experience.
+   - Record component inventory and routing rules so future agents can extend both modes consistently.
+
+## Component Audit — 2025-10-10
+
+### Legacy Welcome & Story Shell
+- **Hero experience**: `App.tsx` renders a premium hero card with eyebrow, script headline, and dual CTA buttons (`/create-event`, `/tutorial`) layered on a soft gradient background with Framework7 cards and brand fonts.
+- **Feature highlights**: A three-card grid introduces guest gallery, timeline/tasks, and invites; badges flag free or included items for unauthenticated vs. subscribed tenants.
+- **Quick actions**: Responsive button stack that shifts based on auth state (`demo event`, `tutorial`, `events`, `login`) providing an immediate action list after the hero.
+- **Credits strip**: `credits-card` combines balance chips, a RevenueCat-aware badge, and CTA to `/credits-store`; replicating this card gives tenants a quick read on package status.
+
+### Monetisation & Ordering
+- **IAP store** (`pages/IAPStorePage.tsx`): Uses `@revenuecat/purchases-capacitor` for offerings, purchase status banners, and analytics tracking; cards highlight price, credit count, and subscription state. Needs Paddle parity discussion before porting.
+- **Credits context** (`contexts/AuthContext.tsx`): Persists tokens and credit balances via Capacitor Preferences and refresh logic; emits helper APIs `purchasePackage`, `getCreditsBalance`.
+
+### Event Creation Wizard
+- **Multi-step flow** (`pages/CreateEventWizard.tsx`): Three validated steps (Basics, Event type & mood, Confirmation) with segmented chips, animated progress bar, and analytics events (`trackEvent`). Integrates `EventService` for API calls and includes next/back navigation with swipe gestures.
+- **Mood board**: Step includes card gallery, tags, and dynamic feature chips to capture desired vibes—helpful reference for onboarding's storytelling portion.
+
+### Theme & Visual System
+- **Design tokens** (`styles/tokens.css`): Brand palette, typography stack (Playfair Display, Montserrat, Lora, Great Vibes), spacing, radius, and shadow definitions exported as CSS variables.
+- **Framework7 overrides** (`styles/theme.css`, `styles/fonts.css`): Maps tokens onto Framework7 CSS variables to achieve native-feel bars, cards, and typography.
+- **Assets** (`src/assets/fonts/*`): Self-hosted font files referenced by tokens; need a Tailwind-friendly strategy (e.g., CSS `@font-face` via Vite) if we replicate the look.
+
+### Supporting Utilities
+- **Services**: `services/AuthService.ts`, `services/EventService.ts`, `services/analytics.ts` provide OAuth PKCE glue, event CRUD helpers, and event tracking (mixpanel-like contract).
+- **i18n** (`src/i18n`): React context-based i18next with `en`/`de` copies for all hero/wizard strings; reuse dictionary keys where possible during port to keep translations aligned.
+
+**Porting Recommendation**
+- Rebuild the hero, feature cards, quick actions, and wizard using Tailwind + shadcn components inside Laravel PWA while reusing copy/structure.
+- Lift design tokens into a Tailwind preset or CSS module so new welcome surfaces keep the premium typography without forcing Framework7 runtime.
+- Treat RevenueCat-specific logic as optional: plan abstraction so Paddle packages in Laravel can slot in later if we skip native IAPs initially.
+
+## Proposed Laravel PWA Welcome Primitives
+- **`TenantWelcomeLayout`**: Full-height, gradient-backed shell with centered content column, safe-area padding, and optional bottom action rail. Applies the legacy token palette via Tailwind CSS variables and toggles between light/dark.
+- **`WelcomeHero`**: Composable hero card exposing slots for eyebrow, headline, script subtitle, and dual CTA buttons. Ships with animation hooks (e.g., `framer-motion`/CSS fade) but degrades gracefully.
+- **`WelcomeStepCard`**: Step wrapper with built-in progress indicator, icon slot, and scroll snap. Intended for storytelling slides (`How it works`, `Why Fotospiel`) before handing off to form-based steps.
+- **`OnboardingCTAList`**: Responsive button group mirroring legacy quick actions; renders stacked buttons on mobile and inline actions on larger breakpoints. Consumes tenant/auth context to toggle copy.
+- **`OnboardingHighlightsGrid`**: Reusable grid for feature cards (icon, title, badge, copy) using existing shadcn `Card` primitives to reproduce the premium look without Framework7.
+- **`OnboardingProgressProvider`**: Lightweight Zustand or React context store that tracks completion state (welcome_seen, package_selected, event_created) for guards and resume logic.
+- **Theming bridge**: Introduce `tenant-admin.css` (or Tailwind preset) that re-exports critical tokens (`--tenant-primary`, serif display font) so the welcome experience and management dashboard share a palette while staying Tailwind-native.
+
+These primitives live under `resources/js/admin/onboarding/` and integrate with current router constants (`ADMIN_BASE_PATH`). They should support lazy-loading so existing dashboard bundle size remains manageable.
+
+## Progress
+- **Inline Checkout**: Die Order-Summary-Seite unterstützt jetzt Stripe-Kartenzahlungen (Payment Element) und Paddle (Orders API) direkt aus dem Onboarding heraus. Free-Packages lassen sich ohne Umweg aktivieren.
+- Dashboard bewirbt die Welcome Journey (Actions + Hero Card) und leitet Tenants ohne Events weiterhin auf `/event-admin/welcome` um, während Fortschritt persistiert wird.
+- Playwright-Skelett `tests/e2e/tenant-onboarding-flow.test.ts` angelegt und via `npm run test:e2e` ausführbar; Tests sind vorerst deaktiviert, bis Seed-Daten + Auth-Helper zur Verfügung stehen.
+- Welcome Landing, Packages, Summary und Event-Setup sind zweisprachig (DE/EN) via react-i18next; LanguageSwitcher im Dashboard & Welcome-Layout steuert die Locale.
+
+## Status — verbleibende Arbeiten
+- Paddle-Testabdeckung (Playwright/RTL) und Error-UX gehören noch in die Roadmap, ebenso wie End-to-End-Validierung auf Staging.
+
+## Notes
+- Keep current management modules untouched until welcome flow is ready; ship incrementally behind feature flag if needed.
+- Reuse new API helpers, QueryClient, and constants to avoid divergence between flows.
+
+

docs/process/changes/2025-11-08-coupon-ops.md

@@ -0,0 +1,12 @@
+# Coupon Ops Enhancements (2025-11-08)
+
+## Summary
+- Added `CouponRedemptionService` + Paddle webhook hooks so successful/failed redemptions are logged and counted.
+- Exposed `/api/v1/marketing/coupons/preview` with per-IP rate limiting, structured logging, and localized responses.
+- Marketing funnel + checkout wizard auto-prefill coupons from `?coupon=` links and persist selections through Paddle checkout.
+- Super Admin dashboard now shows a "Coupon performance (30d)" widget with recent usage + discount totals.
+- New artisan command `php artisan coupons:export` exports the last N days of redemptions to CSV for finance/reporting.
+
+## Follow-ups
+- Wire coupon analytics into the Matomo dashboard once new segments are defined.
+- Expand fraud tooling with IP/device reputation once we roll out the affiliate program.