75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
# Shopsystem — Projektrichtlinien
|
|
|
|
## Projekt
|
|
|
|
Custom E-Commerce Shopsystem (B2C + B2B), weltweit einsetzbar, als verkaufbares Produkt geplant.
|
|
|
|
## Architektur
|
|
|
|
- **App-basiertes System**: Jede Funktion ist eine App mit Manifest (Abhängigkeiten, Konflikte, Pflicht/Optional)
|
|
- **Core**: Minimaler Kern (Auth, API-Router, App-Loader, Event-Bus, DI-Container)
|
|
- **Kommunikation zwischen Apps**: Events (lose Kopplung) und Dependency Injection (keine direkten Imports)
|
|
- **Dritt-Entwickler** können eigene Apps bauen (Marketplace-Konzept)
|
|
|
|
## 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.
|
|
**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)
|
|
- **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
|
|
|
|
- PostgreSQL ist die Quelle der Wahrheit (alle Schreiboperationen)
|
|
- Redis ist die Lese-Schicht (Frontend liest NUR aus Redis)
|
|
- Sync: Sofort-Aktualisierung bei Änderungen + Scheduler als Sicherheitsnetz
|
|
- Frontend sieht nie die DB-Komplexität, nur schnelle Redis-Reads
|
|
|
|
## 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 an
|
|
|
|
## Implementierter Stand (Prototyp)
|
|
|
|
- Alle 8 Module aus `module.md` sind lauffähig: Core, Auth, Catalog, Cart, Checkout, Orders+Mail, AI-Core (RAG/pgvector), AI-Shop-Suche (hybrid), AI-Admin-Chat (Plan/Execute mit Vorschlags-Cards).
|
|
- Keine Tests (Prototyp).
|
|
- Dummy-Payment, Mailhog für Dev-Mails, Bild-Upload lokal in `./uploads`.
|
|
- Starten per `make install && make infra && make migrate && make seed && make reindex && make dev`. Details in `QUICKSTART.md`.
|
|
|
|
## Analyse-Dokument
|
|
|
|
- `shopsystem-analyse.tex` — Vollständige Analyse (34 Seiten), nicht mehr anpassen.
|
|
|
|
## Arbeitsweise
|
|
|
|
- Antworten kompakt halten.
|
|
- KI-gestützter Workflow: Prototyp → Refactoring → Refactoring.
|