Architektur
This commit is contained in:
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user