Systemarchitektur¶

Der Shop ist eine django-oscar 3.x-basierte E-Commerce-Anwendung mit domänenspezifischen Erweiterungen für Getränkelogistik, Pfandsysteme und mehrstufiges Kommunikations-Routing.

Projektstruktur¶

src/snake_shop/
├── config/                  # Django-Projektkonfiguration
│   ├── settings/            # Modulare Settings (django, oscar, celery, api, …)
│   ├── urls.py              # URL-Routing mit i18n_patterns
│   ├── wsgi.py / asgi.py    # WSGI/ASGI-Entrypoints
│   └── celery.py            # Celery-Konfiguration
├── apps/                    # Oscar-App-Overrides (Custom Shop-Logik)
│   ├── basket/              # Warenkorb (Pfand, Verfügbarkeit, after_deposit)
│   ├── catalogue/           # Produkte, Kategorien, Varianten, Middleware
│   ├── checkout/            # Bestellprozess, SurchargeApplicator, Mixins
│   ├── communication/       # E-Mail-Dispatcher, Event-Typen, Signals
│   ├── customer/            # Benutzer, Adressen
│   ├── dashboard/           # Verwaltungsoberfläche (angepasste Views)
│   ├── logistics/           # Liefertermine, Routen, Zeitfenster-Generator
│   ├── offer/               # Angebote, Rabatte, Conditions, Benefits
│   ├── order/               # Bestellungen mit Pfand-Splitting
│   ├── partner/             # Lieferanten, Preisstrategie, Middleware
│   ├── payment/             # Zahlungsabwicklung, Provider
│   ├── shipping/            # Versandmethoden, Zuschläge (OrderAndItemCharges)
│   └── wishlists/           # Wunschlisten
├── affiliate/               # Partner-Tracking (Tracker-View, Provisionslogik)
├── api/                     # REST API (OscarAPI + Swagger)
├── assistant/               # KI-Assistent (Pydantic AI, RAG)
├── custom/                  # Shop-spezifische Middleware, Setup-Views
├── feedback/                # Kunden-Feedback-System
├── monitoring/              # OpenTelemetry, Metriken, Health-Checks
├── newsletter/              # Newsletter (django-newsletter)
├── search/                  # PostgreSQL-Volltextsuche
├── subscription/            # Plugin-/Abonnement-Verwaltung
├── sync/                    # ERP-/WaWi-Synchronisation
├── translate/               # Übersetzungs-Management
├── user/                    # Benutzer, Organisationseinheiten (OU)
└── websocket/               # WebSocket-Endpunkte (Django Channels)

Architekturmuster¶

Oscar-App-Override¶

Django-Oscar-Apps werden über die Django-App-Registry überschrieben:

# config/settings/installed_apps.py
INSTALLED_APPS = [
    "apps.basket.apps.BasketConfig",     # statt oscar.apps.basket
    "apps.checkout.apps.CheckoutConfig", # statt oscar.apps.checkout
    "apps.shipping.apps.ShippingConfig", # statt oscar.apps.shipping
    # ...
]

Dadurch können Modelle, Views und Logik überschrieben werden, ohne den Oscar-Core zu verändern. Oscar selbst bleibt als Abhängigkeit (django-oscar==3.2.6) installiert.

Organisationseinheiten (OU)¶

Die OrganizationUnit ist das zentrale Routing-Konzept für Kommunikation:

Bündelt Zuständigkeit (Kunden, Produktklassen), Empfänger (Mitglieder, E-Mail-Adressen, API-Endpunkte) und Ereignistypen
Jede OU hat ein Pflichtfeld type (INTERNAL / ADDITIONAL_EMAIL_RECIPIENT)
Siehe OU-Routing für den vollständigen Versandablauf

SurchargeApplicator (Checkout)¶

Der SurchargeApplicator (apps/checkout/applicator.py) berechnet Versandzuschläge als separate Surcharge-Zeilen. Anders als Oscar, wo calculate() den Gesamtpreis liefert, gibt calculate() hier 0,00 € zurück – alle Kosten werden über get_extra_charges() gesteuert.

Siehe Checkout-Flow für den vollständigen Bestellablauf.

Logistik-Cursor¶

Der Verfügbarkeits-Cursor (apps/logistics/cursor.py) steuert die Anzeige von Lieferterminen im Checkout:

AvailabilityCursor – Zustandsmaschine für Lieferverfügbarkeit
TimeSlotGenerator – Generiert Zeitfenster aus Zeitplänen
get_next_time_slots() – Ermittelt nächste verfügbare Termine
Virtuelle Zeitfenster werden live aus Schedule + Rule abgeleitet

Middleware-Stack¶

Middleware	Funktion
`TrailingSlashRedirectMiddleware`	301-Weiterleitung für Produkt-URLs ohne Slash
`apps.logistics.middleware.LogisticsMiddleware`	Logistik-Kontext pro Request
`apps.catalogue.middleware.ProductMiddleware`	Produkt-spezifischer Request-Kontext
`apps.partner.middleware.PartnerMiddleware`	Partner-Erkennung & Auswahl
`cookiebanner.middleware.CookieBannerMiddleware`	Cookie-Consent-Banner
`django_htmx.middleware.HtmxMiddleware`	HTMX-Request-Erkennung
`lockdown.middleware.LockdownMiddleware`	Wartungsmodus (optional)

Signals & Events¶

Kommunikations-Signals¶

apps/communication/signals.py verknüpft Domain-Events mit dem Dispatcher:

Signal	Event-Typ	Auslöser
`post_order_placed`	ORDER_PLACED	Bestellabschluss
`post_registration`	REGISTRATION	Neukunden-Registrierung
`post_address_created`	USERADDRESS_CREATED	Neue Lieferadresse
`post_password_changed`	PASSWORD_CHANGED	Passwortänderung
Produkt-Alert	PRODUCT_ALERT	Produkt wieder verfügbar

Logistik-Signals¶

apps/logistics/signals.py reagiert auf Bestelländerungen für die Kapazitätsverwaltung.

Async-Unterstützung¶

Django Channels¶

WebSocket-Verbindungen werden über Django Channels verwaltet (websocket/). Konfiguration in config/asgi.py:

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": TokenAuthMiddlewareStack(
        URLRouter(websocket_urlpatterns)
    ),
})

Celery Tasks¶

Asynchrone Verarbeitung über Celery + Redis:

apps/communication/tasks.py – E-Mail-Versand, OU-Dispatch
apps/sync/tasks.py – ERP-Synchronisation
Periodische Tasks über Celery Beat

Konfiguration¶

Die Settings sind in config/settings/ modular organisiert:

Modul	Inhalt
`django.py`	Django-Core (DB, Cache, I18N, Timezone)
`oscar.py`	Oscar-Einstellungen (Produktklassen, Handler)
`installed_apps.py`	App-Registrierung in korrekter Reihenfolge
`middleware.py`	Middleware-Stack
`template.py`	Template-Engine, Context-Prozessoren
`celery.py`	Celery-Broker, Result-Backend
`api.py`	REST-Framework, OscarAPI
`app_config.py`	App-spezifische Konfiguration
`from_env.py`	Umgebungsvariablen aus `.env`
`logging.py`	Strukturiertes Logging
`cookiebanner.py`	Cookie-Banner-Einstellungen

Technologie-Stack¶

Technologie	Zweck
Django 4.2	Web-Framework
django-oscar 3.2	E-Commerce-Domain
PostgreSQL 16	Datenbank + Volltextsuche (pgvector)
Celery 5.x	Asynchrone Task-Queue
Redis 7	Cache + Message-Broker + Session-Backend
Django Channels 4	WebSocket-Unterstützung
Docker + Compose	Lokale Entwicklungsumgebung
Traefik	Reverse-Proxy + SSL-Terminierung
Helm	Kubernetes-Deployment
OpenTelemetry	Distributed Tracing & Metriken
Grafana + Loki + Tempo	Monitoring-Stack
Pydantic AI	KI-Assistent im Backend
HTMX + Alpine.js	Frontend-Interaktivität