fix(queue): stop() persistiert PRINTING-Jobs als FAILED in DB

Schließt Spec-Errata C2 und Code-Quality-Finding C-1.
Plus Header-Docstring Phase-2-aktualisiert und __init__ Docstring
zur store-Optional-Entscheidung ergänzt.

Refs #93

Author: strausmann

backend/app/services/print_queue.py

@@ -1,11 +1,13 @@
-"""Per-printer async work queue.
+"""Per-printer async work queue mit Persistierungs-Boundary.
 
 Brother PT/QL printers expose TCP/9100 as a single-stream channel — there is
 no on-device multi-job queue. The hub serialises jobs per printer by running
 one asyncio worker task per printer and feeding it from an asyncio.Queue.
 
-Jobs live in-memory (MVP). Phase 5 will add SQLite persistence behind a
-JobStore protocol that this module will accept by dependency injection.
+In-Memory dataclass `Job` Instanzen (mit image_payload bytes und
+asyncio.Event) leben in `_jobs` während des Worker-Loops. Parallel
+persistiert der `JobStore` die SQLModel-Job-Rows in SQLite — siehe
+`app/services/job_store.py` (Phase 2).
 
 Internal dependency note: the worker reads `job._done_event` (a private field
 on `Job`) to signal completion to `wait_for_job`. `PrintQueue` and
@@ -137,6 +139,19 @@ def __init__(
         on_state_change: _StateChangeCallback | None = None,
         store: JobStore | None = None,
     ) -> None:
+        """Konstruktor.
+
+        Args:
+            printers: Liste der Drucker-Objekte (jeder mit ``id`` UUID und
+                ``print_image`` Coroutine-Methode).
+            on_state_change: Optionaler Callback für SSE-Events. Wird nach
+                jeder Job-State-Transition aufgerufen; None deaktiviert das
+                Callback ohne sonstige Seiteneffekte.
+            store: JobStore für DB-Persistierung der Job-Transitionen.
+                Default ist ``MemoryJobStore()`` für Backward-Compat mit
+                Pre-Phase-2-Tests — Production-Code wired in Lifespan
+                explizit ``SQLiteJobStore`` ein (Task 9).
+        """
         self._on_state_change = on_state_change
         self._store: JobStore = store if store is not None else MemoryJobStore()
         self._printers: dict[UUID, _PrinterLike] = {p.id: p for p in printers}
@@ -222,6 +237,7 @@ async def stop(self, timeout_s: float = 30.0) -> None:
                 job.error_msg = job.error_message  # keep legacy field in sync (see line 466)
                 try:
                     JobStateMachine.transition(job, JobState.FAILED)
+                    await self._store.mark_failed(UUID(job.id), "shutdown")
                 except InvalidStateTransitionError:
                     # Defensive: job already moved to a terminal state by the
                     # worker — just ensure _done_event is set.

backend/tests/unit/services/test_print_queue_persistence.py

@@ -93,3 +93,57 @@ async def test_printqueue_calls_mark_failed_on_printer_error() -> None:
     actual_uuid = store.mark_failed.call_args.args[0]
     assert actual_uuid == expected_uuid
     store.mark_done.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_stop_marks_inflight_jobs_as_failed_in_db() -> None:
+    """stop() muss PRINTING-Jobs per store.mark_failed(id, 'shutdown') in DB persistieren.
+
+    Spec-Errata C2: Der In-Memory-Zustand wurde bereits vor diesem Fix korrekt
+    auf FAILED gesetzt — aber der DB-Store-Aufruf fehlte (C-1 Fix).
+    Dieser Test verifiziert dass stop() await self._store.mark_failed(UUID(job.id), 'shutdown')
+    aufruft wenn ein Job beim Shutdown noch in PRINTING war.
+    """
+    import asyncio
+
+    store = AsyncMock(spec=MemoryJobStore)
+
+    # Printer der nie fertig wird — blockiert den Worker im print_image-Aufruf
+    # bis der Test stop() aufruft und der Task gecancelled wird.
+    printer = _make_printer()
+
+    async def _blocking_print(*_args: object, **_kwargs: object) -> None:
+        await asyncio.sleep(60)  # blockiert bis CancelledError via stop()
+
+    printer.print_image = _blocking_print  # type: ignore[assignment]
+
+    queue = PrintQueue(printers=[printer], store=store)
+    await queue.start()
+
+    job_id = await queue.submit(_PRINTER_ID, _sample_image(), tape_mm=12)
+
+    # Kurz warten bis der Worker den Job in PRINTING übernommen hat.
+    from app.services.job_lifecycle import JobState as InMemState
+    for _ in range(50):
+        job = await queue.get(job_id)
+        if job.state == InMemState.PRINTING:
+            break
+        await asyncio.sleep(0.05)
+    else:
+        pytest.fail("Job erreichte PRINTING-State nicht innerhalb der Wartezeit")
+
+    # stop() soll den Worker cancellen und dann PRINTING→FAILED + mark_failed aufrufen.
+    await queue.stop(timeout_s=0.1)
+
+    # Verifizierung: mark_failed muss mit der richtigen UUID und error='shutdown' aufgerufen worden sein.
+    expected_uuid = UUID(job_id)
+    # mark_failed kann mehrfach aufgerufen werden (einmal durch Worker-CancelledError-Pfad
+    # und einmal durch stop()-Cleanup) — mindestens ein Call muss (uuid, 'shutdown') sein.
+    shutdown_calls = [
+        call for call in store.mark_failed.call_args_list
+        if call.args == (expected_uuid, "shutdown")
+    ]
+    assert shutdown_calls, (
+        f"store.mark_failed(UUID(job_id), 'shutdown') wurde nicht aufgerufen. "
+        f"Tatsächliche Calls: {store.mark_failed.call_args_list}"
+    )