Sprint 4: Fehlbestand-Statusmaschine komplett, Nachfüllung sofort/später/teilweise

- Nachfuellung-Modell: einzige Aktion, die Objektposition.istmenge tatsächlich
  ändert (Vier-Kernbegriffe). Deckt Sofort-Nachfüllung während Kontrolle (Karte 07)
  und spätere/externe Nachfüllung (Prompt 02.5) mit derselben Logik ab
- Wichtiger Fix vor dem ersten Testlauf: Objektposition.istmenge wird bei Nachfüllung
  auf den neuen Wert GESETZT (fehlbestand.istmenge + menge), nicht unabhängig
  inkrementiert - sonst bliebe sie beim initialen "nicht kontrolliert"-Stand (0)
  stehen, obwohl die Kontrolle bereits einen realen Zählwert kennt
- Statusübergänge: offen -> nachgefuellt_teilweise (Fehlmenge>0) -> erledigt
  (Fehlmenge=0), ausschließlich automatisch bei Ist=Soll (U3)
- Überbestand durch Nachfüllung erlaubt, als Info gekennzeichnet, kein Fehler (E4)
- KontrollpositionRead liefert jetzt fehlbestand_id mit, damit die UI direkt eine
  Sofort-Nachfüllung anbieten kann, ohne separat nachzufragen
- Tests: U3, U4 (Sofort-Nachfüllung ohne Zwischenstatus), U5 (Teilnachfüllung),
  Überbestand-Fall, Nachfüllung auf bereits erledigten Fehlbestand -> 409

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

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

@@ -0,0 +1,86 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+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 RolleTyp
+from app.models.fehlbestand import Fehlbestand
+from app.schemas.fehlbestand import (
+    FehlbestandRead,
+    NachfuellungCreate,
+    NachfuellungRead,
+    NachfuellungResponse,
+)
+from app.services.fehlbestand import FehlbestandBereitsErledigtError, nachfuellen
+
+router = APIRouter()
+
+_mitarbeiter_plus = require_roles(
+    RolleTyp.mitarbeiter,
+    RolleTyp.materialverantwortlicher,
+    RolleTyp.leitungsverantwortlicher,
+    RolleTyp.administration,
+)
+_verantwortliche = require_roles(
+    RolleTyp.administration, RolleTyp.materialverantwortlicher, RolleTyp.leitungsverantwortlicher
+)
+
+
+@router.get("/fehlbestaende", response_model=list[FehlbestandRead])
+async def liste_fehlbestaende(
+    status_filter: str | None = None,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_verantwortliche),
+) -> list[Fehlbestand]:
+    """Vollständige Filterung nach Zuständigkeit/Standort folgt Sprint 6 (Dashboard)."""
+    stmt = select(Fehlbestand)
+    if status_filter is not None:
+        stmt = stmt.where(Fehlbestand.status == status_filter)
+    result = await db.execute(stmt)
+    return list(result.scalars().all())
+
+
+@router.get("/fehlbestaende/{fehlbestand_id}", response_model=FehlbestandRead)
+async def hole_fehlbestand(
+    fehlbestand_id: uuid.UUID, db: AsyncSession = Depends(get_db), _=Depends(_mitarbeiter_plus)
+) -> Fehlbestand:
+    fehlbestand = await db.get(Fehlbestand, fehlbestand_id)
+    if fehlbestand is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Fehlbestand nicht gefunden")
+    return fehlbestand
+
+
+@router.post(
+    "/fehlbestaende/{fehlbestand_id}/nachfuellungen",
+    response_model=NachfuellungResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def erfasse_nachfuellung(
+    fehlbestand_id: uuid.UUID,
+    payload: NachfuellungCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user=Depends(_mitarbeiter_plus),
+) -> NachfuellungResponse:
+    """Prompt 02.3/02.5: deckt Sofort-Nachfüllung während der Kontrolle (Karte 07)
+    und spätere/externe Nachfüllung gleichermaßen ab."""
+    fehlbestand = await db.get(Fehlbestand, fehlbestand_id)
+    if fehlbestand is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Fehlbestand nicht gefunden")
+
+    try:
+        nachfuellung, ueberbestand = await nachfuellen(
+            db, fehlbestand=fehlbestand, menge=payload.menge, benutzer_id=current_user.id
+        )
+    except FehlbestandBereitsErledigtError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="Fehlbestand ist bereits erledigt"
+        ) from exc
+
+    return NachfuellungResponse(
+        nachfuellung=NachfuellungRead.model_validate(nachfuellung),
+        fehlbestand=FehlbestandRead.model_validate(fehlbestand),
+        ueberbestand=ueberbestand,
+    )

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

@@ -121,13 +121,13 @@ async def erfasse_kontrollposition(
     payload: KontrollpositionInput,
     db: AsyncSession = Depends(get_db),
     current_user: Benutzer = Depends(_mitarbeiter_plus),
-) -> Kontrollposition:
+) -> KontrollpositionRead:
     kontrolle = await _hole_kontrolle_oder_404(db, kontrolle_id)
     _pruefe_besitz(kontrolle, current_user)
 
     objekt = await db.get(Objekt, kontrolle.objekt_id)
     zustaendiger_server_id = await _hauptserver_id(db)
-    return await erfasse_position(
+    kontrollposition, fehlbestand_id = await erfasse_position(
         db,
         kontrolle=kontrolle,
         objekt=objekt,
@@ -135,6 +135,15 @@ async def erfasse_kontrollposition(
         istmenge=payload.istmenge,
         zustaendiger_server_id=zustaendiger_server_id,
     )
+    return KontrollpositionRead(
+        id=kontrollposition.id,
+        kontrolle_id=kontrollposition.kontrolle_id,
+        material_id=kontrollposition.material_id,
+        sollmenge_snapshot=kontrollposition.sollmenge_snapshot,
+        istmenge_erfasst=kontrollposition.istmenge_erfasst,
+        abweichung=kontrollposition.abweichung,
+        fehlbestand_id=fehlbestand_id,
+    )
 
 
 @router.post("/kontrollen/{kontrolle_id}/abschliessen", response_model=KontrolleRead)