M3: Reorder + Inspiration – Schritt 1 (Logik): Reorder-UseCase, Inspiration-Query (ADR-006), Adopt-UseCase + Unit-Tests

2026-09-19 15:57:13 +02:00
parent ce77785003
commit 52a34225fa
11 changed files with 686 additions and 0 deletions
@@ -60,6 +60,16 @@ Status: **final** (2026-09-13, abgestimmt) · Basis: [`anforderungen.md`](anford
 - `SuggestDishes`-Query: Slow 0.5 / Rarität 0.3 / Hotness 0.2 (ADR-006),
  5 Vorschläge + „Weitere 5", 1-Klick-Adopt → `CreateDish` mit Referenz
 - **DoD:** Reorder bleibt nach Reload bestehen; Inspiration klickbar adoptierend
+- *Konkrete Umsetzung (M1-Konvention, Domäne DE):* Schritt 1 (Logik):
+  `MahlzeitReorderUseCase` (neue ID-Reihenfolge → `sortOrder` neu nummerieren,
+  nur geänderte Positionen updaten, `MahlzeitReorderedEvent`),
+  `MahlzeitInspirationQuery` (Kandidaten = Namen mit ≥ 1 `gegessen`-Eintrag,
+  Repräsentant = neuester `gegessen`-Eintrag, Score nach ADR-006 mit
+  Defaults 0.5/0.3/0.2, `ausschluss`-IDs für „Weitere 5", Sortierung
+  absteigend nach Score, bei Gleichstand alphabetisch), `MahlzeitAdoptUseCase`
+  (Quelle → neue `geplant`-Kopie mit `gegessenAm = null`, `MahlzeitAdoptedEvent`).
+  Schritt 2 (UI): Planungsliste mit SortableJS + `POST /mahlzeiten/reorder`,
+  Inspiration-View `GET /inspiration` + `POST /mahlzeiten/{id}/adopt`.

 ### M4 – Härtung & API
 - `X-Api-Token`-Guard (optional, `.env`) für `GET /api/today` (HA-ready)
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\Dto;
+
+/**
+ * Request-DTO: die Reihenfolge der Planungsliste festlegen.
+ *
+ * `reihenfolge` ist die Liste der Mahlzeiten-IDs in der gewünschten
+ * (neuen) Reihenfolge. Die Use-Case-Implementierung nummeriert daraus
+ * `sortOrder` neu (Position 1..N).
+ *
+ * @param list<int> $reihenfolge
+ */
+final class MahlzeitReorderRequest
+{
+    /** @param list<int> $reihenfolge */
+    public function __construct(
+        public readonly array $reihenfolge,
+    ) {
+    }
+}
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\Dto;
+
+use App\Logic\Essen\Model\Mahlzeit;
+use App\Logic\Essen\Model\Wochentag;
+
+/**
+ * Read-Modell eines Inspiration-Vorschlags (ein Gericht aus dem Archiv).
+ *
+ * `score` ist der gewichtete Inspiration-Score (ADR-006), `auftraete` die
+ * Gesamtzahl aller Einträge (geplant + gegessen) mit diesem Namen.
+ *
+ * @param list<Wochentag> $wochentage
+ */
+final class MahlzeitVorschlagResponse
+{
+    public function __construct(
+        public readonly int $id,
+        public readonly string $name,
+        public readonly string $notiz,
+        public readonly array $wochentage,
+        public readonly float $score,
+        public readonly ?\DateTimeImmutable $gegessenAm,
+        public readonly int $auftraete,
+    ) {
+    }
+
+    public static function fromModel(Mahlzeit $m, float $score, int $auftraete): self
+    {
+        return new self(
+            id: $m->id,
+            name: $m->name,
+            notiz: $m->notiz,
+            wochentage: $m->wochentage,
+            score: $score,
+            gegessenAm: $m->gegessenAm,
+            auftraete: $auftraete,
+        );
+    }
+}
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\Event;
+
+/**
+ * Domain-Event: ein Archiv-Gericht wurde per 1-Klick als neuer `geplant`-Eintrag
+ * übernommen (Adopt, nach Commit). `quellId` verweist auf die übernommenen Quelle.
+ */
+final readonly class MahlzeitAdoptedEvent
+{
+    public function __construct(
+        public int $id,
+        public string $name,
+        public int $quellId,
+    ) {
+    }
+}
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\Event;
+
+/**
+ * Domain-Event: die Reihenfolge der Planungsliste wurde geändert (nach Commit).
+ * Trägt die neue ID-Reihenfolge (State-Carry, kein ORM-Wissen).
+ *
+ * @param list<int> $reihenfolge
+ */
+final readonly class MahlzeitReorderedEvent
+{
+    /** @param list<int> $reihenfolge */
+    public function __construct(
+        public array $reihenfolge,
+    ) {
+    }
+}
@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\Query;
+
+use App\Logic\Common\ClockInterface;
+use App\Logic\Essen\Dto\MahlzeitVorschlagResponse;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+use App\Logic\Essen\Model\MahlzeitStatus;
+
+/**
+ * Read-Query: Inspiration (ADR-006).
+ *
+ * Schlägt Gerichte **aus dem Archiv** (mindestens ein `gegessen`-Eintrag) vor,
+ * bewertet nach einem gewichteten Mix:
+ *   score = w_slow  * staleness   (lange nicht gekocht, primär)
+ *         + w_rare  * rarity      (seltene Gerichte, sekundär)
+ *         + w_hot   * popularity  (beliebte Gerichte, tertiär)
+ *
+ * - staleness: `now - letzte_geschmack`, normalisiert an die längste Pause.
+ * - rarity:    `1 / (auftraete + 1)`, auftraete = Anzahl ALLER Einträge (Name).
+ * - popularity: `auftraete / max(auftraete)`.
+ *
+ * `ausschluss` (bereits vorgeschlagene Repräsentanten-IDs) wird übersprungen,
+ * damit "Weitere 5" neue Gerichte liefert. Sortierung absteigend nach Score.
+ */
+final readonly class MahlzeitInspirationQuery
+{
+    public function __construct(
+        private MahlzeitManagerInterface $mahlzeiten,
+        private ClockInterface $clock,
+        private float $gewichtSlow = 0.5,
+        private float $gewichtRare = 0.3,
+        private float $gewichtHot = 0.2,
+    ) {
+    }
+
+    /**
+     * @param list<int> $ausschluss bereits vorgeschlagene Repräsentanten-IDs
+     * @return list<MahlzeitVorschlagResponse>
+     */
+    public function execute(int $limit = 5, array $ausschluss = []): array
+    {
+        $alle = $this->mahlzeiten->list(null);
+        if ($alle === []) {
+            return [];
+        }
+
+        $jetzt = $this->clock->now();
+
+        /** @var array<string, array{letzte: ?\DateTimeImmutable, anzahl: int, repraesentant: mixed}> $perName */
+        $perName = [];
+        foreach ($alle as $m) {
+            $e = &$perName[$m->name];
+            if (!isset($e)) {
+                $e = ['letzte' => null, 'anzahl' => 0, 'repraesentant' => $m];
+            }
+            $e['anzahl']++;
+            if ($m->status === MahlzeitStatus::Gegessen && $m->gegessenAm !== null) {
+                if ($e['letzte'] === null || $m->gegessenAm > $e['letzte']) {
+                    $e['letzte'] = $m->gegessenAm;
+                    $e['repraesentant'] = $m;
+                }
+            }
+        }
+        unset($e);
+
+        // Nur Gerichte, die im Archiv stehen (>= 1 gegessener Eintrag).
+        $kandidaten = [];
+        foreach ($perName as $name => $e) {
+            if ($e['letzte'] !== null) {
+                $kandidaten[] = [
+                    'name' => $name,
+                    'letzte' => $e['letzte'],
+                    'anzahl' => $e['anzahl'],
+                    'repraesentant' => $e['repraesentant'],
+                ];
+            }
+        }
+        if ($kandidaten === []) {
+            return [];
+        }
+
+        // Normalisierungs-Maxima.
+        $maxStale = 0;
+        $maxAnzahl = 0;
+        foreach ($kandidaten as $k) {
+            $stale = $jetzt->getTimestamp() - $k['letzte']->getTimestamp();
+            if ($stale > $maxStale) {
+                $maxStale = $stale;
+            }
+            if ($k['anzahl'] > $maxAnzahl) {
+                $maxAnzahl = $k['anzahl'];
+            }
+        }
+
+        $scored = [];
+        foreach ($kandidaten as $k) {
+            $stale = $jetzt->getTimestamp() - $k['letzte']->getTimestamp();
+            $staleness = $maxStale > 0 ? $stale / $maxStale : 0.0;
+            $rarity = 1.0 / ($k['anzahl'] + 1);
+            $popularity = $maxAnzahl > 0 ? $k['anzahl'] / $maxAnzahl : 0.0;
+            $score = $this->gewichtSlow * $staleness + $this->gewichtRare * $rarity + $this->gewichtHot * $popularity;
+            $scored[] = ['k' => $k, 'score' => $score];
+        }
+
+        // Absteigend nach Score; bei Gleichstand alphabetisch (deterministisch).
+        usort($scored, static fn (array $a, array $b): int => $b['score'] <=> $a['score'] ?: strcmp($a['k']['name'], $b['k']['name']));
+
+        $ausschlussSet = array_flip(array_map('intval', $ausschluss));
+        $ergebnis = [];
+        foreach ($scored as $s) {
+            /** @var \App\Logic\Essen\Model\Mahlzeit $repraesentant */
+            $repraesentant = $s['k']['repraesentant'];
+            if (isset($ausschlussSet[$repraesentant->id])) {
+                continue;
+            }
+            $ergebnis[] = MahlzeitVorschlagResponse::fromModel($repraesentant, $s['score'], (int) $s['k']['anzahl']);
+            if (\count($ergebnis) >= $limit) {
+                break;
+            }
+        }
+
+        return $ergebnis;
+    }
+}
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\UseCase;
+
+use App\Logic\Common\ClockInterface;
+use App\Logic\Common\EventDispatcherInterface;
+use App\Logic\Common\TransactionManagerInterface;
+use App\Logic\Essen\Dto\MahlzeitCreateRequest;
+use App\Logic\Essen\Dto\MahlzeitResponse;
+use App\Logic\Essen\Event\MahlzeitAdoptedEvent;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+use App\Logic\Essen\Mapping\MahlzeitFactory;
+
+/**
+ * Use-Case: ein Gericht (z. B. aus dem Archiv) per 1-Klick als NEUEN
+ * `geplant`-Eintrag übernehmen (Kopie – `gegessenAm` bleibt leer, neue ID,
+ * am Ende der Planungsliste angehängt).
+ *
+ * Wirft `MahlzeitNotFoundException` (→ 404), wenn die Quelle unbekannt ist.
+ */
+final readonly class MahlzeitAdoptUseCase
+{
+    public function __construct(
+        private TransactionManagerInterface $tx,
+        private MahlzeitManagerInterface $mahlzeiten,
+        private MahlzeitFactory $factory,
+        private EventDispatcherInterface $events,
+        private ClockInterface $clock,
+    ) {
+    }
+
+    public function execute(int $quellId): MahlzeitResponse
+    {
+        $quelle = $this->mahlzeiten->find($quellId);
+
+        $req = new MahlzeitCreateRequest(
+            name: $quelle->name,
+            notiz: $quelle->notiz,
+            wochentage: $quelle->wochentage,
+        );
+        $mahlzeit = $this->factory->createFromCreateRequest($req, $this->clock->now());
+
+        $gespeichert = $this->tx->execute(fn () => $this->mahlzeiten->create($mahlzeit));
+
+        $this->events->dispatch(new MahlzeitAdoptedEvent(id: $gespeichert->id, name: $gespeichert->name, quellId: $quellId));
+
+        return MahlzeitResponse::fromModel($gespeichert);
+    }
+}
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logic\Essen\UseCase;
+
+use App\Logic\Common\EventDispatcherInterface;
+use App\Logic\Common\TransactionManagerInterface;
+use App\Logic\Essen\Dto\MahlzeitReorderRequest;
+use App\Logic\Essen\Event\MahlzeitReorderedEvent;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+
+/**
+ * Use-Case: die Reihenfolge der Planungsliste ändern (Drag & Drop).
+ *
+ * Die übergebene ID-Liste wird in `sortOrder` neu nummeriert (Position 1..N).
+ * Läuft in einer Transaktion; unbekannte IDs werfen `MahlzeitNotFoundException`
+ * (→ 404). Eine leere Liste ist ein No-Op.
+ */
+final readonly class MahlzeitReorderUseCase
+{
+    public function __construct(
+        private TransactionManagerInterface $tx,
+        private MahlzeitManagerInterface $mahlzeiten,
+        private EventDispatcherInterface $events,
+    ) {
+    }
+
+    public function execute(MahlzeitReorderRequest $req): void
+    {
+        $reihenfolge = array_values($req->reihenfolge);
+        if ($reihenfolge === []) {
+            return;
+        }
+
+        $this->tx->execute(function () use ($reihenfolge): void {
+            foreach ($reihenfolge as $position => $id) {
+                $sortOrder = $position + 1;
+                $mahlzeit = $this->mahlzeiten->find($id);
+
+                // Unveränderte Positionen überspringen (keine unnötigen Writes).
+                if ($mahlzeit->sortOrder !== $sortOrder) {
+                    $this->mahlzeiten->update($mahlzeit->mitSortOrder($sortOrder));
+                }
+            }
+        });
+
+        $this->events->dispatch(new MahlzeitReorderedEvent($reihenfolge));
+    }
+}
@@ -0,0 +1,146 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Logic\Essen\Query;
+
+use App\Logic\Common\ClockInterface;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+use App\Logic\Essen\Model\Mahlzeit;
+use App\Logic\Essen\Model\MahlzeitStatus;
+use App\Logic\Essen\Model\Wochentag;
+use App\Logic\Essen\Query\MahlzeitInspirationQuery;
+use PHPUnit\Framework\TestCase;
+
+final class MahlzeitInspirationQueryTest extends TestCase
+{
+    private \DateTimeImmutable $jetzt;
+
+    protected function setUp(): void
+    {
+        $this->jetzt = new \DateTimeImmutable('2026-09-18 00:00:00');
+    }
+
+    private function clock(): ClockInterface
+    {
+        $clock = $this->createStub(ClockInterface::class);
+        $clock->method('now')->willReturn($this->jetzt);
+        return $clock;
+    }
+
+    /** @param list<Mahlzeit> $mahlzeiten */
+    private function manager(array $mahlzeiten): MahlzeitManagerInterface
+    {
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->expects(self::once())->method('list')->with(null)->willReturn($mahlzeiten);
+        return $manager;
+    }
+
+    private function gegessen(int $id, string $name, \DateTimeImmutable $gegessenAm): Mahlzeit
+    {
+        return new Mahlzeit($id, $name, '', [Wochentag::Mo], 1, MahlzeitStatus::Gegessen, $this->jetzt, $this->jetzt, $gegessenAm);
+    }
+
+    private function geplant(int $id, string $name): Mahlzeit
+    {
+        return new Mahlzeit($id, $name, '', [Wochentag::Mo], 1, MahlzeitStatus::Geplant, $this->jetzt, $this->jetzt, null);
+    }
+
+    public function testExecuteLeereListeLiefertKeineVorschlaege(): void
+    {
+        $query = new MahlzeitInspirationQuery($this->manager([]), $this->clock());
+
+        self::assertSame([], $query->execute());
+    }
+
+    public function testExecuteOhneArchivEintraegeKeineVorschlaege(): void
+    {
+        // Nur `geplant` – kein Gericht im Archiv.
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->geplant(1, 'Bolognese'),
+            $this->geplant(2, 'Curry'),
+        ]), $this->clock());
+
+        self::assertSame([], $query->execute());
+    }
+
+    public function testExecuteSortiertAbsteigendNachScoreUndWaehltRepraesentanten(): void
+    {
+        // "Bolognese": gegessen vor 10 Tagen (id 1) + 1 geplanter Eintrag → auftraete 2,
+        //   repraesentant = id 1.
+        // "Curry": gegessen vor 3 Tagen (id 3), auftraete 1.
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->gegessen(1, 'Bolognese', new \DateTimeImmutable('2026-09-08 00:00:00')),
+            $this->geplant(2, 'Bolognese'),
+            $this->gegessen(3, 'Curry', new \DateTimeImmutable('2026-09-15 00:00:00')),
+        ]), $this->clock());
+
+        $vorschlaege = $query->execute();
+
+        self::assertCount(2, $vorschlaege);
+        self::assertSame(1, $vorschlaege[0]->id);
+        self::assertSame('Bolognese', $vorschlaege[0]->name);
+        self::assertSame(2, $vorschlaege[0]->auftraete);
+        self::assertSame(3, $vorschlaege[1]->id);
+        self::assertSame('Curry', $vorschlaege[1]->name);
+        self::assertSame(1, $vorschlaege[1]->auftraete);
+        // Staleness dominiert: das länger nicht gekochte Gericht hat den höheren Score.
+        self::assertGreaterThan($vorschlaege[1]->score, $vorschlaege[0]->score);
+    }
+
+    public function testExecuteWaehltNeuestenGegessenenEintragAlsRepraesentanten(): void
+    {
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->gegessen(1, 'Bolognese', new \DateTimeImmutable('2026-09-01 00:00:00')),
+            $this->gegessen(4, 'Bolognese', new \DateTimeImmutable('2026-09-08 00:00:00')),
+        ]), $this->clock());
+
+        $vorschlaege = $query->execute();
+
+        self::assertCount(1, $vorschlaege);
+        self::assertSame(4, $vorschlaege[0]->id);
+        self::assertEquals(new \DateTimeImmutable('2026-09-08 00:00:00'), $vorschlaege[0]->gegessenAm);
+        self::assertSame(2, $vorschlaege[0]->auftraete);
+    }
+
+    public function testExecuteAusschlussSpruengtBereitsVorgeschlageneGerichte(): void
+    {
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->gegessen(1, 'Bolognese', new \DateTimeImmutable('2026-09-08 00:00:00')),
+            $this->gegessen(3, 'Curry', new \DateTimeImmutable('2026-09-15 00:00:00')),
+        ]), $this->clock());
+
+        // "Weitere 5": Bolognese (id 1) wurde bereits vorgeschlagen.
+        $vorschlaege = $query->execute(5, [1]);
+
+        self::assertCount(1, $vorschlaege);
+        self::assertSame('Curry', $vorschlaege[0]->name);
+    }
+
+    public function testExecuteBemaessErgebnisAnLimit(): void
+    {
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->gegessen(1, 'Bolognese', new \DateTimeImmutable('2026-09-08 00:00:00')),
+            $this->gegessen(2, 'Curry', new \DateTimeImmutable('2026-09-12 00:00:00')),
+            $this->gegessen(3, 'Pasta', new \DateTimeImmutable('2026-09-15 00:00:00')),
+        ]), $this->clock());
+
+        $vorschlaege = $query->execute(2);
+
+        self::assertCount(2, $vorschlaege);
+        self::assertSame(['Bolognese', 'Curry'], array_map(static fn ($v) => $v->name, $vorschlaege));
+    }
+
+    public function testExecuteGleichstandEntscheidetAlphabetisch(): void
+    {
+        // Beide Gerichte: gleiche Pause, gleiche Auftritte → Score-Gleichstand.
+        $query = new MahlzeitInspirationQuery($this->manager([
+            $this->gegessen(1, 'Zwiebelsuppe', new \DateTimeImmutable('2026-09-13 00:00:00')),
+            $this->gegessen(2, 'Apfelkuchen', new \DateTimeImmutable('2026-09-13 00:00:00')),
+        ]), $this->clock());
+
+        $vorschlaege = $query->execute();
+
+        self::assertSame(['Apfelkuchen', 'Zwiebelsuppe'], array_map(static fn ($v) => $v->name, $vorschlaege));
+    }
+}
@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Logic\Essen\UseCase;
+
+use App\Logic\Common\ClockInterface;
+use App\Logic\Common\EventDispatcherInterface;
+use App\Logic\Common\TransactionManagerInterface;
+use App\Logic\Essen\Event\MahlzeitAdoptedEvent;
+use App\Logic\Essen\Exception\MahlzeitNotFoundException;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+use App\Logic\Essen\Mapping\MahlzeitFactory;
+use App\Logic\Essen\Model\Mahlzeit;
+use App\Logic\Essen\Model\MahlzeitStatus;
+use App\Logic\Essen\Model\Wochentag;
+use App\Logic\Essen\UseCase\MahlzeitAdoptUseCase;
+use PHPUnit\Framework\TestCase;
+
+final class MahlzeitAdoptUseCaseTest extends TestCase
+{
+    private function tx(): TransactionManagerInterface
+    {
+        $tx = $this->createStub(TransactionManagerInterface::class);
+        $tx->method('execute')->willReturnCallback(static fn (\Closure $work): mixed => $work());
+        return $tx;
+    }
+
+    private function clock(): ClockInterface
+    {
+        $clock = $this->createStub(ClockInterface::class);
+        $clock->method('now')->willReturn(new \DateTimeImmutable('2026-09-18 12:00:00'));
+        return $clock;
+    }
+
+    public function testExecuteKopiertQuelleAlsNeuenGeplantEintrag(): void
+    {
+        $jetzt = new \DateTimeImmutable('2026-09-18 12:00:00');
+        $quelle = new Mahlzeit(7, 'Bolognese', 'mit Parmesan', [Wochentag::Mo], 3, MahlzeitStatus::Gegessen, $jetzt, $jetzt, $jetzt);
+
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->expects(self::once())->method('find')->with(7)->willReturn($quelle);
+        $manager->expects(self::once())->method('create')->willReturnCallback(function (Mahlzeit $m) {
+            // Neue, geplante Kopie: gleiche Inhalte, aber ohne gegessenAm und ohne ID.
+            self::assertSame('Bolognese', $m->name);
+            self::assertSame('mit Parmesan', $m->notiz);
+            self::assertSame([Wochentag::Mo], $m->wochentage);
+            self::assertSame(MahlzeitStatus::Geplant, $m->status);
+            self::assertNull($m->gegessenAm);
+            self::assertSame(0, $m->sortOrder);
+            self::assertSame(0, $m->id);
+            // Persistenz vergibt die neue ID.
+            return $m->mitId(42);
+        });
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::once())->method('dispatch')->with(
+            self::equalTo(new MahlzeitAdoptedEvent(id: 42, name: 'Bolognese', quellId: 7)),
+        );
+
+        $useCase = new MahlzeitAdoptUseCase($this->tx(), $manager, new MahlzeitFactory(), $events, $this->clock());
+
+        $response = $useCase->execute(7);
+
+        self::assertSame(42, $response->id);
+        self::assertSame('Bolognese', $response->name);
+        self::assertSame(MahlzeitStatus::Geplant, $response->status);
+        self::assertNull($response->gegessenAm);
+    }
+
+    public function testExecuteUnbekannteQuelleWirft404UndLegtNichtsAn(): void
+    {
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->method('find')->willThrowException(new MahlzeitNotFoundException(99));
+        $manager->expects(self::never())->method('create');
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::never())->method('dispatch');
+
+        $useCase = new MahlzeitAdoptUseCase($this->tx(), $manager, new MahlzeitFactory(), $events, $this->clock());
+
+        $this->expectException(MahlzeitNotFoundException::class);
+
+        try {
+            $useCase->execute(99);
+        } finally {
+            // Erwartete Exception oben.
+        }
+    }
+}
@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Logic\Essen\UseCase;
+
+use App\Logic\Common\EventDispatcherInterface;
+use App\Logic\Common\TransactionManagerInterface;
+use App\Logic\Essen\Dto\MahlzeitReorderRequest;
+use App\Logic\Essen\Event\MahlzeitReorderedEvent;
+use App\Logic\Essen\Exception\MahlzeitNotFoundException;
+use App\Logic\Essen\Manager\MahlzeitManagerInterface;
+use App\Logic\Essen\Model\Mahlzeit;
+use App\Logic\Essen\Model\MahlzeitStatus;
+use App\Logic\Essen\UseCase\MahlzeitReorderUseCase;
+use PHPUnit\Framework\TestCase;
+
+final class MahlzeitReorderUseCaseTest extends TestCase
+{
+    private function tx(): TransactionManagerInterface
+    {
+        $tx = $this->createStub(TransactionManagerInterface::class);
+        $tx->method('execute')->willReturnCallback(static fn (\Closure $work): mixed => $work());
+        return $tx;
+    }
+
+    private function mahlzeit(int $id, int $sortOrder): Mahlzeit
+    {
+        $jetzt = new \DateTimeImmutable('2026-09-18 12:00:00');
+        return new Mahlzeit($id, 'Gericht' . $id, '', [], $sortOrder, MahlzeitStatus::Geplant, $jetzt, $jetzt, null);
+    }
+
+    public function testExecuteRenommertSortOrderUndDispatchtEvent(): void
+    {
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->method('find')->willReturnMap([
+            [2, $this->mahlzeit(2, 2)],
+            [1, $this->mahlzeit(1, 1)],
+            [3, $this->mahlzeit(3, 3)],
+        ]);
+
+        $gespeicherte = [];
+        $manager->expects(self::exactly(2))->method('update')->willReturnCallback(function (Mahlzeit $m) use (&$gespeicherte) {
+            $gespeicherte[$m->id] = $m->sortOrder;
+            return $m;
+        });
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::once())->method('dispatch')->with(
+            self::equalTo(new MahlzeitReorderedEvent([2, 1, 3])),
+        );
+
+        $useCase = new MahlzeitReorderUseCase($this->tx(), $manager, $events);
+        $useCase->execute(new MahlzeitReorderRequest([2, 1, 3]));
+
+        // id 2 → Position 1, id 1 → Position 2; id 3 (Position 3) bleibt unverändert.
+        self::assertSame([2 => 1, 1 => 2], $gespeicherte);
+    }
+
+    public function testExecuteSpruengtBereitsKorrektePosition(): void
+    {
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->method('find')->willReturnMap([
+            [1, $this->mahlzeit(1, 1)],
+            [2, $this->mahlzeit(2, 2)],
+        ]);
+        $manager->expects(self::never())->method('update');
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::once())->method('dispatch');
+
+        $useCase = new MahlzeitReorderUseCase($this->tx(), $manager, $events);
+        $useCase->execute(new MahlzeitReorderRequest([1, 2]));
+    }
+
+    public function testExecuteLeereListeIstNoOp(): void
+    {
+        $manager = $this->createMock(MahlzeitManagerInterface::class);
+        $manager->expects(self::never())->method('find');
+        $manager->expects(self::never())->method('update');
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::never())->method('dispatch');
+
+        $useCase = new MahlzeitReorderUseCase($this->tx(), $manager, $events);
+        $useCase->execute(new MahlzeitReorderRequest([]));
+    }
+
+    public function testExecuteUnbekannteIdWirft404(): void
+    {
+        $manager = $this->createStub(MahlzeitManagerInterface::class);
+        $manager->method('find')->willThrowException(new MahlzeitNotFoundException(99));
+
+        $events = $this->createMock(EventDispatcherInterface::class);
+        $events->expects(self::never())->method('dispatch');
+
+        $useCase = new MahlzeitReorderUseCase($this->tx(), $manager, $events);
+
+        $this->expectException(MahlzeitNotFoundException::class);
+
+        try {
+            $useCase->execute(new MahlzeitReorderRequest([99]));
+        } finally {
+            // Erwartete Exception oben.
+        }
+    }
+}