wahnsinn

CLAUDE.md

@@ -13,12 +13,35 @@ Custom E-Commerce Shopsystem (B2C + B2B), weltweit einsetzbar, als verkaufbares
 
 ## Tech-Stack
 
-- **Backend**: Python + FastAPI
+- **Backend**: Python + FastAPI — Tooling: `uv`, `ruff`, `pytest`
 - **Datenbank**: PostgreSQL (Write-Store) + Redis (Read-Store)
-- **Frontend**: React (Next.js) + TypeScript
-- **Suche**: Meilisearch (Standard), austauschbar per Such-Abstraktion für Enterprise-Kunden
+- **Frontend**: Vue 3 + Vite + TypeScript + Pinia + Vue Router — Tooling: `pnpm`, `eslint`, `prettier`, `vitest`. Nur Web, responsives Design.
+  **Zwei getrennte Vue-Apps mit separatem Build:** `shop` und `admin`.
+- **Auth**: JWT (Access + Refresh), `argon2` für Passwort-Hashing
+- **KI**: Ollama (lokal) via RAG — Standard-Modelle `llama3.1` (Chat) + `nomic-embed-text` (Embeddings), per Abstraktion austauschbar
+- **Suche**: austauschbar per Such-Abstraktion (Standard Meilisearch)
 - **DB-Migrationen**: Alembic (SQLAlchemy)
-- **Jede App** bringt eigene Migrationen, API-Endpunkte und Frontend-Komponenten mit
+- **i18n**: DE + EN initial
+- **Dev-Infrastruktur**: `docker-compose` mit Postgres, Redis, Meilisearch, Ollama
+- **Jede App** bringt Manifest (`manifest.yaml`), Migrationen, API-Endpunkte, Frontend-Komponenten, Events und Übersetzungen mit
+
+## Betrieb
+
+- **Single-Shop pro Instanz** (kein Multi-Tenant). Mehrere Shops → mehrere Deployments.
+
+## Repo-Struktur
+
+```
+/backend        FastAPI-Core + App-Loader
+/frontend/shop  Vue-App Kundensicht
+/frontend/admin Vue-App Admin
+/apps           Core-Apps und optionale Apps als Python-Packages
+```
+
+## KI-Integration
+
+- **Shop-Seite**: KI-Helfer für natürlichsprachliche Produktsuche (RAG über Produkte/Kategorien).
+- **Admin-Seite**: KI-Chatbox auf der Startseite. Befehle und JSON-Bulk-Input werden als **Vorschlags-Cards** dargestellt. Fehlende Felder sind in der Card editierbar. Ausführung erst nach Bestätigung durch den Admin — KI führt nie direkt aus.
 
 ## Datenfluss
 

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.

module.md

@@ -0,0 +1,206 @@
+# Shopsystem — Module (Implementierungs-Schritte)
+
+Jedes Modul ist ein **end-to-end Feature** (Backend + Frontend + Tests + Migrationen + ggf. Doku gemeinsam). Module bauen aufeinander auf, können aber jeweils eigenständig gemerged werden.
+
+Format pro Modul:
+- **Ziel**: Was soll am Ende funktionieren
+- **Backend**: API-Endpunkte, Modelle, Migrationen, Events
+- **Frontend**: Welche App (shop/admin), welche Seiten/Komponenten
+- **Fertig wenn**: Akzeptanzkriterium — konkret und testbar
+
+---
+
+## Modul 0 — Projektgerüst
+
+**Ziel:** Monorepo steht, alle drei Apps (backend, frontend/shop, frontend/admin) starten lokal, Docker-Compose bringt Postgres/Redis/Meilisearch/Ollama hoch.
+
+**Backend:**
+- `pyproject.toml` mit `uv`, FastAPI, SQLAlchemy, Alembic, Redis-Client, pytest, ruff
+- Health-Endpunkt `GET /health` (Backend + DB + Redis ping)
+- `APP_ENV` + `.env.example`
+
+**Frontend:**
+- `frontend/shop` und `frontend/admin` via `pnpm create vue` mit TS, Pinia, Router, Vitest
+- Shared Package `frontend/shared` für API-Client, i18n-Keys, gemeinsame Typen
+- Jede App startet mit Platzhalter-Seite und zeigt Backend-Health-Status
+
+**Infra:**
+- `docker-compose.yml`: Postgres, Redis, Meilisearch, Ollama (mit Modell-Pull-Init)
+- `Makefile` oder `justfile` mit `dev`, `test`, `lint`, `migrate`
+
+**Fertig wenn:** `docker-compose up` + `make dev` → Browser zeigt grünen Health-Status auf `localhost:5173` (shop) und `localhost:5174` (admin).
+
+---
+
+## Modul 1 — Core-Framework
+
+**Ziel:** App-basiertes Laden funktioniert. Der Core kennt Apps, lädt deren Router/Migrationen/Events.
+
+**Backend:**
+- **App-Loader**: Entdeckt `apps/*/manifest.yaml`, prüft Abhängigkeiten/Konflikte, lädt Reihenfolge auf
+- **Manifest-Schema**: `name`, `version`, `depends_on`, `conflicts_with`, `provides`, `required`
+- **DI-Container** (minimal, z.B. via `punq` oder eigen): Services pro App registrierbar
+- **Event-Bus** (in-process für MVP, Interface offen für Broker): `publish(event)`, `subscribe(handler)`, persistierte `events`-Tabelle für Audit
+- **Settings-Service**: Key-Value-Store in Postgres, App-Namespace, Typisierung
+- **Redis-Projector-Interface**: Apps registrieren Projektoren, die bei Events Redis aktualisieren
+- Migrations-Runner: sammelt Alembic-Heads aus allen Apps
+
+**Frontend:**
+- Kein User-facing Code. Aber `frontend/shared` bekommt Typen für `Setting` + Event-Envelope.
+
+**Fertig wenn:**
+- Eine Dummy-App `apps/hello` mit leerer Route `/api/hello` lädt automatisch.
+- Setting `core.shop_name` lässt sich setzen und lesen (API).
+- Event beim Setting-Change landet in `events`-Tabelle und aktualisiert Redis-Key.
+
+---
+
+## Modul 2 — Auth & User
+
+**Ziel:** Registrierung, Login, Rollen (Kunde / Admin) funktionieren end-to-end in beiden Frontends.
+
+**Backend (`apps/auth`):**
+- Entitäten: `user` (id, email, password_hash, role, locale, created_at), `refresh_token`
+- Endpunkte: `POST /auth/register`, `POST /auth/login`, `POST /auth/refresh`, `POST /auth/logout`, `GET /auth/me`
+- JWT (Access 15 min, Refresh 30 Tage), `argon2` für Passwörter
+- Events: `user.registered`, `user.logged_in`
+- Seed: 1 Admin (`admin@example.com` / `admin`)
+
+**Frontend (shop + admin):**
+- Shop: Register/Login-Seite, Account-Seite (persönliche Daten ändern, Passwort ändern)
+- Admin: Login-Seite mit Rollen-Check (nur role=admin darf rein)
+- Pinia-Store `auth` + API-Interceptor für Access-Token-Refresh
+
+**Fertig wenn:** Kunde kann sich im Shop registrieren & einloggen. Admin kann sich im Admin-Frontend einloggen, Kunde wird dort abgewiesen.
+
+---
+
+## Modul 3 — Produkte & Kategorien
+
+**Ziel:** Admin pflegt Produkte + Kategorien, Shop zeigt sie.
+
+**Backend (`apps/catalog`):**
+- Entitäten: `product` (id, sku, name_i18n, description_i18n, price, currency, stock, active, images[], category_id), `category` (id, slug, name_i18n, parent_id)
+- Endpunkte: `GET /products`, `GET /products/{id}`, `GET /categories` (public, aus Redis)
+- Admin-Endpunkte: `POST/PUT/DELETE /admin/products`, dto. Kategorien
+- Events: `product.created/updated/deleted`, `category.*`
+- Redis-Projektor schreibt nach Events
+- Image-Upload (zunächst lokaler Storage, per Interface austauschbar)
+
+**Frontend Shop:**
+- Startseite mit Produktliste
+- Kategorieseite, Produktdetailseite
+
+**Frontend Admin:**
+- Produktliste, Produkt-Bearbeitungs-Form (inkl. i18n-Felder DE/EN, Bild-Upload)
+- Kategorieverwaltung (Baum)
+
+**Fertig wenn:** Admin legt Kategorie + Produkt an, Shop zeigt beides ohne Reload (Redis synchron).
+
+---
+
+## Modul 4 — Warenkorb & Checkout
+
+**Ziel:** Kunde kann Produkte in den Warenkorb legen und eine Bestellung abschließen (ohne echte Zahlung — Stub).
+
+**Backend (`apps/cart`, `apps/checkout`, `apps/payment` als Stub):**
+- `cart` (user_id oder session_id, items[])
+- `checkout`: validiert Cart, nimmt Adress- + Zahlungsmethoden-Daten entgegen, erzeugt Order
+- `payment`: Stub-Provider (`DummyPayment`) mit Interface `PaymentProvider`
+- Endpunkte: `GET/POST/DELETE /cart/items`, `POST /checkout/preview`, `POST /checkout/confirm`
+
+**Frontend Shop:**
+- Warenkorb-Seite + Mini-Cart
+- Checkout-Flow (Adresse → Zahlungsmethode → Bestätigung)
+
+**Fertig wenn:** Kunde legt Produkt in den Warenkorb und schließt Checkout ab → Order liegt in DB mit Status `paid` (Dummy-Provider).
+
+---
+
+## Modul 5 — Bestellungen & Mail
+
+**Ziel:** Bestellliste für Kunde + Admin, Bestellbestätigungs-Mail nach Order.
+
+**Backend (`apps/orders`, `apps/mail`):**
+- `orders`-App reagiert auf `checkout.confirmed` → schreibt Order, Status-Historie
+- Endpunkte: `GET /orders` (eigene), `GET /admin/orders` (alle), `GET /orders/{id}`
+- `mail`-App: Interface `MailProvider` (dev = Konsole/Mailhog, prod = SMTP/Anbieter)
+- Event-Handler: `order.created` → Bestätigungs-Mail mit Template (Jinja2, i18n)
+
+**Frontend Shop:**
+- `/account/orders` — Bestellliste + Detailseite
+
+**Frontend Admin:**
+- `/admin/orders` — Liste mit Filter, Detailseite mit Statusänderung
+
+**Fertig wenn:** Nach Checkout landet Mail in Mailhog, Kunde + Admin sehen Bestellung in ihrer jeweiligen Liste.
+
+---
+
+## Modul 6 — KI-Core (RAG)
+
+**Ziel:** RAG-Infrastruktur steht. Produkte, Kategorien, Settings sind indiziert und abfragbar.
+
+**Backend (`apps/ai_core`):**
+- `LLMProvider`-Interface + `OllamaProvider` (Default): `chat()`, `embed()`
+- Vector-Store: `pgvector`-Extension in Postgres, Tabelle `ai_documents` (id, source_type, source_id, text, embedding, metadata)
+- Indexer reagiert auf Events (`product.*`, `category.*`, `core.settings_updated`) und aktualisiert Embeddings
+- Endpunkt: `POST /ai/query` — nimmt Text + Kontext-Typ, liefert Antwort + relevante Dokument-IDs
+- Tool-System: Apps registrieren "Tools" (Funktionen), die die KI aufrufen darf — aber nur als **Vorschlag**, keine direkte Ausführung. Vorschläge werden als strukturiertes JSON zurückgegeben.
+
+**Frontend:** keines in diesem Modul — Infrastruktur only.
+
+**Fertig wenn:** `POST /ai/query` mit "grüner Pulli" liefert passende Produkt-IDs. Änderung an einem Produkt aktualisiert dessen Embedding automatisch.
+
+---
+
+## Modul 7 — Shop-KI-Suche
+
+**Ziel:** Kunde kann im Shop natürlichsprachlich nach Produkten suchen.
+
+**Backend (`apps/ai_shop`):**
+- Endpunkt `POST /ai/shop/search` — nutzt `ai_core`, liefert gefilterte/sortierte Produktliste
+- System-Prompt ist Shop-aware (Währung, Sprache des Users)
+
+**Frontend Shop:**
+- KI-Suchleiste oben (neben klassischer Suche)
+- Eingabe "ich suche einen grünen Pulli" → Produktgrid aktualisiert sich, KI-Begründung optional ausklappbar
+
+**Fertig wenn:** Suche nach "etwas warmes zum Wandern" liefert plausible Produkte (abhängig von Seed-Daten).
+
+---
+
+## Modul 8 — Admin-KI-Chat mit Vorschlags-Cards
+
+**Ziel:** Admin kann per Chat Aktionen planen lassen und per Card bestätigen.
+
+**Backend (`apps/ai_admin`):**
+- Endpunkt `POST /ai/admin/plan` — nimmt Prompt (oder JSON), nutzt `ai_core`-Tools, gibt **Aktionsplan** als Liste von Cards zurück:
+  ```json
+  [{"tool": "settings.update", "args": {...}, "missing": [], "preview": "..."}]
+  ```
+- Endpunkt `POST /ai/admin/execute` — nimmt bestätigte Card(s), validiert, führt die zugrundeliegenden Tools aus, gibt Resultat zurück
+- Tools registrieren sich mit JSON-Schema für Args, sodass fehlende/ungültige Felder erkennbar sind
+- Audit-Log jedes ausgeführten Tools
+
+**Frontend Admin:**
+- Chatbox auf Startseite
+- Eingabe Text ODER JSON-Bulk → zeigt Cards mit Tool, geplanten Args, fehlenden Feldern (editierbar)
+- "Bestätigen" pro Card oder "Alle bestätigen" → ruft `execute`
+- Erfolg/Fehler-Feedback pro Card
+
+**Beispiele, die nach Modul 8 funktionieren müssen:**
+- *"setze den Shopnamen auf TEST123"* → eine Card `settings.update {key: core.shop_name, value: TEST123}` → Bestätigen → Setting geändert
+- *(JSON mit 3 Produkten)* "das sind neue Produkte, erstelle sie" → 3 Cards `catalog.product.create`; fehlende SKU editierbar → Bestätigen → Produkte angelegt
+
+**Fertig wenn:** Beide Beispiele oben funktionieren end-to-end.
+
+---
+
+## Querschnittliche Themen (werden in jedem Modul mitgemacht)
+
+- **Tests**: pytest für Backend, vitest für Frontend; jedes Modul bringt mindestens einen Happy-Path-Test mit
+- **i18n**: Alle user-sichtbaren Strings DE + EN
+- **Migrationen**: Alembic-Head pro App, Core-Runner orchestriert
+- **Code-Qualität**: `ruff` + `eslint/prettier` laufen in CI (CI selbst in einem späteren Wartungs-Modul)
+- **Fehlendes bewusst ausgelassen** (optionale Apps, Phase 2+ der Analyse): Wunschliste, Bewertungen, Gutscheine, echte Payment-Provider, B2B-Preise, Genehmigungsworkflows, erweiterte Suche, SEO, Analytics. Werden als optionale Apps später gebaut.