📦 E-Commerce Returns Management Engine (DDD Showcase)

Ein modernes, domänenorientiertes (Domain-Driven Design) E-Commerce Retouren-Management-System auf Basis von Laravel 13, Filament 5 und reiner Hexagonal-Architektur.

---

🎯 Das zentrale wirtschaftliche Problem & Showcase

„Warum bekommt der Kunde für das zurückgesendete Produkt nur 39,90 € statt 59,90 € zurück?“

In klassischen E-Commerce-Systemen führen Retouren oft zu pauschalen 100%-Rücküberweisungen, selbst wenn die Ware gebraucht, geöffnet oder unvollständig zurückkommt.

Dieses System löst das Problem durch eine deterministische, transparente und auditierbare Erstattungsberechnung:

Original Order (Kaufpreis: 59,90 €)
      │
      ▼
Return Request (Online-Portal)
      │
      ▼
Eligibility Check (Fristen, Mengen, Berechtigung)
      │
      ▼
Goods Received (Wareneingang im Lager)
      │
      ▼
Inspection (Physischer Befund)
  ├─ Zustand: USED (Gebraucht)
  ├─ Wiederverkauf: B_GOOD (B-Ware)
  └─ Wertminderung (Value Adjustment): -20,00 €
      │
      ▼
Refund Calculation (Deterministische Berechnung)
      │
      ▼
Final Refund: 39,90 € (Auditierbar & im Filament Backend aufgeschlüsselt)

---

🏗️ Hexagonale Domain-Driven Design (DDD) Architektur

app/Domain/Returns/                 # 100% PURE PHP 8.4 (Keine Framework-Abhängigkeiten)
├── Model/
│   ├── ReturnOrder.php             # Aggregate Root (State Machine & Invarianten)
│   ├── Entities/                   # ReturnItem, Inspection
│   └── ValueObjects/               # Money, Quantity, ReturnStatus, ReturnCondition, etc.
├── Services/
│   ├── ReturnEligibilityService.php
│   ├── RefundCalculator.php
│   └── ProportionalDiscountAllocationStrategy.php
├── Specifications/                 # ReturnIsWithinAllowedPeriod, ProductIsReturnable
├── Events/                         # ReturnRequested, ReturnInspected, RefundCalculated, etc.
└── Repositories/                   # ReturnRepositoryInterface, OrderReadPortInterface

app/Application/Returns/            # Orchestrierung von Use Cases (Commands & Handlers)
├── Commands/                       # CreateReturn, ApproveReturn, RecordInspection, CompleteReturn...
└── Handlers/                       # Transaktionale Ausführung der Domänenoperationen

app/Infrastructure/                 # Technische Adapter & Persistenz
├── Persistence/Eloquent/Models/    # OrderModel, ReturnModel, ReturnInspectionModel, AuditLogs
└── Repositories/                   # EloquentReturnRepository, EloquentOrderReadPort

app/Filament/                       # UI-Steuerung (Filament 5 Admin Panel)
└── Resources/Returns/              # Tabellen, Inspektions-Dialog, Explainability-Infolist

---

🚀 Schnellstart (Quickstart mit Zenv)

1. Docker-Container starten:

./zenv up

2. Datenbank migrieren & Demo-Daten seeden:

./zenv artisan migrate --seed

3. Filament Admin Panel öffnen:

• URL: http://localhost/admin
• E-Mail: admin@example.com
• Passwort: password

4. RedisInsight Web-UI öffnen:

• URL: http://localhost:5540
• Host: redis | Port: 6379

---

🧪 Tests & Qualitätssicherung

Das gesamte Projekt ist lückenlos mit Pest PHP getestet:

# Alle Unit-, Feature- und Architecture-Tests ausführen:
./zenv pest

# Nur Architecture-Tests (Schichtenreinheit der Domain):
./zenv pest tests/Architecture

# Code-Style prüfen mit Laravel Pint:
./zenv vendor/bin/pint --test

---

📄 Lizenz & Dokumentation

• Konzept: docs/concepts/returns-management.md
• Value Proposition: docs/marketing/returns-management-showcase.md
• Changelog: CHANGELOG.md