# 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.