wahnsinn vibe

2026-04-16 19:42:06 +02:00
parent 9c5da44f64
commit e3e88cc58e
127 changed files with 9456 additions and 3 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -0,0 +1,126 @@
+# Shopsystem — Prototyp Quickstart
+
+## Was ist das?
+
+Ein app-basiertes E-Commerce-Shopsystem als **Prototyp**, um ein Gefühl für das Konzept zu bekommen. 8 Module sind end-to-end implementiert (Core, Auth, Catalog, Cart/Checkout, Orders/Mail, AI-Core, AI-Shop-Suche, AI-Admin-Chat mit Vorschlags-Cards).
+
+## Voraussetzungen
+
+- Docker + `docker compose`
+- Python ≥ 3.11 + `uv` (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- Node ≥ 20 + `pnpm` (`npm install -g pnpm`)
+
+## Einmalig: Installation
+
+```bash
+make install    # installiert backend (uv) + frontend (pnpm)
+make infra      # startet postgres, redis, meilisearch, ollama, mailhog
+# Ollama zieht im Hintergrund llama3.1 (~5 GB) + nomic-embed-text (~270 MB).
+# Beim ersten Start dauert das je nach Bandbreite 10–20 min.
+make migrate    # erstellt Tabellen
+make seed       # legt Admin, Demo-Kunde, 4 Kategorien, 12 Produkte an
+make reindex    # baut KI-Embeddings (braucht nomic-embed-text)
+```
+
+## Starten
+
+```bash
+make dev        # startet Backend + Shop + Admin parallel im Vordergrund
+# Backend: http://localhost:8000  (OpenAPI-Docs: /docs)
+# Shop:    http://localhost:5173
+# Admin:   http://localhost:5174
+# Mailhog: http://localhost:8025
+```
+
+Oder einzeln: `make backend`, `make shop`, `make admin`.
+
+## Logins (Seed)
+
+- Admin: `admin@example.com` / `admin123`
+- Demo-Kunde: `kunde@example.com` / `kunde123`
+
+## Klick-Route durch alle Features
+
+### Shop (http://localhost:5173)
+
+1. **Startseite** — 12 Produkte, 4 Kategorien
+2. **KI-Suche** (`/ai` oder „KI-Suche" im Header):
+   - `grüner Pulli` → der „Grüne Kuschelpulli" erscheint ganz oben
+   - `etwas warmes zum Wandern` → Outdoor-Jacke, Wanderschuhe, Wanderhose
+3. **Registrierung** (`/register`) oder **Login** (`/login`, Demo-Kunde vorausgefüllt)
+4. Produkt öffnen → „In den Warenkorb" → `/cart` → **Zur Kasse**
+5. Adresse ausfüllen → **Jetzt bestellen** → Bestätigung mit Order-ID
+6. Auf Mailhog (http://localhost:8025) liegt die **Bestellbestätigung**
+7. `/account/orders` — Bestellung sichtbar
+
+### Admin (http://localhost:5174)
+
+1. Login mit Admin-Credentials (vorausgefüllt)
+2. **Dashboard** — Statistiken + KI-Chatbox
+3. **KI-Chatbox-Beispiele**:
+   - Typ: `setze den Shopnamen auf TEST123` → **Planen** → Card erscheint → **Bestätigen** → Shop-Header zeigt TEST123
+   - JSON-Bulk reinwerfen:
+     ```
+     Das sind neue Produkte, erstelle sie:
+     [
+       {"sku":"NEW-TS-RED","name_de":"Rotes T-Shirt","price":18.90,"stock":20},
+       {"sku":"NEW-SOCK","name_de":"Socken","price":4.90,"stock":100},
+       {"sku":"NEW-CAP","name_de":"Grüne Kappe","price":12.00,"stock":30}
+     ]
+     ```
+     → 3 Cards → Felder editierbar → **Alle bestätigen** → 3 neue Produkte im Shop
+4. **Produkte** — Liste, neu anlegen (mit Bild-Upload), bearbeiten, löschen
+5. **Kategorien** — CRUD
+6. **Bestellungen** — Liste + Detail + Statuswechsel (paid → shipped → delivered …)
+7. **Einstellungen** — Shopname ändern, KI-Index neu bauen
+
+## Nützliche Kommandos
+
+```bash
+make reindex    # nach großen Produkt-Änderungen oder bei KI-Suche-Problemen
+make reset      # destruktiv: DB-Volume löschen, alles neu
+make logs       # docker logs
+make infra-down # stoppt docker-services (dev-Prozesse bleiben)
+```
+
+## Bekannte Grenzen (bewusst so im Prototyp)
+
+- Keine Tests (pytest/vitest weggelassen)
+- Nur Dummy-Payment
+- Bild-Upload lokal in `./uploads`
+- KI-Shop-Suche: Hybrid aus Embedding + Keyword-Boost (nomic-embed-text ist auf Deutsch allein zu schwach)
+- KI-Admin-Chat nutzt llama3.1 — Antwort-Qualität hängt vom Modell ab. Bei schwachen Prompts kann die Card ungenau sein; Missing-Felder werden aber hart validiert
+- Meilisearch-Service läuft, ist aber nicht angebunden (für später)
+- Ein Admin-Panel-Logout via Sidebar lädt Login-Seite
+- Responsive, aber mobile-first-Polish fehlt
+
+## Architektur-Überblick
+
+```
+Browser
+  ├── http://localhost:5173  → Vue Shop (Kundensicht)
+  └── http://localhost:5174  → Vue Admin (KI-Chat, CRUD)
+          │
+          ▼
+    http://localhost:8000 FastAPI
+      ├── core (App-Loader, Event-Bus, DI, Settings, Redis-Projector, Security)
+      └── apps/*
+          auth, catalog, cart, checkout, payment, orders, mail,
+          ai_core (pgvector + Ollama + Tools), ai_shop (hybrid search),
+          ai_admin (Plan/Execute mit Proposal-Cards)
+                  │
+    ┌─────────────┼─────────────────┬─────────────┐
+    ▼             ▼                 ▼             ▼
+Postgres      Redis           Ollama           Mailhog
+(Write +      (Read-Cache:    (llama3.1        (Dev-SMTP,
+ pgvector)     Products,       Chat +           Web-UI 8025)
+               Categories,     nomic
+               Settings)       Embed)
+```
+
+## Troubleshooting
+
+- **„KI-Suche gibt nichts/Unsinn":** `make reindex` ausführen. Wenn nomic-embed-text nicht gezogen ist, siehe `docker compose logs ollama-init`.
+- **„KI-Chatbox gibt nur _error zurück":** Das llama3.1-Modell ist noch am Pullen. Warten bis in `curl http://localhost:11434/api/tags` beide Modelle auftauchen.
+- **„Port schon belegt":** `pkill -f vite; pkill -f uvicorn` dann `make dev`.
+- **„DB-Schema-Mismatch":** `make reset` (löscht alles und baut neu).