shop/base.md

Shopsystem — Vision (base)

Projektziel

Erweiterbares E-Commerce Shopsystem (B2C + B2B), weltweit einsetzbar, als verkaufbares Produkt. Dritt-Entwickler können eigene Apps bauen und verteilen (Marketplace-Konzept).

Architektur-Prinzip

App-basiert mit einem minimalen Core (Framework) und darauf aufbauenden Apps.

• Core (Framework) — das Minimum, damit überhaupt etwas läuft: Auth, API-Router, App-Loader, Event-Bus, DI-Container, Migrations-Runner, Settings-Verwaltung, User-Management.
• Core-Apps — das Minimum, damit ein Shop Sinn ergibt und funktioniert (z.B. Produkte, Kategorien, Warenkorb, Checkout, Bestellungen, Zahlung, Versand, Mail, Admin-UI, KI-Chat).
• Optionale Apps — Features, ohne die der Shop trotzdem funktioniert (z.B. Wunschliste, Bewertungen, Gutscheine).
• Dritt-Apps — gleiche Mechanik wie optionale Apps, nur von externen Entwicklern.

Jede App bringt mit: Manifest (Abhängigkeiten, Konflikte, Pflicht/Optional), eigene Migrationen, API-Endpunkte, Frontend-Komponenten, Events, Übersetzungen.

Kommunikation zwischen Apps: Events (lose Kopplung) + Dependency Injection (keine direkten Imports).

Tech-Stack

• Backend: Python + FastAPI (Tooling: uv, ruff, pytest)
• Datenbank: PostgreSQL (Write-Store) + Redis (Read-Store)
• Frontend: Vue 3 + Vite + TypeScript + Pinia + Vue Router (Tooling: pnpm, eslint, prettier, vitest) — nur Web, responsives Design für Mobile. Zwei getrennte Vue-Apps mit eigenem Build: shop (Kundensicht) und admin.
• KI: Lokale KI via Ollama (Standard-Modelle z.B. qwen2.5:7b für Chat, bge-m3 für Embeddings), RAG über Shop-/Produkt-/Einstellungs-Daten. Per Abstraktion austauschbar.
• Auth: JWT (Access + Refresh), Passwort-Hashing via argon2
• Migrationen: Alembic (SQLAlchemy)
• Suche: austauschbar per Such-Abstraktion (Standard Meilisearch)
• i18n: DE + EN initial, weitere Sprachen nachladbar
• Deployment (Dev): docker-compose mit Postgres, Redis, Meilisearch, Ollama

Datenfluss

• PostgreSQL ist Quelle der Wahrheit (alle Schreiboperationen).
• Redis ist die Lese-Schicht — das Frontend liest nur aus Redis.
• Sync: Sofort-Aktualisierung bei Änderungen + Scheduler als Sicherheitsnetz.
• Frontend sieht die DB-Komplexität nie, nur schnelle Reads.

Kundensicht (Shop-Frontend)

Bewusst simpel gehalten:

• Account mit Bestellungen und persönlichen Daten
• Produkt-Browsing über Kategorien
• KI-Helfer (verbunden mit lokaler KI + RAG): natürliche Anfragen wie "ich suche einen grünen Pulli" → KI filtert/sortiert angezeigte Produkte entsprechend
• Warenkorb + Bestellprozess (Klasse = ordentlicher Checkout-Flow)
• Bestätigungs-Mail nach der Bestellung

Admin-Sicht

Klassisches Admin: Produkte, Kategorien, Bestellungen, Einstellungen, Apps verwalten.

Zusätzlich KI-Chatbox auf der Startseite:

• Befehle in natürlicher Sprache: "setze den Shopnamen auf TEST123" → KI erzeugt Vorschlags-Card mit geplanter Änderung → Admin bestätigt → Ausführung.
• JSON-Bulk-Input: Admin wirft JSON in den Chat ("das sind neue Produkte, erstelle sie") → KI erzeugt mehrere Cards (eine pro Anweisung) → Fehlende Felder sind in der Card editierbar → Admin bestätigt (einzeln oder alle) → Ausführung.

Jede Aktion der KI ist immer erst Vorschlag, nie direkte Ausführung.

Betriebsmodell

Single-Shop pro Instanz (kein Multi-Tenant). Wer mehrere Shops betreiben will, deployed mehrere Instanzen. Vereinfacht Schema, Caching und RLS erheblich.

Umgebungen

APP_ENV=dev|staging|production steuert Verhalten:

• dev: Seed-Daten, Mock-Services, Hot-Reload, Debug-Logging
• staging: Stripe Testmodus, Catch-All E-Mails
• production: echte Zahlungen, Caching aktiv

Domänen-Skizze (hoch-level)

Minimale Entitäten, die der Core bzw. Core-Apps mitbringen:

• User (Kunde, Admin, Firma für B2B)
• Product + Category
• Cart + CartItem
• Order + OrderItem + OrderStatus
• Payment + Shipment
• Setting (Key-Value, pro App-Namespace)
• App (installierte Apps inkl. Version, Status)
• Event (persistierte Domain-Events für Audit/Replay)

Abgrenzung — was ist nicht Core

• Wunschliste, Bewertungen, Rabatt-/Gutschein-Engine, Produktempfehlungen, Multi-Vendor, Abo-Modelle — alles optionale Apps.

Bezug zur Analyse

Details zu Feature-Prioritäten (Pflicht/Soll/Kann), B2B-Anforderungen, i18n, Sicherheit und Phasenplan: siehe shopsystem-analyse.pdf (34 Seiten). Die Analyse bleibt unverändert; diese Datei ist die aktuelle Arbeits-Vision.