From 9c5da44f64df4101a782bf08cb4cb03817922c0a Mon Sep 17 00:00:00 2001 From: Marek Lenczewski Date: Thu, 16 Apr 2026 17:10:40 +0200 Subject: [PATCH] wahnsinn --- CLAUDE.md | 31 ++++++-- base.md | 97 +++++++++++++++++++++++++ module.md | 206 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 330 insertions(+), 4 deletions(-) create mode 100644 base.md create mode 100644 module.md diff --git a/CLAUDE.md b/CLAUDE.md index 139e3dd..2640d03 100644 --- a/CLAUDE.md +++ b/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 diff --git a/base.md b/base.md new file mode 100644 index 0000000..c6acfe7 --- /dev/null +++ b/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. diff --git a/module.md b/module.md new file mode 100644 index 0000000..1d2a228 --- /dev/null +++ b/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.