From 6774ffa35f8b2fdbeb004c0b58ad9b2378f7dfc0 Mon Sep 17 00:00:00 2001 From: Jens Date: Sat, 13 Jun 2026 13:26:39 +0200 Subject: [PATCH] Architektur --- Doku/architektur.md | 117 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 Doku/architektur.md diff --git a/Doku/architektur.md b/Doku/architektur.md new file mode 100644 index 0000000..32a448c --- /dev/null +++ b/Doku/architektur.md @@ -0,0 +1,117 @@ +# 🌿 Architektur-Dokumentation: Gartenprojekt (Symfony) + +## 1. Vision & Kernprinzipien +Das Ziel dieser Architektur ist eine strikte Trennung zwischen technischer Infrastruktur, Geschäftslogik und den Liefermechanismen. Wir verfolgen einen Ansatz, der an **Clean Architecture** und **Hexagonal Architecture** angelehnt ist. + +### Grundregeln: +* **Unidirektionaler Fluss:** `UI` $\rightarrow$ `Logic` $\rightarrow$ `Data`. Ein Layer darf niemals Informationen aus einem übergeordneten Layer importieren. +* **Dependency Inversion:** Die `Logic`-Schicht definiert die Anforderungen (Interfaces). Die `Data`-Schicht implementiert diese. Die Logik ist somit unabhängig von der Datenbank-Technologie. +* **Model-Zentrierung:** Das Model ist das Herzstück der Applikation. Es ist ein anämisches POPO (Plain Old PHP Object) und wird primär im gesamten System verwendet. +* **Atomarität:** Business-Operationen sind atomar. Entweder alles wird gespeichert oder nichts (Transaction Management). + +--- + +## 2. Die Schichtenarchitektur + +### 🟢 UI Layer (Delivery Mechanisms) +Die UI-Schicht ist die dünne Eintrittspforte. Sie besitzt keine Geschäftslogik. +* **Einstiegspunkte:** `Http` (Controller), `Console` (Commands), `Queue` (MessageHandlers). +* **Verantwortlichkeiten:** + * Mapping von Input auf **DTOs**. + * Syntaktische Validierung via Symfony Constraints am DTO. + * Grobe Autorisierungsprüfung (Rollen-basiert, z.B. `ROLE_USER`). + * Aufruf des entsprechenden **UseCase**. + +### 🔵 Logic Layer (Business Core) +Hier wird definiert, *was* das System tut. Die Logik ist in Orchestrierung und zustandslose Fachlogik unterteilt. + +#### A. Orchestrierung & State +* **UseCase:** Der Dirigent eines Business-Prozesses. Er koordiniert den Ablauf: `Authorization` $\rightarrow$ `Validation` $\rightarrow$ `Calculation` $\rightarrow$ `Save`. Er steuert die Transaktionsgrenzen via `TransactionManagerInterface`. +* **Manager:** Zuständig für das **State Management**. Er implementiert das *Cache-Aside Pattern* (prüft Cache vor dem Provider) und steuert die Cache-Invalidierung nach Schreibvorgängen. + +#### B. Spezialisierte Logik (Stateless Services) +Um "Fat Managers" zu vermeiden, wird Fachlogik in spezialisierte Klassen ausgelagert: +* **Calculators:** Pure Functions für Berechnungen $\rightarrow$ gibt Werte zurück. +* **Policies:** Business-Regelprüfungen $\rightarrow$ gibt `boolean` zurück. +* **Validators:** Komplexe Zustandsprüfungen $\rightarrow$ wirft `ValidationException`. +* **Strategies:** Kapselung austauschbarer Algorithmen. + +#### C. Domain Objekte +* **Models:** Die primären Datencontainer (z.B. `GardenPlan`). Anämisch und unabhängig von der DB. +* **DTOs:** Transportobjekte zwischen UI und Logic. +* **Domain Events:** Dünne Ereignisse (ID & Typ), die via `DomainEventCollector` gesammelt und nach dem Commit gefeuert werden. + +### 🔴 Data Layer (Infrastructure) +Die technische Realisierung. Alles hier ist austauschbar, solange die Interfaces der Logic-Schicht erfüllt werden. +* **Provider / Processor:** Implementierungen der in der Logic definierten Interfaces. Provider = Lesen | Processor = Schreiben. +* **Entities:** Die technischen Repräsentationen für Doctrine (z.B. `GardenPlanEntity`). +* **Mappers:** Explizite Klassen, die zwischen `Entity` $\leftrightarrow$ `Model` transformieren. + +--- + +## 3. Technischer Workflow & Pipeline + +### Der Schreib-Pfad (Write Flow) +`UI (Controller/Command)` $\rightarrow$ `DTO` $\rightarrow$ `UseCase (Start Transaction)` $\rightarrow$ `Auth Check (Voter)` $\rightarrow$ `Validator` $\rightarrow$ `Policy` $\rightarrow$ `Calculator` $\rightarrow$ `Manager` $\rightarrow$ `Processor` $\rightarrow$ `Mapper` $\rightarrow$ `Entity` $\rightarrow$ `DB`. + +### Der Lese-Pfad (Read Flow) +`UI` $\rightarrow$ `UseCase` $\rightarrow$ `Manager (Cache check)` $\rightarrow$ `Provider Interface` $\rightarrow$ `Implementation` $\rightarrow$ `Mapper` $\rightarrow$ `Model` $\rightarrow$ `UI`. + +--- + +## 4. Querschnittsfunktionen + +### Transaktionssteuerung & Fehler +* **Transaction Management:** Der UseCase nutzt ein `TransactionManagerInterface`, um sicherzustellen, dass alle Änderungen innerhalb eines Prozesses atomar erfolgen. +* **Error Handling:** Eigene Domain-Exceptions in der Logic. Ein zentraler **Symfony ExceptionListener** mappt diese auf HTTP-Statuscodes (400, 403, 404, etc.). + +### Asynchronität (Messenger) +* **Inbound:** `Message` $\rightarrow$ `Handler` $\rightarrow$ `DTO` $\rightarrow$ `UseCase`. +* **Outbound:** Nachrichten werden erst **nach** dem erfolgreichen Commit der Transaktion verschickt (Post-Commit Trigger), um "Ghost Notifications" zu vermeiden. + +--- + +## 5. Namensmusterkatalog + +| Komponente | Muster | Beispiel | +| :--- | :--- | :--- | +| **Model** | `[Entity]` | `GardenPlan` | +| **Entity** | `[Entity]Entity` | `GardenPlanEntity` | +| **UseCase** | `[Action][Entity]UseCase` | `CreateGardenPlanUseCase` | +| **Manager** | `[Entity]Manager` | `GardenPlanManager` | +| **Calculator** | `[Topic]Calculator` | `SpacingCalculator` | +| **Policy** | `[Rule]Policy` | `CompatibilityPolicy` | +| **Validator** | `[Entity]Validator` | `GardenLayoutValidator` | +| **Provider Interface**| `[Entity]ProviderInterface` | `GardenPlanProviderInterface` | +| **Processor Interface**| `[Entity]ProcessorInterface`| `GardenPlanProcessorInterface`| +| **Mapper** | `[Src]To[Tgt]Mapper` | `GardenPlanEntityToModelMapper`| +| **DTO** | `[Action][Entity]Dto` | `UpdateGardenPlanDto` | + +--- + +## 6. Ordnerstruktur (Hybrid-Feature Ansatz) + +```text +src/ +├── UI/ +│ ├── Http/Controller/[Feature]/ # z.B. /Planning/GardenPlanController.php +│ ├── Console/Command/[Feature]/ # z.B. /Irrigation/StartWateringCommand.php +│ └── Queue/MessageHandler/[Feature]/ # z.B. /Notification/SendMailHandler.php +│ +├── Logic/ +│ ├── UseCase/[Feature]/ # z.B. /Planning/CreateGardenPlanUseCase.php +│ ├── Manager/[Feature]/ # z.B. /Planning/GardenPlanManager.php +│ ├── Domain/ +│ │ ├── Model/[Feature]/ # z.B. /Planning/GardenPlan.php +│ │ ├── DTO/[Feature]/ # z.B. /Planning/UpdatePlanDto.php +│ │ └── Service/[Feature]/ # Calculator, Policy, Validator, Strategy +│ └── InfrastructureInterface/ # Provider & Processor Interfaces +│ +├── Data/ +│ ├── Doctrine/ +│ │ ├── Entity/[Feature]/ # z.B. /Planning/GardenPlanEntity.php +│ │ └── Mapping/[Feature]/ # z.B. /Planning/GardenPlanMapper.php +│ └── Implementation/ +│ ├── Provider/[Feature]/ # Realisierung der Interfaces +│ └── Processor/[Feature]/ # Realisierung der Interfaces +```