127 lines
5.3 KiB
Markdown
127 lines
5.3 KiB
Markdown
# 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).
|