wahnsinn

base.md

@@ -0,0 +1,97 @@
+# 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. `llama3.1` für Chat, `nomic-embed-text` 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.