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