feat(personal): Personal/Qualifikationen-Modul (Roadmap Phase 1)

Neues Modul für die BOS-Ressourcenplattform-Erweiterung: Einheit (Zug/Gruppe,
self-referenzierend), Qualifikationstyp (Führerschein/Lehrgang/Berechtigung),
BenutzerQualifikation (mit Gültigkeit) und ObjekttypQualifikationsanforderung
(M:N) - beantwortet "wer darf dieses Fahrzeug fahren?" über
GET /objekte/{id}/berechtigung/{benutzer_id}.

Benutzer und Objekt bekommen optionale einheit_id (additiv, analog
fahrzeug_id-Muster). Nebenbei Bugfix: PATCH /benutzer konnte einheit_id nicht
auf null setzen (Feld-vorhanden-Check via model_fields_set statt is not None).

Frontend: neuer Admin-Tab "Personal" (Einheiten, Qualifikationstypen,
Benutzer-Qualifikationszuordnung), Einheit-Auswahl im Benutzer-Formular.

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

backend/app/api/v1/api.py

@@ -11,6 +11,7 @@ from app.api.v1.endpoints import (
     historie,
     kontrollen,
     objekte,
+    personal,
     stammdaten,
     vorlagen,
     zustaendigkeit,
@@ -30,3 +31,4 @@ 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"])
+api_router.include_router(personal.router, tags=["personal"])

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

@@ -37,6 +37,7 @@ async def erstelle_benutzer(
         email=payload.email,
         passwort_hash=hash_password(payload.passwort),
         aktiv=True,
+        einheit_id=payload.einheit_id,
     )
     db.add(benutzer)
     await db.flush()
@@ -64,6 +65,11 @@ async def aendere_benutzer(
         benutzer.email = payload.email
     if payload.aktiv is not None:
         benutzer.aktiv = payload.aktiv
+    if "einheit_id" in payload.model_fields_set:
+        # explizit gesetzt (auch null = Einheit lösen) unterscheiden von "nicht
+        # im Request enthalten" - anders als die übrigen Felder hier, da null
+        # ein gültiger, gewollter Zielzustand ist (Bugfix vor Auslieferung).
+        benutzer.einheit_id = payload.einheit_id
     if payload.rollen is not None:
         result = await db.execute(select(BenutzerRolle).where(BenutzerRolle.benutzer_id == benutzer_id))
         for bestehende in result.scalars().all():

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

@@ -0,0 +1,213 @@
+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 get_current_user, require_roles
+from app.db.session import get_db
+from app.models.auth import RolleTyp
+from app.models.personal import (
+    BenutzerQualifikation,
+    Einheit,
+    ObjekttypQualifikationsanforderung,
+    Qualifikationstyp,
+)
+from app.schemas.personal import (
+    BenutzerQualifikationCreate,
+    BenutzerQualifikationRead,
+    BerechtigungspruefungRead,
+    EinheitCreate,
+    EinheitRead,
+    EinheitUpdate,
+    ObjekttypQualifikationsanforderungCreate,
+    ObjekttypQualifikationsanforderungRead,
+    QualifikationstypCreate,
+    QualifikationstypRead,
+    QualifikationstypUpdate,
+)
+from app.services.personal import pruefe_berechtigung
+
+router = APIRouter()
+
+_admin_only = require_roles(RolleTyp.administration)
+
+
+# -- Einheit ------------------------------------------------------------------
+
+@router.get("/einheiten", response_model=list[EinheitRead])
+async def liste_einheiten(db: AsyncSession = Depends(get_db), _=Depends(get_current_user)) -> list[Einheit]:
+    result = await db.execute(select(Einheit))
+    return list(result.scalars().all())
+
+
+@router.post("/einheiten", response_model=EinheitRead, status_code=status.HTTP_201_CREATED)
+async def erstelle_einheit(
+    payload: EinheitCreate, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> Einheit:
+    einheit = Einheit(**payload.model_dump())
+    db.add(einheit)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Ungültige Zuordnung") from exc
+    return einheit
+
+
+@router.patch("/einheiten/{einheit_id}", response_model=EinheitRead)
+async def aendere_einheit(
+    einheit_id: int, payload: EinheitUpdate, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> Einheit:
+    einheit = await db.get(Einheit, einheit_id)
+    if einheit is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Einheit nicht gefunden")
+    for feld, wert in payload.model_dump(exclude_unset=True).items():
+        setattr(einheit, feld, wert)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Ungültige Zuordnung") from exc
+    return einheit
+
+
+# -- Qualifikationstyp ---------------------------------------------------------
+
+@router.get("/qualifikationstypen", response_model=list[QualifikationstypRead])
+async def liste_qualifikationstypen(
+    db: AsyncSession = Depends(get_db), _=Depends(get_current_user)
+) -> list[Qualifikationstyp]:
+    result = await db.execute(select(Qualifikationstyp))
+    return list(result.scalars().all())
+
+
+@router.post("/qualifikationstypen", response_model=QualifikationstypRead, status_code=status.HTTP_201_CREATED)
+async def erstelle_qualifikationstyp(
+    payload: QualifikationstypCreate, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> Qualifikationstyp:
+    qualifikationstyp = Qualifikationstyp(**payload.model_dump())
+    db.add(qualifikationstyp)
+    await db.flush()
+    return qualifikationstyp
+
+
+@router.patch("/qualifikationstypen/{qualifikationstyp_id}", response_model=QualifikationstypRead)
+async def aendere_qualifikationstyp(
+    qualifikationstyp_id: int,
+    payload: QualifikationstypUpdate,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_admin_only),
+) -> Qualifikationstyp:
+    qualifikationstyp = await db.get(Qualifikationstyp, qualifikationstyp_id)
+    if qualifikationstyp is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Qualifikationstyp nicht gefunden")
+    for feld, wert in payload.model_dump(exclude_unset=True).items():
+        setattr(qualifikationstyp, feld, wert)
+    await db.flush()
+    return qualifikationstyp
+
+
+# -- Benutzer-Qualifikation -----------------------------------------------------
+
+@router.get("/benutzer/{benutzer_id}/qualifikationen", response_model=list[BenutzerQualifikationRead])
+async def liste_benutzer_qualifikationen(
+    benutzer_id: int, db: AsyncSession = Depends(get_db), _=Depends(get_current_user)
+) -> list[BenutzerQualifikation]:
+    result = await db.execute(
+        select(BenutzerQualifikation).where(BenutzerQualifikation.benutzer_id == benutzer_id)
+    )
+    return list(result.scalars().all())
+
+
+@router.post(
+    "/benutzer/{benutzer_id}/qualifikationen",
+    response_model=BenutzerQualifikationRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def erfasse_benutzer_qualifikation(
+    benutzer_id: int,
+    payload: BenutzerQualifikationCreate,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_admin_only),
+) -> BenutzerQualifikation:
+    if payload.benutzer_id != benutzer_id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="benutzer_id im Pfad und Body weichen ab")
+    qualifikation = BenutzerQualifikation(**payload.model_dump())
+    db.add(qualifikation)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="Qualifikation mit diesem Erwerbsdatum existiert bereits"
+        ) from exc
+    return qualifikation
+
+
+# -- Objekttyp-Qualifikationsanforderung -----------------------------------------
+
+@router.get(
+    "/objekttypen/{objekttyp_id}/qualifikationsanforderungen",
+    response_model=list[ObjekttypQualifikationsanforderungRead],
+)
+async def liste_qualifikationsanforderungen(
+    objekttyp_id: int, db: AsyncSession = Depends(get_db), _=Depends(get_current_user)
+) -> list[ObjekttypQualifikationsanforderung]:
+    result = await db.execute(
+        select(ObjekttypQualifikationsanforderung).where(
+            ObjekttypQualifikationsanforderung.objekttyp_id == objekttyp_id
+        )
+    )
+    return list(result.scalars().all())
+
+
+@router.post(
+    "/objekttypen/{objekttyp_id}/qualifikationsanforderungen",
+    response_model=ObjekttypQualifikationsanforderungRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def erstelle_qualifikationsanforderung(
+    objekttyp_id: int,
+    payload: ObjekttypQualifikationsanforderungCreate,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_admin_only),
+) -> ObjekttypQualifikationsanforderung:
+    if payload.objekttyp_id != objekttyp_id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="objekttyp_id im Pfad und Body weichen ab")
+    anforderung = ObjekttypQualifikationsanforderung(**payload.model_dump())
+    db.add(anforderung)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Anforderung existiert bereits") from exc
+    return anforderung
+
+
+@router.delete(
+    "/objekttypen/{objekttyp_id}/qualifikationsanforderungen/{qualifikationstyp_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def loesche_qualifikationsanforderung(
+    objekttyp_id: int,
+    qualifikationstyp_id: int,
+    db: AsyncSession = Depends(get_db),
+    _=Depends(_admin_only),
+) -> None:
+    anforderung = await db.get(
+        ObjekttypQualifikationsanforderung, {"objekttyp_id": objekttyp_id, "qualifikationstyp_id": qualifikationstyp_id}
+    )
+    if anforderung is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Anforderung nicht gefunden")
+    await db.delete(anforderung)
+    await db.flush()
+
+
+# -- Berechtigungsprüfung -------------------------------------------------------
+
+@router.get("/objekte/{objekt_id}/berechtigung/{benutzer_id}", response_model=BerechtigungspruefungRead)
+async def pruefe_objekt_berechtigung(
+    objekt_id: int, benutzer_id: int, db: AsyncSession = Depends(get_db), _=Depends(get_current_user)
+) -> BerechtigungspruefungRead:
+    """Nutzer-Beispiel Personal-Modul: "wer darf dieses Fahrzeug fahren?"."""
+    fehlende = await pruefe_berechtigung(db, benutzer_id=benutzer_id, objekt_id=objekt_id)
+    return BerechtigungspruefungRead(
+        berechtigt=len(fehlende) == 0,
+        fehlende_qualifikationstypen=list(fehlende),
+    )