feat(rollen): granulares Rechte-System (Roadmap Phase 6, letztes Modul)

Additiv neben dem bestehenden 4-Rollen-System (mitarbeiter/material-
verantwortlicher/leitungsverantwortlicher/administration bleiben unverändert,
kein Breaking Change): Admin kann jetzt eigene Rollen (z.B. "Materialwart",
"Helfer" aus der Ursprungs-Anforderung) mit frei wählbaren Einzelrechten aus
einem Berechtigungs-Katalog anlegen und Benutzern zuweisen - auch Benutzern
ganz ohne feste RolleTyp-Zuordnung.

Neue Tabellen: berechtigung (Katalog), rolle (custom, admin-anlegbar),
rolle_berechtigung (M:N), benutzer_rolle_zuordnung (M:N, eigene Tabelle statt
Wiederverwendung des ENUM-basierten benutzer_rolle).

require_roles_or_permission() kombiniert beide Systeme: bestehende feste
Rollen ODER eine passende granulare Berechtigung. Auf die vom Nutzer genannten
Beispiel-Endpunkte angewendet: Material anlegen/bearbeiten, Lagerbewegung
durchführen, Mangel melden/lesen/bearbeiten, Prüfung durchführen - weitere
Endpunkte folgen bei Bedarf nach demselben Muster (require_permission()/
require_roles_or_permission() stehen jetzt als Bausteine bereit).

Neue Endpunkte: GET /berechtigungen, CRUD /rollen, PUT/DELETE
/rollen/{id}/berechtigungen/{id}, PUT/DELETE /benutzer/{id}/rollen/{id}.

Frontend: neuer Admin-Tab "Rollen & Rechte" (Rolle anlegen, Rechte togglen,
Benutzer zuweisen/entfernen).

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

backend/app/api/deps.py

@@ -8,6 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.security import InvalidTokenError, decode_access_token
 from app.db.session import get_db
 from app.models.auth import Benutzer, RolleTyp
+from app.models.permission import Berechtigung, BenutzerRolleZuordnung, Rolle, RolleBerechtigung
 
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
 
@@ -50,3 +51,55 @@ def require_roles(*erlaubte_rollen: RolleTyp) -> Callable:
         return current_user
 
     return checker
+
+
+async def _hat_berechtigung(db: AsyncSession, benutzer_id: int, schluessel: tuple[str, ...]) -> bool:
+    result = await db.execute(
+        select(Berechtigung.schluessel)
+        .join(RolleBerechtigung, RolleBerechtigung.berechtigung_id == Berechtigung.id)
+        .join(Rolle, Rolle.id == RolleBerechtigung.rolle_id)
+        .join(BenutzerRolleZuordnung, BenutzerRolleZuordnung.rolle_id == Rolle.id)
+        .where(BenutzerRolleZuordnung.benutzer_id == benutzer_id, Berechtigung.schluessel.in_(schluessel))
+    )
+    return result.first() is not None
+
+
+def require_permission(*erlaubte_berechtigungen: str) -> Callable:
+    """Roadmap Phase 6 (granulares Rechte-System): prüft, ob eine der frei
+    konfigurierbaren Rollen des Benutzers (app.models.permission.Rolle) eine
+    der übergebenen Berechtigungen trägt - additiv zum festen 4-Rollen-System,
+    das über require_roles() unverändert weiterläuft."""
+
+    async def checker(
+        current_user: Benutzer = Depends(get_current_user), db: AsyncSession = Depends(get_db)
+    ) -> Benutzer:
+        if not await _hat_berechtigung(db, current_user.id, erlaubte_berechtigungen):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Für diese Aktion fehlt die erforderliche Berechtigung",
+            )
+        return current_user
+
+    return checker
+
+
+def require_roles_or_permission(*erlaubte_rollen: RolleTyp, berechtigung: str) -> Callable:
+    """Kombinierte Prüfung für Endpunkte, die sowohl über eine der festen
+    Rollen (bestehende Admins/Materialverantwortliche/... - Rückwärts-
+    kompatibilität) als auch über eine neu zugewiesene granulare Berechtigung
+    (z.B. eine custom "Materialwart"-Rolle) erreichbar sein sollen."""
+
+    async def checker(
+        current_user: Benutzer = Depends(get_current_user), db: AsyncSession = Depends(get_db)
+    ) -> Benutzer:
+        besitzt = {RolleTyp(r) for r in current_user.rollen_namen}
+        if besitzt.intersection(erlaubte_rollen):
+            return current_user
+        if await _hat_berechtigung(db, current_user.id, (berechtigung,)):
+            return current_user
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Für diese Aktion fehlt die erforderliche Rolle oder Berechtigung",
+        )
+
+    return checker

backend/app/api/v1/api.py

@@ -14,6 +14,7 @@ from app.api.v1.endpoints import (
     lagerbewegung,
     mangel,
     objekte,
+    permission,
     personal,
     stammdaten,
     vorlagen,
@@ -38,3 +39,4 @@ api_router.include_router(personal.router, tags=["personal"])
 api_router.include_router(mangel.router, tags=["mangel"])
 api_router.include_router(lagerbewegung.router, tags=["lagerbewegung"])
 api_router.include_router(dokument.router, tags=["dokument"])
+api_router.include_router(permission.router, tags=["permission"])

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

@@ -5,7 +5,7 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.api.deps import require_roles
+from app.api.deps import require_roles, require_roles_or_permission
 from app.db.session import get_db
 from app.models.auth import KnotenTyp, RolleTyp, Systemknoten
 from app.models.geraet_instanz import GeraetInstanz
@@ -18,6 +18,14 @@ router = APIRouter()
 _materialverantwortliche = require_roles(
     RolleTyp.administration, RolleTyp.materialverantwortlicher, RolleTyp.leitungsverantwortlicher
 )
+# Roadmap Phase 6: Prüfung durchführen zusätzlich über die granulare
+# Berechtigung "pruefung.durchfuehren" erreichbar (z.B. custom "Helfer"-Rolle).
+_darf_pruefen = require_roles_or_permission(
+    RolleTyp.administration,
+    RolleTyp.materialverantwortlicher,
+    RolleTyp.leitungsverantwortlicher,
+    berechtigung="pruefung.durchfuehren",
+)
 
 
 async def _hauptserver_id(db: AsyncSession) -> int:
@@ -61,7 +69,7 @@ async def aendere_geraet_status(
     geraet_id: uuid.UUID,
     payload: GeraetInstanzStatusUpdate,
     db: AsyncSession = Depends(get_db),
-    current_user=Depends(_materialverantwortliche),
+    current_user=Depends(_darf_pruefen),
 ) -> GeraetInstanz:
     instanz = await db.get(GeraetInstanz, geraet_id)
     if instanz is None:

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

@@ -2,7 +2,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.api.deps import get_current_user, require_roles
+from app.api.deps import get_current_user, require_roles_or_permission
 from app.db.session import get_db
 from app.models.auth import RolleTyp
 from app.models.lagerbewegung import Lagerbewegung
@@ -13,10 +13,14 @@ from app.services.lagerbewegung import verschiebe_objekt
 
 router = APIRouter()
 
-# Deckt sich mit der Rollen-Vorgabe aus dem Mangel-Modul (Materialwart-
-# Berechtigung "Lagerbewegungen durchführen" aus der Ursprungs-Anforderung).
-_materialverantwortliche = require_roles(
-    RolleTyp.administration, RolleTyp.materialverantwortlicher, RolleTyp.leitungsverantwortlicher
+# Deckt sich mit der Rollen-Vorgabe aus dem Mangel-Modul, zusätzlich über die
+# granulare Berechtigung "lagerbewegung.durchfuehren" erreichbar (z.B. eine
+# custom "Materialwart"-Rolle, Roadmap Phase 6).
+_materialverantwortliche = require_roles_or_permission(
+    RolleTyp.administration,
+    RolleTyp.materialverantwortlicher,
+    RolleTyp.leitungsverantwortlicher,
+    berechtigung="lagerbewegung.durchfuehren",
 )
 
 

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

@@ -5,7 +5,7 @@ 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.api.deps import require_roles_or_permission
 from app.db.session import get_db
 from app.models.auth import KnotenTyp, RolleTyp, Systemknoten
 from app.models.mangel import Mangel, MangelStatus
@@ -16,14 +16,21 @@ from app.services.mangel import aendere_status
 
 router = APIRouter()
 
-_mitarbeiter_plus = require_roles(
+_ALLE_ROLLEN = (
     RolleTyp.mitarbeiter,
     RolleTyp.materialverantwortlicher,
     RolleTyp.leitungsverantwortlicher,
     RolleTyp.administration,
 )
-_materialverantwortliche = require_roles(
-    RolleTyp.administration, RolleTyp.materialverantwortlicher, RolleTyp.leitungsverantwortlicher
+# Roadmap Phase 6: zusätzlich über eine granulare custom-Rolle (z.B. "Helfer")
+# erreichbar, auch wenn diese keine der vier festen RolleTyp-Rollen trägt.
+_darf_lesen = require_roles_or_permission(*_ALLE_ROLLEN, berechtigung="mangel.lesen")
+_darf_melden = require_roles_or_permission(*_ALLE_ROLLEN, berechtigung="mangel.melden")
+_materialverantwortliche = require_roles_or_permission(
+    RolleTyp.administration,
+    RolleTyp.materialverantwortlicher,
+    RolleTyp.leitungsverantwortlicher,
+    berechtigung="mangel.bearbeiten",
 )
 
 
@@ -37,7 +44,7 @@ async def liste_maengel(
     objekt_id: int | None = None,
     status_filter: MangelStatus | None = None,
     db: AsyncSession = Depends(get_db),
-    _=Depends(_mitarbeiter_plus),
+    _=Depends(_darf_lesen),
 ) -> list[Mangel]:
     """Prompt-Erweiterung (Mangel-Modul): jeder Mitarbeiter+ darf lesen (Mängel
     sind für alle im Einsatzalltag relevant), Status ändern bleibt
@@ -54,7 +61,7 @@ async def liste_maengel(
 
 @router.post("/maengel", response_model=MangelRead, status_code=status.HTTP_201_CREATED)
 async def melde_mangel(
-    payload: MangelCreate, db: AsyncSession = Depends(get_db), current_user=Depends(_mitarbeiter_plus)
+    payload: MangelCreate, db: AsyncSession = Depends(get_db), current_user=Depends(_darf_melden)
 ) -> Mangel:
     objekt = await db.get(Objekt, payload.objekt_id)
     if objekt is None:

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

@@ -0,0 +1,129 @@
+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 Benutzer, RolleTyp
+from app.models.permission import Berechtigung, BenutzerRolleZuordnung, Rolle, RolleBerechtigung
+from app.schemas.permission import BerechtigungRead, RolleCreate, RolleRead, RolleUpdate
+
+router = APIRouter()
+
+_admin_only = require_roles(RolleTyp.administration)
+
+
+async def _rolle_read(db: AsyncSession, rolle: Rolle) -> RolleRead:
+    ids = (
+        await db.execute(select(RolleBerechtigung.berechtigung_id).where(RolleBerechtigung.rolle_id == rolle.id))
+    ).scalars().all()
+    return RolleRead(id=rolle.id, name=rolle.name, beschreibung=rolle.beschreibung, berechtigung_ids=list(ids))
+
+
+@router.get("/berechtigungen", response_model=list[BerechtigungRead])
+async def liste_berechtigungen(db: AsyncSession = Depends(get_db), _=Depends(_admin_only)) -> list[Berechtigung]:
+    result = await db.execute(select(Berechtigung))
+    return list(result.scalars().all())
+
+
+@router.get("/rollen", response_model=list[RolleRead])
+async def liste_rollen(db: AsyncSession = Depends(get_db), _=Depends(_admin_only)) -> list[RolleRead]:
+    result = await db.execute(select(Rolle))
+    return [await _rolle_read(db, r) for r in result.scalars().all()]
+
+
+@router.post("/rollen", response_model=RolleRead, status_code=status.HTTP_201_CREATED)
+async def erstelle_rolle(
+    payload: RolleCreate, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> RolleRead:
+    rolle = Rolle(name=payload.name, beschreibung=payload.beschreibung)
+    db.add(rolle)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Rollenname bereits vergeben") from exc
+    return await _rolle_read(db, rolle)
+
+
+@router.patch("/rollen/{rolle_id}", response_model=RolleRead)
+async def aendere_rolle(
+    rolle_id: int, payload: RolleUpdate, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> RolleRead:
+    rolle = await db.get(Rolle, rolle_id)
+    if rolle is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Rolle nicht gefunden")
+    for feld, wert in payload.model_dump(exclude_unset=True).items():
+        setattr(rolle, feld, wert)
+    try:
+        await db.flush()
+    except IntegrityError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Rollenname bereits vergeben") from exc
+    return await _rolle_read(db, rolle)
+
+
+@router.delete("/rollen/{rolle_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def loesche_rolle(rolle_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)) -> None:
+    rolle = await db.get(Rolle, rolle_id)
+    if rolle is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Rolle nicht gefunden")
+    await db.delete(rolle)
+    await db.flush()
+
+
+@router.put("/rollen/{rolle_id}/berechtigungen/{berechtigung_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def setze_rollen_berechtigung(
+    rolle_id: int, berechtigung_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> None:
+    if await db.get(Rolle, rolle_id) is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Rolle nicht gefunden")
+    if await db.get(Berechtigung, berechtigung_id) is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Berechtigung nicht gefunden")
+    bestehend = await db.get(RolleBerechtigung, {"rolle_id": rolle_id, "berechtigung_id": berechtigung_id})
+    if bestehend is None:
+        db.add(RolleBerechtigung(rolle_id=rolle_id, berechtigung_id=berechtigung_id))
+        await db.flush()
+
+
+@router.delete("/rollen/{rolle_id}/berechtigungen/{berechtigung_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def entferne_rollen_berechtigung(
+    rolle_id: int, berechtigung_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> None:
+    bestehend = await db.get(RolleBerechtigung, {"rolle_id": rolle_id, "berechtigung_id": berechtigung_id})
+    if bestehend is not None:
+        await db.delete(bestehend)
+        await db.flush()
+
+
+@router.put("/benutzer/{benutzer_id}/rollen/{rolle_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def weise_rolle_zu(
+    benutzer_id: int, rolle_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> None:
+    if await db.get(Benutzer, benutzer_id) is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Benutzer nicht gefunden")
+    if await db.get(Rolle, rolle_id) is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Rolle nicht gefunden")
+    bestehend = await db.get(BenutzerRolleZuordnung, {"benutzer_id": benutzer_id, "rolle_id": rolle_id})
+    if bestehend is None:
+        db.add(BenutzerRolleZuordnung(benutzer_id=benutzer_id, rolle_id=rolle_id))
+        await db.flush()
+
+
+@router.delete("/benutzer/{benutzer_id}/rollen/{rolle_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def entferne_rollen_zuordnung(
+    benutzer_id: int, rolle_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> None:
+    bestehend = await db.get(BenutzerRolleZuordnung, {"benutzer_id": benutzer_id, "rolle_id": rolle_id})
+    if bestehend is not None:
+        await db.delete(bestehend)
+        await db.flush()
+
+
+@router.get("/benutzer/{benutzer_id}/rollen", response_model=list[int])
+async def liste_rollen_zuordnung(
+    benutzer_id: int, db: AsyncSession = Depends(get_db), _=Depends(_admin_only)
+) -> list[int]:
+    result = await db.execute(
+        select(BenutzerRolleZuordnung.rolle_id).where(BenutzerRolleZuordnung.benutzer_id == benutzer_id)
+    )
+    return list(result.scalars().all())

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

@@ -2,7 +2,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.api.deps import get_current_user, require_roles
+from app.api.deps import get_current_user, require_roles, require_roles_or_permission
 from app.db.session import get_db
 from app.models.auth import RolleTyp
 from app.models.stammdaten import Bereich, Fach, Kategorie, Material, Objekttyp, Standort
@@ -259,7 +259,7 @@ async def hole_material(
 async def erstelle_material(
     payload: MaterialCreate,
     db: AsyncSession = Depends(get_db),
-    _=Depends(require_roles(RolleTyp.administration)),
+    _=Depends(require_roles_or_permission(RolleTyp.administration, berechtigung="material.erstellen")),
 ) -> Material:
     material = Material(**payload.model_dump())
     db.add(material)
@@ -272,7 +272,7 @@ async def aendere_material(
     material_id: int,
     payload: MaterialUpdate,
     db: AsyncSession = Depends(get_db),
-    _=Depends(require_roles(RolleTyp.administration)),
+    _=Depends(require_roles_or_permission(RolleTyp.administration, berechtigung="material.bearbeiten")),
 ) -> Material:
     material = await db.get(Material, material_id)
     if material is None:

backend/app/models/permission.py

@@ -0,0 +1,48 @@
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Berechtigung(Base):
+    """Roadmap Phase 6: Katalog einzelner Rechte (z.B. "material.erstellen").
+    Fest im Code definiert (welche Endpunkte welches Recht prüfen), aber wer
+    welche Berechtigung über welche Rolle bekommt, ist frei konfigurierbar."""
+
+    __tablename__ = "berechtigung"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    schluessel: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    beschreibung: Mapped[str] = mapped_column(String, nullable=False)
+
+
+class Rolle(Base):
+    """Vom Admin frei anlegbare Rolle (z.B. "Materialwart", "Helfer") - additiv
+    neben dem bestehenden festen 4-Rollen-System (RolleTyp), nicht dessen
+    Ersatz. Ein Benutzer kann beides gleichzeitig haben."""
+
+    __tablename__ = "rolle"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String, unique=True, nullable=False)
+    beschreibung: Mapped[str | None] = mapped_column(String)
+
+
+class RolleBerechtigung(Base):
+    __tablename__ = "rolle_berechtigung"
+
+    rolle_id: Mapped[int] = mapped_column(ForeignKey("rolle.id", ondelete="CASCADE"), primary_key=True)
+    berechtigung_id: Mapped[int] = mapped_column(
+        ForeignKey("berechtigung.id", ondelete="CASCADE"), primary_key=True
+    )
+
+
+class BenutzerRolleZuordnung(Base):
+    """M:N Benutzer<->Rolle (neues System) - eigene Tabelle statt
+    Wiederverwendung von benutzer_rolle, dessen rolle-Spalte ein fester ENUM
+    ist und keine FK auf frei anlegbare rolle-Zeilen erlaubt."""
+
+    __tablename__ = "benutzer_rolle_zuordnung"
+
+    benutzer_id: Mapped[int] = mapped_column(ForeignKey("benutzer.id", ondelete="CASCADE"), primary_key=True)
+    rolle_id: Mapped[int] = mapped_column(ForeignKey("rolle.id", ondelete="CASCADE"), primary_key=True)

backend/app/schemas/permission.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class BerechtigungRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    schluessel: str
+    beschreibung: str
+
+
+class RolleCreate(BaseModel):
+    name: str
+    beschreibung: str | None = None
+
+
+class RolleUpdate(BaseModel):
+    name: str | None = None
+    beschreibung: str | None = None
+
+
+class RolleRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    name: str
+    beschreibung: str | None
+    berechtigung_ids: list[int] = []