feat(services): best-effort batch dispatcher

Pro-Item-Fehler → BatchError-Liste. Hardware-Vorbedingungen
(printer_offline, cover_open) sind batch-fatal und propagieren.

Refs strausmann/hangar#78

Author: strausmann

backend/app/services/batch_dispatch.py

@@ -0,0 +1,68 @@
+"""Best-effort Batch-Dispatcher: validiert + queued pro Item, sammelt Errors."""
+from __future__ import annotations
+
+import logging
+
+from app.printer_backends.exceptions import (
+    PrinterCoverOpenError,
+    PrinterOfflineError,
+    SnmpQueryError,
+    TapeEmptyError,
+    TapeMismatchError,
+)
+from app.schemas.print_batch import BatchError
+from app.schemas.print_request import PrintRequest
+from app.services.lookup_service import LookupFailedError
+from app.services.template_loader import TemplateNotFoundError
+
+_log = logging.getLogger(__name__)
+
+# Per-item errors → collected into BatchError list (best-effort)
+_PER_ITEM_ERRORS: dict[type[Exception], str] = {
+    TemplateNotFoundError: "template_not_found",
+    LookupFailedError:     "integration_lookup_failed",
+    TapeMismatchError:     "tape_mismatch",
+    TapeEmptyError:        "tape_empty",
+}
+
+# Hardware preconditions → propagate (caller returns 409)
+_BATCH_FATAL_ERRORS: tuple[type[Exception], ...] = (
+    PrinterCoverOpenError,
+    PrinterOfflineError,
+    SnmpQueryError,
+)
+
+
+async def dispatch_batch(
+    service,                          # PrintService (duck-typed)
+    items: list[PrintRequest],
+) -> tuple[list[str], list[BatchError]]:
+    """Queue each item individually. Collect per-item errors.
+    Hardware errors propagate."""
+    job_ids: list[str] = []
+    errors: list[BatchError] = []
+
+    for index, item in enumerate(items):
+        try:
+            job_id = await service.submit_print_job(item)
+            job_ids.append(str(job_id))
+        except _BATCH_FATAL_ERRORS:
+            raise
+        except tuple(_PER_ITEM_ERRORS) as exc:
+            code = _PER_ITEM_ERRORS[type(exc)]
+            detail = None
+            if isinstance(exc, TapeMismatchError):
+                detail = {"expected_mm": exc.expected_mm,
+                          "loaded_mm": exc.loaded_mm}
+            errors.append(BatchError(
+                index=index, error_code=code,
+                error_message=str(exc), error_detail=detail,
+            ))
+        except Exception as exc:  # unknown sync failure
+            _log.exception("unexpected error in batch item %d", index)
+            errors.append(BatchError(
+                index=index, error_code="internal_error",
+                error_message=str(exc),
+            ))
+
+    return job_ids, errors

backend/tests/unit/test_batch_dispatch.py

@@ -0,0 +1,49 @@
+"""Unit-Tests für den Batch-Dispatcher (best-effort, pro-Item-Validation)."""
+from __future__ import annotations
+
+from uuid import uuid4
+
+import pytest
+
+from app.schemas.print_batch import BatchError
+from app.schemas.print_request import PrintRequest, RawLabelData
+from app.services.batch_dispatch import dispatch_batch
+from app.services.template_loader import TemplateNotFoundError
+
+
+class _FakePrintService:
+    def __init__(self, fail_at: dict[int, type[Exception]] | None = None):
+        self.fail_at = fail_at or {}
+        self.calls = 0
+
+    async def submit_print_job(self, req: PrintRequest):
+        idx = self.calls
+        self.calls += 1
+        if idx in self.fail_at:
+            raise self.fail_at[idx]("simulated")
+        return str(uuid4())
+
+
+def _item(template_id="hangar-furniture-12mm"):
+    return PrintRequest(template_id=template_id,
+                        data=RawLabelData(title="t", primary_id="p", qr_payload="q"))
+
+
+@pytest.mark.asyncio
+async def test_dispatch_all_succeed():
+    service = _FakePrintService()
+    items = [_item() for _ in range(3)]
+    job_ids, errors = await dispatch_batch(service, items)
+    assert len(job_ids) == 3
+    assert errors == []
+
+
+@pytest.mark.asyncio
+async def test_dispatch_partial_failure_keeps_going():
+    service = _FakePrintService(fail_at={1: TemplateNotFoundError})
+    items = [_item(), _item("typo"), _item()]
+    job_ids, errors = await dispatch_batch(service, items)
+    assert len(job_ids) == 2
+    assert len(errors) == 1
+    assert errors[0].index == 1
+    assert errors[0].error_code == "template_not_found"