feat(api): Hub batch print endpoint + slug + hangar templates for Hangar integration

backend/alembic/versions/a0516c04278c_add_print_batches_table.py

@@ -0,0 +1,47 @@
+"""add print_batches table
+
+Revision ID: a0516c04278c
+Revises: da865401716d
+Create Date: 2026-05-30 15:18:58.348408
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a0516c04278c'
+down_revision: Union[str, Sequence[str], None] = 'da865401716d'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('print_batches',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('printer_id', sa.Uuid(), nullable=False),
+    sa.Column('job_ids', sa.JSON(), nullable=True),
+    sa.Column('created_by', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['printer_id'], ['printers.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_print_batches_created_at'), 'print_batches', ['created_at'], unique=False)
+    op.create_index(op.f('ix_print_batches_created_by'), 'print_batches', ['created_by'], unique=False)
+    op.create_index(op.f('ix_print_batches_printer_id'), 'print_batches', ['printer_id'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_print_batches_printer_id'), table_name='print_batches')
+    op.drop_index(op.f('ix_print_batches_created_by'), table_name='print_batches')
+    op.drop_index(op.f('ix_print_batches_created_at'), table_name='print_batches')
+    op.drop_table('print_batches')
+    # ### end Alembic commands ###

backend/alembic/versions/da865401716d_add_printer_slug_column.py

@@ -0,0 +1,42 @@
+"""add printer slug column
+
+Revision ID: da865401716d
+Revises: 20260518_phase7c_pat_prefix
+Create Date: 2026-05-30 15:03:06.420359
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "da865401716d"
+down_revision: str | Sequence[str] | None = "20260518_phase7c_pat_prefix"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "printers",
+        sa.Column(
+            "slug",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="",
+        ),
+    )
+    # Backfill aus name: existierende Drucker erhalten einen slug
+    op.execute(
+        "UPDATE printers SET slug = LOWER(REPLACE(name, ' ', '-')) WHERE slug = ''"
+    )
+    op.create_index(op.f("ix_printers_slug"), "printers", ["slug"], unique=True)
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index(op.f("ix_printers_slug"), table_name="printers")
+    op.drop_column("printers", "slug")

backend/app/api/routes/batch.py

@@ -0,0 +1,88 @@
+"""POST /api/print/{printer_key}/batch — best-effort batch print."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Request, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import AuthContext
+from app.auth.scope_deps import require_print
+from app.db.session import get_session
+from app.models.print_batch import PrintBatch
+from app.printer_backends.exceptions import (
+    PrinterCoverOpenError,
+    PrinterOfflineError,
+    SnmpQueryError,
+)
+from app.repositories import print_batches as batches_repo
+from app.repositories import printers as printers_repo
+from app.schemas.print_batch import BatchRequest, BatchResponse
+from app.services.batch_dispatch import dispatch_batch
+
+# SessionDep locally — Hub has no central app/api/deps.py module.
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+# prefix=/api → POST /api/print/{...}/batch. print.py has no prefix
+# (POST /print), so this is a clean separation.
+router = APIRouter(prefix="/api")
+
+_SYNC_ERROR_MAP: dict[type[Exception], str] = {
+    PrinterOfflineError:   "printer_offline",
+    PrinterCoverOpenError: "printer_cover_open",
+    SnmpQueryError:        "snmp_error",
+}
+
+
+@router.post(
+    "/print/{printer_key}/batch",
+    status_code=status.HTTP_202_ACCEPTED,
+    response_model=BatchResponse,
+    tags=["print"],
+    summary="Submit a batch of print jobs",
+    description=(
+        "Best-effort batch print. Validates each item individually and "
+        "returns per-item errors. Hardware preconditions (printer_offline, "
+        "cover_open) reject the entire batch with 409."
+    ),
+)
+async def create_batch(
+    printer_key: Annotated[str, Path(description="Printer slug or UUID")],
+    body: BatchRequest,
+    http: Request,
+    session: SessionDep,
+    auth: Annotated[AuthContext, Depends(require_print)],
+) -> BatchResponse:
+    # 1. Resolve printer
+    printer = await printers_repo.resolve_by_slug_or_uuid(session, printer_key)
+    if printer is None:
+        raise HTTPException(404, detail={"error_code": "printer_not_found"})
+
+    # 2. Best-effort dispatch
+    service = http.app.state.print_service
+    try:
+        job_ids, errors = await dispatch_batch(service, body.items)
+    except (PrinterOfflineError, PrinterCoverOpenError, SnmpQueryError) as exc:
+        raise HTTPException(409, detail={
+            "error_code": _SYNC_ERROR_MAP[type(exc)],
+            "error_message": str(exc),
+        })
+
+    # 3. Persist tracking row
+    # auth.subject_id does NOT exist — use api_key_id or source
+    created_by = str(auth.api_key_id) if auth.api_key_id else auth.source
+    batch_row = PrintBatch(
+        printer_id=printer.id,
+        job_ids=job_ids,
+        created_by=created_by,
+    )
+    await batches_repo.create(session, batch_row)
+
+    return BatchResponse(
+        batch_id=batch_row.id,
+        printer_id=printer.id,
+        queued_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+        job_ids=job_ids,
+        errors=errors,
+    )

backend/app/api/routes/printers.py

@@ -28,7 +28,7 @@
 from typing import Annotated, Any
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.auth.dependencies import AuthContext, check_printer_access
@@ -80,12 +80,28 @@ async def _get_printer_or_404(session: AsyncSession, printer_id: UUID) -> Any:
     summary="List all printers",
     description=(
         "Returns every registered printer.  The ``paused`` flag is joined "
-        "from ``printer_state``; it is ``false`` when no state row exists yet."
+        "from ``printer_state``; it is ``false`` when no state row exists yet.  "
+        "Pass ``?slug=<slug>`` to filter to a single printer by exact slug match "
+        "(returns 404 when no printer with that slug exists)."
     ),
 )
-async def list_printers(session: SessionDep, _auth: ReadAuthDep) -> list[PrinterRead]:
-    """List all printers with their pause state."""
-    printers = await printers_repo.list_all(session)
+async def list_printers(
+    session: SessionDep,
+    _auth: ReadAuthDep,
+    slug: Annotated[str | None, Query(description="Filter by exact slug")] = None,
+) -> list[PrinterRead]:
+    """List all printers with their pause state, optionally filtered by slug."""
+    if slug is not None:
+        printer = await printers_repo.get_by_slug(session, slug)
+        if printer is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={"error_code": "printer_not_found",
+                        "error_message": f"slug={slug!r} not found"},
+            )
+        printers = [printer]
+    else:
+        printers = await printers_repo.list_all(session)
     result: list[PrinterRead] = []
     for p in printers:
         state = await printer_state_repo.get(session, p.id)
@@ -94,6 +110,7 @@ async def list_printers(session: SessionDep, _auth: ReadAuthDep) -> list[Printer
             PrinterRead(
                 id=p.id,
                 name=p.name,
+                slug=p.slug,
                 model=p.model,
                 backend=p.backend,
                 connection=dict(p.connection),

backend/app/main.py

@@ -75,6 +75,7 @@
 import app.integrations as _integrations_init  # triggers integration plugin discovery
 from app import __version__
 from app.api.error_handlers import register_error_handlers
+from app.api.routes import batch as batch_routes
 from app.api.routes import events as events_routes
 from app.api.routes import jobs as jobs_routes
 from app.api.routes import lookup as lookup_routes
@@ -595,6 +596,7 @@ async def readiness(
 
     register_error_handlers(app)
     app.include_router(print_router)
+    app.include_router(batch_routes.router)
     app.include_router(events_routes.router)
     app.include_router(printers_routes.router)
     app.include_router(templates_routes.router)

backend/app/models/__init__.py

@@ -7,6 +7,7 @@
 from app.models.api_key import ApiKey
 from app.models.job import Job, JobState
 from app.models.preset import Preset
+from app.models.print_batch import PrintBatch
 from app.models.printer import Printer
 from app.models.printer_state import PrinterState
 from app.models.printer_status_cache import PrinterStatusCache
@@ -17,6 +18,7 @@
     "Job",
     "JobState",
     "Preset",
+    "PrintBatch",
     "Printer",
     "PrinterState",
     "PrinterStatusCache",

backend/app/models/print_batch.py

@@ -0,0 +1,21 @@
+"""SQLModel table für print_batches — Tracking-Aggregat für Batch-Druckaufträge."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import JSON, DateTime
+from sqlmodel import Column, Field, SQLModel
+
+
+class PrintBatch(SQLModel, table=True):
+    __tablename__ = "print_batches"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    printer_id: UUID = Field(index=True, foreign_key="printers.id")
+    job_ids: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    created_by: str = Field(index=True, description="SSO-Email oder API-Key-ID")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False, index=True),
+    )

backend/app/models/printer.py

@@ -15,6 +15,9 @@ class Printer(SQLModel, table=True):
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
     name: str = Field(index=True, unique=True)
+    slug: str = Field(default="", index=True, unique=True,
+                      description="Stable URL-safe identifier (e.g., 'brother-p750w'). "
+                                  "Defaults to slugified name on init.")
     model: str
     backend: str
     connection: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))

backend/app/repositories/print_batches.py

@@ -0,0 +1,44 @@
+"""CRUD für PrintBatch-Aggregat."""
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import col
+
+from app.models.print_batch import PrintBatch
+
+
+async def create(session: AsyncSession, batch: PrintBatch) -> PrintBatch:
+    session.add(batch)
+    await session.commit()
+    await session.refresh(batch)
+    return batch
+
+
+async def get(session: AsyncSession, batch_id: UUID) -> PrintBatch | None:
+    return await session.get(PrintBatch, batch_id)
+
+
+async def list_recent(session: AsyncSession, hours: int = 24) -> list[PrintBatch]:
+    since = datetime.now(UTC) - timedelta(hours=hours)
+    result = await session.execute(
+        select(PrintBatch)
+        .where(col(PrintBatch.created_at) >= since)
+        .order_by(col(PrintBatch.created_at).desc())
+    )
+    return list(result.scalars())
+
+
+async def prune_older_than(session: AsyncSession, hours: int = 24) -> int:
+    cutoff = datetime.now(UTC) - timedelta(hours=hours)
+    result = await session.execute(
+        select(PrintBatch).where(col(PrintBatch.created_at) < cutoff)
+    )
+    rows = list(result.scalars())
+    for row in rows:
+        await session.delete(row)
+    await session.commit()
+    return len(rows)

backend/app/repositories/printers.py

@@ -34,3 +34,23 @@ async def create(session: AsyncSession, printer: Printer) -> Printer:
     await session.commit()
     await session.refresh(printer)
     return printer
+
+
+async def get_by_slug(session: AsyncSession, slug: str) -> Printer | None:
+    """Lookup nach slug. None wenn nicht vorhanden."""
+    result = await session.execute(
+        select(Printer).where(col(Printer.slug) == slug)
+    )
+    return result.scalar_one_or_none()
+
+
+async def resolve_by_slug_or_uuid(session: AsyncSession, key: str) -> Printer | None:
+    """Akzeptiert Slug-String ODER UUID-String. UUID hat Vorrang (Performance)."""
+    try:
+        uuid_obj = UUID(key)
+        printer = await get(session, uuid_obj)
+        if printer is not None:
+            return printer
+    except ValueError:
+        pass
+    return await get_by_slug(session, key)