feat: define UseCase pattern and directory structure

architektur-patterns.md

@@ -0,0 +1,97 @@
+# Architektur Patterns
+
+Diese Datei definiert die konkreten Implementierungsmuster für die verschiedenen Layer der Anwendung.
+
+## 1. UseCase Pattern (`src/Logic`)
+
+Das UseCase Pattern bildet das Herzstück der Business-Logik. Jeder Anwendungsfall wird als eigenständige Klasse implementiert, um eine klare Trennung der Verantwortlichkeiten und eine hohe Testbarkeit zu gewährleisten.
+
+### Struktur & Definition
+- **Interface**: Alle UseCases müssen das `UseCaseInterface` implementieren.
+- **Methode**: Die primäre Logik liegt in der Methode `execute()`.
+- **Eingabe/Ausgabe**: Daten werden strikt über DTOs (Data Transfer Objects) ausgetauscht.
+- **Rückgabewert**: Ein UseCase gibt entweder ein Response-DTO zurück oder `void` (bei reinen Schreiboperationen).
+- **Fehlerbehandlung**: Business-Fehler werden über spezifische **Domain-Exceptions** signalisiert.
+
+### DTOs (Data Transfer Objects)
+- **Typ**: Readonly-Klassen (PHP 8.2+).
+- **Namenskonvention**: Suffix `Request` für Eingabe, `Response` für Ausgabe.
+- **Typisierung**: Maximale native Typisierung; PHPDocs nur bei komplexen Types (z.B. Generics in Arrays).
+
+### Namenskonvention & Verzeichnisstruktur
+- **Klassennamen**: Suffix `UseCase`.
+- **Pfad**: `src/Logic/{Module}/{Feature}/{Typ}/...`
+
+**Beispiel-Struktur:**
+- `src/Logic/Sales/Order/UseCase/CreateOrderUseCase.php`
+- `src/Logic/Sales/Order/Dto/CreateOrderRequest.php`
+- `src/Logic/Sales/Order/Dto/CreateOrderResponse.php`
+
+### Code Beispiel
+
+#### Interface
+```php
+namespace App\Logic\Common;
+
+/**
+ * @template TRequest
+ * @template TResponse
+ */
+interface UseCaseInterface
+{
+    /**
+     * @param TRequest $request
+     * @return TResponse|void
+     */
+    public function execute(mixed $request): mixed;
+}
+```
+
+#### Implementierung
+```php
+namespace App\Logic\Sales\Order\UseCase;
+
+use App\Logic\Common\UseCaseInterface;
+use App\Logic\Sales\Order\Dto\CreateOrderRequest;
+use App\Logic\Sales\Order\Dto\CreateOrderResponse;
+use App\Logic\Sales\Order\Exception\InsufficientStockException;
+
+readonly class CreateOrderUseCase implements UseCaseInterface
+{
+    public function execute(mixed $request): CreateOrderResponse
+    {
+        if (!$request instanceof CreateOrderRequest) {
+            throw new \InvalidArgumentException('Invalid request type');
+        }
+
+        // Business Logik hier...
+        if ($this->stockTooLow()) {
+            throw new InsufficientStockException();
+        }
+
+        return new CreateOrderResponse(orderId: '123');
+    }
+
+    private function stockTooLow(): bool { return false; }
+}
+```
+
+#### DTOs
+```php
+namespace App\Logic\Sales\Order\Dto;
+
+readonly class CreateOrderRequest
+{
+    public function __construct(
+        public string $customerId,
+        public array $items,
+    ) {}
+}
+
+readonly class CreateOrderResponse
+{
+    public function __construct(
+        public string $orderId,
+    ) {}
+}
+```