svc-essensplanung/Doku/architektur.md

Architektur – svc-essensplanung

Konkretisierung der ADR-007 für diese App. Referenz: jens/symfony-architektur.

0. Die drei Layer (Kurzreferenz)

+-------------+     +--------------------------+     +--------------------------------------+
|    UI       |     |          Logic           |     |                Data                    |
| (src/UI)    | --> | (src/Logic)              | --> |  (src/Data)                             |
├-------------┤     ├──────────────────────────┤     ├────────────────────────────────────────┤
│ Controllers │     │ UseCases  (Writes)       |     │ Entities (Doctrine)                    │
│ Commands    │     │ Queries   (Reads)        |     │ Mappers (Entity <-> Model)             │
│ Templates   |     │ Managers  (per Model)    |     │ Providers (Read)                       │
│ (Twig)      |     │ Models    (POPO, Rich)   |     │ Processors (Write)                     │
│ Exception   |     │ DTOs      (readonly)     |     │ Transaction-Manager-Bridge             │
│ Subscriber  |     │ Exceptions (Domain)      |     │ EventDispatcher-Bridge                 │
└-------------┘     │ Mapping (Model-Factory)  |     │                                        │
                    | Provider/Processor Ifcs  |     │                                        │
                    └──────────────────────────┘     └────────────────────────────────────────┘

Abhängigkeitsregel (Dependency Inversion): UI → Logic; Logic → Interface (Definition im Logic); Data → Interface (Definition im Data). Die Data-Layer implementiert Interfaces aus der Logic-Layer. Keine Umkehr.

Namenskonvention (Kurz):

• Interface: Suffixe Interface (z. B. DishProviderInterface).
• UseCase: Suffix UseCase (z. B. CreateDishUseCase).
• Query: Suffix Query (z. B. ListDishesQuery).
• Manager: Suffix Manager (z. B. DishManager).
• Provider/Processor: Suffix Provider/Processor (z. B. DishProvider).
• Mapper: Suffix Mapper (z. B. DishMapper).
• Model-Factory: Suffix Factory (z. B. DishModelFactory).
• DTO: Suffix Request bzw. Response.
• Exception: Suffix Exception.
• Entity (Data): Suffix Entity (z. B. DishEntity).

1. Domain-Modell (Logik)

Eine Modul-Domäne: Essen. Darin ein Business-Model: Dish (Gericht/Eintrag). Wichtiger Hinweis: Die "Archivsicht" ist kein abgesonderter Business-Model, sondern eine Volltext-Sicht (Read-Query) mit dem Filter status = gegessen. Das reduziert die Komplexität.

1.1. Das Business-Model Dish

src/Logic/Essen/Model/Dish.php – Rich Domain Model (POPO, readonly, kein Framework):

namespace App\Logic\Essen\Model;

class Dish
{
    public function __construct(
        public readonly ?int $id,
        public string $name,
        public ?string $notiz,
        /** @var DishDay[] */
        public readonly array $wochentage,
        public readonly int $sort_order,
        public DishStatus $status,
        public readonly ?\DateTimeImmutable $gegessen_am,
        public readonly \DateTimeImmutable $erstellt_am,
        public readonly \DateTimeImmutable $aktualisiert_am,
    ) {}

    // State transitions: kapseln eigene Statusänderungen
    public function markAsGegessen(\DateTimeImmutable $now): self {
        if ($this->status === DishStatus::GEGESSEN) {
            throw new BusinessRuleViolationException('Bereits gegessen.');
        }
        return new self($this->id, $this->name, $this->notiz, $this->wochentage,
            $this->sort_order, DishStatus::GEGESSEN, $now, $this->erstellt_am, $now);
    }

    public function markAsGeplant(\DateTimeImmutable $now): self { /* symmetrisch */ }
}

Enums in src/Logic/Essen/Model/:

• DishStatus (GEPLANT, GEGESSEN)
• DishDay (MO, DI, MI, DO, FR, SA, SO)

1.2. DTOs

src/Logic/Essen/Dto/
├── CreateDishRequest.php        // name, notiz?, wochentag[]? 
├── UpdateDishRequest.php        // id, name, notiz?, wochentag[]?, sort_order?
├── DeleteDishRequest.php        // id
├── MoveDishRequest.php          // id, position (int)
├── ToggleDishStatusRequest.php  // id
├── ListDishesRequest.php        // status? (optional), sort='sort_order'|'gegessen_am'
├── ListDishesResponse.php       // items: Dish[]
├── InspirationRequest.php       // limit=5, offset=0, excludeIds: int[]
├── InspirationResponse.php      // suggestions: Dish[]
└── TodayResponse.php            // dishes: Dish[]   // optional HA-Consumer

Alle readonly, native Typisierung, keine Attribute/Constraints.

1.3. UseCases (Writes)

src/Logic/Essen/UseCase/
├── CreateDishUseCase.php
├── UpdateDishUseCase.php
├── DeleteDishUseCase.php
├── MoveDishUseCase.php          // ändert sort_order (bzw. sort_order-Reihenfolge)
└── ToggleDishStatusUseCase.php  // markAsGegessen / markAsGeplant

Verfahren (schlau aus Referenz Sektion 1 & 3):

1. Syntaktische Validierung im UI-Layer (Controller/Command) als rein PHP (keine Symfony-Validator-Constraints auf DTOs).
2. Business-Validierung im UseCase + im Model-Konstruktor (Invarianzen).
3. Persistence im UseCase via DishManager → DishProcessor (Write); Cache-Sidecar-Invalidierung im Manager.
4. Event-Dispatch nach erfolgreichem Commit (Bridge in Data-Layer).
5. Response-DTO (z. B. UpdateDishResponse) zurück an Controller.

Beispiel (UseCase CreateDishUseCase):

namespace App\Logic\Essen\UseCase;

readonly class CreateDishUseCase
{
    public function __construct(
        private TransactionManagerInterface $tx,
        private DishManagerInterface $dishes,
        private DishModelFactory $factory,
        private EventDispatcherInterface $events,
    ) {}

    public function execute(CreateDishRequest $req): CreateDishResponse
    {
        return $this->tx->execute(function() use ($req): CreateDishResponse {
            $dish = $this->factory->createFromRequest($req);   // DTO -> Model
            $saved = $this->dishes->create($dish);               // Model -> Processor
            $this->events->dispatch(new DishCreatedEvent(id: $saved->id));
            return new CreateDishResponse(id: $saved->id, dish: $saved);
        });
    }
}

1.4. Queries (Reads)

src/Logic/Essen/Query/
├── ListDishesQuery.php          // -> ListDishesResponse
├── GetDishQuery.php             // -> Dish (optional)
├── TodayQuery.php               // -> TodayResponse   (HA-Consumer / optional)
└── InspirationQuery.php         // -> InspirationResponse (5er-Batch + Offset)

InspirationQuery (Algorithmus, ADR-006):

readonly class InspirationQuery
{
    public function __construct(
        private InspirationWeightSettings $settings,   // w_slow/w_rare/w_hot
        private DishManagerInterface $dishes,
        private DishHistoryProviderInterface $history,  // aus Data-Layer
    ) {}

    public function execute(InspirationRequest $req): InspirationResponse
    {
        $all = $this->dishes->listGegessen();
        $history = $this->history->historyByDishName();

        $scored = $all
            ->filter(fn(Dish $d) => !in_array($d->id, $req->excludeIds, true))
            ->map(fn(Dish $d) => new Scored(
                  dish: $d,
                  score: $this->score($d, $history),
            ))
            ->sortDescByScore()
            ->slice($req->offset, $req->limit);

        return new InspirationResponse(suggestions: $scored->map(fn($s)=>$s->dish));
    }

    private function score(Dish $d, array $h): float {
        // w_slow * staleness + w_rare * rarity + w_hot * popularity
        // (Details: ADR-006)
    }
}

1.5. Manager (pro Business-Model)

src/Logic/Essen/Manager/
├── DishManagerInterface.php
└── DishManager.php   // Read + Write-Koordination, Cache-Aside (vorerst
                      // ohne Cache, Platzhalter für Phase 2)

Interface (in Logic):

interface DishManagerInterface
{
    public function create(Dish $dish): Dish;
    public function update(Dish $dish): Dish;
    public function delete(int $id): void;
    public function move(Dish $dish, int $newSortOrder): void;
    public function find(int $id): Dish;
    /** @return Dish[] */
    public function listGegessen(): array;
    /** @return Dish[] */
    public function listGeplant(): array;
    public function invalidateCache(): void;
}

1.6. Provider-/Processor-Interfaces (in Logic)

src/Logic/Essen/
├── DishProviderInterface.php     // Read: find, listGegessen, listGeplant, countByName...
└── DishProcessorInterface.php    // Write: create, save, delete; move (sort_order)

Implementierungen liegen in src/Data/Essen/Provider/ bzw. Processor/.

1.7. Model-Factory (DTO -> Model)

src/Logic/Essen/Mapping/DishModelFactory.php
├── createFromRequest(CreateDishRequest): Dish
├── updateFromRequest(UpdateDishRequest): Dish
└── rebuildFromPartialUpdate(Dish $current, UpdateDishRequest $req): Dish

1.8. Domänen-Exceptions

src/Logic/Common/Exception/
├── DomainException.php            // abstract base (RuntimeException)
├── ResourceNotFoundException.php  // -> 404
├── BusinessRuleViolationException.php  // -> 422
├── ConcurrencyException.php       // -> 409 (falls Locking)
├── AccessDeniedException.php      // -> 403
└── InfrastructureException.php    // -> 503

src/Logic/Essen/Exception/
└── DishNotFoundException.php      // erbt ResourceNotFoundException

HTTP-Mapping erfolgt zentral in src/UI/Http/ExceptionSubscriber.php (keine try-catch in jedem Controller).

1.9. Gemeinsame Schnittstellen in src/Logic/Common/

src/Logic/Common/
├── TransactionManagerInterface.php   // execute(callable): mixed
├── EventDispatcherInterface.php      // dispatch(object $event): void
└── Exception/ (wie oben)

Bridges in Data (siehe Sektion 1.10):

• src/Data/Infrastructure/Doctrine/EntityManagerTransactionManager.php
• src/Data/Infrastructure/SymfonyEventDispatcherBridge.php

1.10. Data-Layer (Konkrete Implementierung)

src/Data/Essen/
├── Entity/DishEntity.php          // #[ORM\Entity] – Doctrine, Attribute erlaubt!
├── Provider/DishProvider.php      // implementiert DishProviderInterface
├── Processor/DishProcessor.php    // implementiert DishProcessorInterface
├── Mapper/DishMapper.php          // toModel / createEntity / updateEntity
└── HistoryProvider/DishHistoryProvider.php // (optional, für Inspiration)

src/Data/Infrastructure/
├── Doctrine/EntityManagerTransactionManager.php
└── SymfonyEventDispatcherBridge.php

Doctrine Entity (DishEntity):

#[ORM\Entity, ORM\Table(name: 'essens_dishes')]
class DishEntity
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\Column(type: 'string', length: 255)]
    private string $name = '';
    // (notiz, wochentage (set), sort_order, status, gegessen_am, timestamps)

    // nur Getter/Setter, keine Logik
}

Mapper (stateless):

• toModel(DishEntity): Dish
• createEntity(Dish): DishEntity
• updateEntity(Dish, DishEntity): void

Processor (Write):

readonly class DishProcessor implements DishProcessorInterface
{
    public function __construct(
        private EntityManagerInterface $em,
        private DishMapper $mapper,
    ) {}

    public function create(Dish $model): Dish {
        $entity = $this->mapper->createEntity($model);
        $this->em->persist($entity);
        $this->em->flush();
        return $this->mapper->toModel($entity);  // mit id aus DB
    }

    public function save(Dish $model): Dish {
        $entity = $this->em->getRepository(DishEntity::class)->find($model->id);
        if ($entity === null) throw new DishNotFoundException($model->id);
        $this->mapper->updateEntity($model, $entity);
        $this->em->flush();
        return $model;
    }
    // ...
}

1.11. UI-Layer

src/UI/Http/Essen/
├── DishController.php           // CRUD, toggle, move (sort_order)
├── InspirationController.php    // 5er-Batch
├── TodayController.php          // optional: HA-Consumer (GET /api/today)
└── ExceptionSubscriber.php      // zentrales Domain-Exception → HTTP-Mapping

src/UI/Twig/                     // Twig-Templates (htmx-Fragmente)
├── dish/
│   ├── index.html.twig          // Planungsliste + Archiv-Tab
│   ├── form.html.twig           // Erstellen/Bearbeiten
│   └── item.html.twig           // Eintrag (li) – SortableJS
├── inspiration/
│   └── panel.html.twig
└── layout/base.html.twig

htmx wird als statische Datei ausgeliefert (public/js/htmx.min.js, public/js/sortable.min.js) und in layout eingeblendet. Kein Build-Step.

Antwort-Vertrag (htmx):

• Alle Writes geben ein HTML-Fragment zurück (aktualisierte Liste/Tab), oder Hix-Response-Header: HX-Reswap` etc. für Fragment-Austausch.
• Für API-Consumer (HA) parallel ein JSON-Endpunkt GET /api/today.

1.12. Testing

tests/
├── Unit/Logic/                  // Pure PHP, ohne Kernel (schnell)
│   ├── Essen/Model/DishTest.php
│   ├── Essen/UseCase/CreateDishUseCaseTest.php
│   ├── Essen/Query/InspirationQueryTest.php  // mit gemocktem Provider
│   └── Essen/Mapping/DishModelFactoryTest.php
├── Integration/Data/            // Test-Env + SQLite (oder in-memory)
│   ├── Essen/DishProviderTest.php
│   ├── Essen/DishProcessorTest.php
│   └── Essen/DishMapperTest.php
├── Functional/UI/               // Symfony WebTestCase, isolierte Endpunkte
│   ├── Essen/DishControllerTest.php
│   └── Essen/ExceptionSubscriberTest.php
└── Functional/Scenarios/        // User-Flows
    └── EssenDishLifecycleTest.php   // create → toggle → archive → restore

Mocking-Richtlinien (aus Referenz Sektion 13):

• Mocke Interface, nie die konkrete Implementierung.
• Mocke kein Business-Model/DTO (eigentlich instanziert).
• Mocke keine 3rd-Party-Libs; brüche in Interfaces.

2. Directory Structure (End-to-End)

svc-essensplanung/
├── bin/
│   └── console
├── config/
│   ├── bundles.php
│   ├── packages/
│   │   ├── doctrine.yaml
│   │   ├── framework.yaml
│   │   └── routing.yaml
│   ├── routes/
│   │   ├── essen.yaml
│   │   └── api.yaml        # /api/today (HA-Consumer)
│   ├── services.yaml        # (fast nur auto-wire, wenige explizite)
│   └── inspiration_settings.yaml   // w_slow/w_rare/w_hot (ADR-006)
├── docker/
│   └── prod_entrypoint.sh
├── public/
│   ├── index.php
│   ├── js/htmx.min.js
│   ├── js/sortable.min.js
│   └── images/icon.svg      // PWA
├── src/
│   ├── Logic/
│   │   ├── Common/
│   │   │   ├── Exception/ (6 Klassen, s. 1.8)
│   │   │   ├── TransactionManagerInterface.php
│   │   │   └── EventDispatcherInterface.php
│   │   └── Essen/
│   │       ├── Model/ (Dish, DishDay, DishStatus)
│   │       ├── Dto/ (10 Dateien)
│   │       ├── UseCase/ (5)
│   │       ├── Query/ (4)
│   │       ├── Manager/ (interface + impl)
│   │       ├── DishProviderInterface.php
│   │       ├── DishProcessorInterface.php
│   │       ├── Mapping/DishModelFactory.php
│   │       └── Event/DishCreatedEvent.php, DishArchivedEvent.php, ...
│   ├── Data/
│   │   ├── Infrastructure/
│   │   │   ├── Doctrine/EntityManagerTransactionManager.php
│   │   │   └── SymfonyEventDispatcherBridge.php
│   │   └── Essen/
│   │       ├── Entity/DishEntity.php
│   │       ├── Provider/DishProvider.php
│   │       ├── Processor/DishProcessor.php
│   │       ├── Mapper/DishMapper.php
│   │       └── HistoryProvider/DishHistoryProvider.php
│   └── UI/
│       ├── Http/Essen/ (3 Controllers + ExceptionSubscriber)
│       └── Twig/ (Layout + Fragmente)
├── templates/                 // (oder src/UI/Twig – siehe oben)
├── migrations/                // (Doctrine Migrations, Auto-Gen)
├── tests/
├── public/js/htmx.min.js
├── public/js/sortable.min.js
├── docker-compose.yaml        // FrankenPHP + Volume /db
├── Dockerfile
├── .env.dist
├── composer.json
├── symfony.lock
├── phpunit.xml
└── README.md

3. Dependency Graph (konkret)

UI: DishController
  -> Logic: CreateDishUseCase
  -> Logic: MoveDishUseCase
  -> Logic: ToggleDishStatusUseCase
  -> Logic: ListDishesQuery
  -> Logic: InspirationQuery
  -> Logic DTOs (CreateDishRequest, MoveDishRequest, ...)

Logic: CreateDishUseCase
  -> Logic: Common TransactionManagerInterface
  -> Logic: Essen DishManagerInterface
  -> Logic: Essen Mapping/DishModelFactory
  -> Logic: Common EventDispatcherInterface
  -> Logic: Essen/Event DishCreatedEvent

Logic: DishManager
  -> Logic: Essen DishProviderInterface   (Read)
  -> Logic: Essen DishProcessorInterface  (Write)

Data: DishProvider implements Logic:DishProviderInterface
Data: DishProcessor implements Logic:DishProcessorInterface
Data: DishMapper   (Entity <-> Model, stateless)
Data: EntityManagerTransactionManager  implements Logic:Common TransactionManagerInterface
Data: SymfonyEventDispatcherBridge     implements Logic:Common EventDispatcherInterface

4. Konventionen für neue Module/Features

1. Neue Domäne: Neues Ordner-Paar src/Logic/{Modul} + src/Data/{Modul} (gleicher Name, z. B. Einkaufsliste).
2. Neues Business-Model: Model-Ordner, eigene Manager-/Provider-/-Processor, eigene Exceptions, eigenes *ModelFactory.
3. Neuer UseCase: Immer unter src/Logic/{Modul}/{Feature}/UseCase/, DTOs im Dto/, Read in Query/.
4. Neue Schnittstelle (Provider/Processor): Interface in Logic, Implementation in Data; Autowiring via Symfony (nichts in services.yaml, es sei denn mehrere Implementierungen).
5. Neue Business-Regel: Im Model-Konstruktor oder in einer State-Transition- Methode – nie im UseCase, wenn sie das Model selbst betrifft.
6. Neue Konsole/CLI: src/UI/Console/, UseCase-Delegation wie HTTP.
7. Neues Event: In src/Logic/{Modul}/{Feature}/Event/, DTO-Struktur, State-Carry (nur was der Subscriber braucht), kein ORM-Wissen.
8. Testing: Jede Unit in tests/Unit/{Modul}/, je Layer ein Testfall. Kein Mock auf konkrete Klassen.

5. Anti-Pattern (bewusst vermieden)

• ❌ Symfony-Validator-Constraints auf Logik-DTOs.
• ❌ EntityManagerInterface in der Logik-Layer.
• ❌ Doctrine-Entities als Rückgabewert aus der Logic-Layer.
• ❌ HTTP-Header/Routing-Knowledge in der Logik-Layer.
• ❌ Try-catch in jedem Controller (zentraler Exception-Subscriber).
• ❌ Anemic-Entities in der Data-Layer, die die Geschäftsregeln tragen.
• ❌ Mehrere Implementierungen eines Interfaces ohne explizite Bindung in services.yaml (Ambiguität).
• ❌ „Service" als catch-all-Name (immer UseCase/Query/Manager).

6. Offene / Phase-2-Punkte

• settings.yaml für Inspiration-Gewichte (ADR-006). Default 0.5/0.3/0.2.
• DishHistoryProvider konkret (für Inspiration, zählt Auftritte pro Name).
• GET /api/today für HA-Consumer (Phase 2, ADR-004).
• Optional: Push-Benachrichtigung per HA-Notify (Phase 2).
• Optional: Cache-Aside im DishManager (vorerst ohne, Phase 2).