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

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

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)

Startseite — 12 Produkte, 4 Kategorien
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
Registrierung (/register) oder Login (/login, Demo-Kunde vorausgefüllt)
Produkt öffnen → „In den Warenkorb" → /cart → Zur Kasse
Adresse ausfüllen → Jetzt bestellen → Bestätigung mit Order-ID
Auf Mailhog (http://localhost:8025) liegt die Bestellbestätigung
/account/orders — Bestellung sichtbar

Admin (http://localhost:5174)

Login mit Admin-Credentials (vorausgefüllt)
Dashboard — Statistiken + KI-Chatbox

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

Produkte — Liste, neu anlegen (mit Bild-Upload), bearbeiten, löschen
Kategorien — CRUD
Bestellungen — Liste + Detail + Statuswechsel (paid → shipped → delivered …)
Einstellungen — Shopname ändern, KI-Index neu bauen

Nützliche Kommandos

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

5.3 KiB Raw Blame History Unescape Escape