Karte 14 Schritt 2 (Admin-Teil) + Frontend für Anhänger-Kopplung

Backend: geraet_instanz-CRUD (Liste/Anlegen/Status ändern inkl. optionalem
Fehlbestand pro Gerät/Löschen), pruefintervall_monate in Objektposition-
Schemas verdrahtet (Prüfdatum -> naechste_pruefung wird automatisch
berechnet, Monatsrechnung ohne neue Dependency).

Frontend: GeraeteInstanzenListe ersetzt das Einzel-SN-Feld im Admin-Portal
(ObjektPositionenPanel) durch eine Instanz-Liste mit Status/Prüfdatum/
Bemerkung je Exemplar - löst das Karte-14-Kernproblem (mehrere Geräte pro
Position). ObjektSection: Anhänger-Kopplung bei Anlage und nachträglich
änderbar.

Kontroll-Erfassung (PositionCard/KontrollPage) bleibt unverändert - die
komplett neue Erfassungs-UI für geraet_sn (Umsetzungsschritt 4, Karte 14)
ist bewusst nicht Teil dieses Commits.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CVgbozhYmuEhiEJHffRXCV

backend/app/api/v1/api.py

@@ -6,6 +6,7 @@ from app.api.v1.endpoints import (
     dashboard,
     eskalation,
     fehlbestaende,
+    geraet_instanz,
     health,
     historie,
     kontrollen,
@@ -27,4 +28,5 @@ api_router.include_router(kontrollen.router, tags=["kontrollen"])
 api_router.include_router(fehlbestaende.router, tags=["fehlbestaende"])
 api_router.include_router(eskalation.router, tags=["eskalation"])
 api_router.include_router(historie.router, tags=["historie"])
+api_router.include_router(geraet_instanz.router, tags=["geraet_instanz"])
 api_router.include_router(dashboard.router, tags=["dashboard"])

backend/app/api/v1/endpoints/geraet_instanz.py

@@ -0,0 +1,91 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import require_roles
+from app.db.session import get_db
+from app.models.auth import KnotenTyp, RolleTyp, Systemknoten
+from app.models.geraet_instanz import GeraetInstanz
+from app.models.objektposition import Objektposition
+from app.schemas.geraet_instanz import GeraetInstanzCreate, GeraetInstanzRead, GeraetInstanzStatusUpdate
+from app.services.geraet_instanz import aendere_status, erstelle, liste_fuer_position, loesche
+
+router = APIRouter()
+
+_materialverantwortliche = require_roles(
+    RolleTyp.administration, RolleTyp.materialverantwortlicher, RolleTyp.leitungsverantwortlicher
+)
+
+
+async def _hauptserver_id(db: AsyncSession) -> int:
+    result = await db.execute(select(Systemknoten.id).where(Systemknoten.typ == KnotenTyp.haupt))
+    return result.scalar_one()
+
+
+@router.get("/objektpositionen/{position_id}/geraete", response_model=list[GeraetInstanzRead])
+async def liste_geraete(
+    position_id: uuid.UUID, db: AsyncSession = Depends(get_db), _=Depends(_materialverantwortliche)
+) -> list[GeraetInstanz]:
+    return await liste_fuer_position(db, position_id)
+
+
+@router.post(
+    "/objektpositionen/{position_id}/geraete",
+    response_model=GeraetInstanzRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def erstelle_geraet(
+    position_id: uuid.UUID,
+    payload: GeraetInstanzCreate,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_materialverantwortliche),
+) -> GeraetInstanz:
+    """Karte 14: löst objektposition.seriennummer als Einzelfeld ab - beliebig
+    viele Geräte-Exemplare pro Position."""
+    position = await db.get(Objektposition, position_id)
+    if position is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Objektposition nicht gefunden")
+    try:
+        return await erstelle(db, objektposition_id=position_id, seriennummer=payload.seriennummer)
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="Seriennummer an dieser Position bereits vergeben"
+        ) from exc
+
+
+@router.patch("/geraete/{geraet_id}", response_model=GeraetInstanzRead)
+async def aendere_geraet_status(
+    geraet_id: uuid.UUID,
+    payload: GeraetInstanzStatusUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user=Depends(_materialverantwortliche),
+) -> GeraetInstanz:
+    instanz = await db.get(GeraetInstanz, geraet_id)
+    if instanz is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Gerät nicht gefunden")
+
+    zustaendiger_server_id = await _hauptserver_id(db)
+    aktualisiert, _fehlbestand_id = await aendere_status(
+        db,
+        instanz=instanz,
+        status=payload.status,
+        pruefdatum=payload.pruefdatum,
+        bemerkung=payload.bemerkung,
+        erzeuge_fehlbestand=payload.erzeuge_fehlbestand,
+        benutzer_id=current_user.id,
+        zustaendiger_server_id=zustaendiger_server_id,
+    )
+    return aktualisiert
+
+
+@router.delete("/geraete/{geraet_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def loesche_geraet(
+    geraet_id: uuid.UUID, db: AsyncSession = Depends(get_db), _=Depends(_materialverantwortliche)
+) -> None:
+    instanz = await db.get(GeraetInstanz, geraet_id)
+    if instanz is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Gerät nicht gefunden")
+    await loesche(db, instanz)

backend/app/api/v1/endpoints/objekte.py

@@ -106,6 +106,7 @@ async def hole_objektposition_per_code(
         ablaufdatum=position.ablaufdatum,
         chargennummer=position.chargennummer,
         code=position.code,
+        pruefintervall_monate=position.pruefintervall_monate,
     )
 
 
@@ -179,6 +180,7 @@ async def liste_objektpositionen(
             ablaufdatum=p.ablaufdatum,
             chargennummer=p.chargennummer,
             code=p.code,
+            pruefintervall_monate=p.pruefintervall_monate,
         )
         for p in positionen
     ]
@@ -307,6 +309,7 @@ async def aendere_objektposition(
         ablaufdatum=position.ablaufdatum,
         chargennummer=position.chargennummer,
         code=position.code,
+        pruefintervall_monate=position.pruefintervall_monate,
     )
 
 
@@ -351,4 +354,5 @@ async def fuege_zusatzposition_hinzu(
         ablaufdatum=position.ablaufdatum,
         chargennummer=position.chargennummer,
         code=position.code,
+        pruefintervall_monate=position.pruefintervall_monate,
     )

backend/app/schemas/geraet_instanz.py

@@ -0,0 +1,31 @@
+import uuid
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict
+
+from app.models.geraet_instanz import GeraetStatus
+
+
+class GeraetInstanzCreate(BaseModel):
+    seriennummer: str
+
+
+class GeraetInstanzRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: uuid.UUID
+    objektposition_id: uuid.UUID
+    seriennummer: str
+    pruefdatum: date | None
+    naechste_pruefung: date | None
+    status: GeraetStatus
+    bemerkung: str | None
+
+
+class GeraetInstanzStatusUpdate(BaseModel):
+    status: GeraetStatus
+    pruefdatum: date | None = None
+    bemerkung: str | None = None
+    # Karte 14: "pro Gerät entscheidbar" - defekt/in_reparatur kann optional
+    # einen Fehlbestand erzeugen (nutzt bestehende Fehlbestand-Infrastruktur),
+    # muss aber nicht (z.B. Ersatzgerät bereits vorhanden).
+    erzeuge_fehlbestand: bool = False

backend/app/schemas/objekt.py

@@ -52,6 +52,7 @@ class ObjektpositionRead(BaseModel):
     ablaufdatum: date | None
     chargennummer: str | None
     code: str | None
+    pruefintervall_monate: int | None
 
 
 class ObjektpositionUpdate(BaseModel):
@@ -62,6 +63,7 @@ class ObjektpositionUpdate(BaseModel):
     ablaufdatum: date | None = None
     chargennummer: str | None = None
     code: str | None = None
+    pruefintervall_monate: int | None = None
 
 
 class ObjektpositionCreate(BaseModel):

backend/app/services/geraet_instanz.py

@@ -0,0 +1,130 @@
+import calendar
+import uuid
+from datetime import date, datetime, timezone
+from decimal import Decimal
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.fehlbestand import Fehlbestand, FehlbestandStatus
+from app.models.geraet_instanz import GeraetInstanz, GeraetStatus
+from app.models.objekt import Objekt
+from app.models.objektposition import Objektposition
+from app.services import benachrichtigung as benachrichtigung_service
+from app.services import historie as historie_service
+
+
+def _plus_monate(stichtag: date, monate: int) -> date:
+    """Kein python-dateutil als Dependency für eine einzelne Monatsaddition -
+    Tag wird auf das Monatsende gekappt, falls der Zielmonat kürzer ist
+    (z.B. 31. Januar + 1 Monat -> 28./29. Februar)."""
+    monats_index = stichtag.month - 1 + monate
+    jahr = stichtag.year + monats_index // 12
+    monat = monats_index % 12 + 1
+    letzter_tag = calendar.monthrange(jahr, monat)[1]
+    return date(jahr, monat, min(stichtag.day, letzter_tag))
+
+
+async def liste_fuer_position(db: AsyncSession, objektposition_id) -> list[GeraetInstanz]:
+    result = await db.execute(
+        select(GeraetInstanz).where(GeraetInstanz.objektposition_id == objektposition_id)
+    )
+    return list(result.scalars().all())
+
+
+async def erstelle(db: AsyncSession, *, objektposition_id, seriennummer: str) -> GeraetInstanz:
+    instanz = GeraetInstanz(objektposition_id=objektposition_id, seriennummer=seriennummer)
+    db.add(instanz)
+    await db.flush()
+    return instanz
+
+
+async def loesche(db: AsyncSession, instanz: GeraetInstanz) -> None:
+    await db.delete(instanz)
+
+
+async def aendere_status(
+    db: AsyncSession,
+    *,
+    instanz: GeraetInstanz,
+    status: GeraetStatus,
+    pruefdatum: date | None,
+    bemerkung: str | None,
+    erzeuge_fehlbestand: bool,
+    benutzer_id: int,
+    zustaendiger_server_id: int,
+) -> tuple[GeraetInstanz, uuid.UUID | None]:
+    """Karte 14: Status ändern (einsatzbereit/defekt/in_reparatur), optional
+    Prüfung erfassen (naechste_pruefung wird neu berechnet, sofern die
+    Objektposition ein pruefintervall_monate hat), optional einen Fehlbestand
+    erzeugen (pro Gerät entscheidbar, nutzt bestehende Fehlbestand-
+    Infrastruktur statt eigenem Parallel-Konzept)."""
+    alter_status = instanz.status
+    instanz.status = status
+    instanz.bemerkung = bemerkung
+
+    if pruefdatum is not None:
+        instanz.pruefdatum = pruefdatum
+        objektposition = await db.get(Objektposition, instanz.objektposition_id)
+        if objektposition is not None and objektposition.pruefintervall_monate:
+            instanz.naechste_pruefung = _plus_monate(pruefdatum, objektposition.pruefintervall_monate)
+
+    await db.flush()
+
+    await historie_service.log(
+        db,
+        zustaendiger_server_id=zustaendiger_server_id,
+        benutzer_id=benutzer_id,
+        ereignistyp="geraet_status_geaendert",
+        entitaet_typ="geraet_instanz",
+        entitaet_id=instanz.id,
+        alter_wert={"status": alter_status.value},
+        neuer_wert={"status": status.value, "seriennummer": instanz.seriennummer},
+        begruendung=bemerkung,
+    )
+
+    fehlbestand_id = None
+    if erzeuge_fehlbestand and status != GeraetStatus.einsatzbereit:
+        fehlbestand_id = await _erzeuge_fehlbestand(
+            db,
+            instanz=instanz,
+            benutzer_id=benutzer_id,
+            zustaendiger_server_id=zustaendiger_server_id,
+        )
+
+    return instanz, fehlbestand_id
+
+
+async def _erzeuge_fehlbestand(
+    db: AsyncSession, *, instanz: GeraetInstanz, benutzer_id: int, zustaendiger_server_id: int
+):
+    objektposition = await db.get(Objektposition, instanz.objektposition_id)
+    objekt = await db.get(Objekt, objektposition.objekt_id)
+
+    fehlbestand = Fehlbestand(
+        erzeugt_von_server_id=zustaendiger_server_id,
+        objekt_id=objektposition.objekt_id,
+        material_id=objektposition.material_id,
+        standort_id=objekt.standort_id,
+        sollmenge=Decimal(1),
+        istmenge=Decimal(0),
+        fehlmenge=Decimal(1),
+        entstanden_am=datetime.now(timezone.utc),
+        festgestellt_von=benutzer_id,
+        ursache=f"Gerät {instanz.seriennummer} ({instanz.status.value})",
+        status=FehlbestandStatus.offen,
+    )
+    db.add(fehlbestand)
+    await db.flush()
+
+    await historie_service.log(
+        db,
+        zustaendiger_server_id=zustaendiger_server_id,
+        benutzer_id=benutzer_id,
+        ereignistyp="fehlbestand_entstanden",
+        entitaet_typ="fehlbestand",
+        entitaet_id=fehlbestand.id,
+        neuer_wert={"ursache": fehlbestand.ursache, "geraet_instanz_id": str(instanz.id)},
+    )
+    await benachrichtigung_service.benachrichtige_neuer_fehlbestand(db, fehlbestand=fehlbestand)
+    return fehlbestand.id