feat(ui): UI-005 begründete Einsatzbereitschaft + Dokumente in der Akte

Backend: objekt_readiness() in dashboard.py liefert Status+Gründe für
ein einzelnes Objekt, Fallunterscheidung aus einsatzbereitschaft()
extrahiert (_kategorie_und_gruende, keine Duplizierung). Neue Felder
an /akte/objekt/{id}. Frontend: ReadinessBadge + Gründeliste ersetzt
den rohen objekt.status-Badge (Objekt-Lebenszyklus-Status bleibt
separat sichtbar). Dokumente waren in der Akte bisher nur Text ohne
Interaktion - jetzt DokumentePanel eingebunden plus neuer "Ansehen"-
Klick (PDF/Bild im neuen Tab statt Zwangs-Download).

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

arbeitskacheln/20_ui_redesign.md

@@ -136,7 +136,20 @@ Aktueller Stand vor Redesign: 39 Seiten-/Komponenten-Dateien, ~7.000 Zeilen, ein
 - **Akzeptanzkriterien:** „unbekannt/nie kontrolliert" wird nie als einsatzbereit
   dargestellt (harte Regel, Akzeptanzkriterium testbar).
 - **Tests:** Begründungslogik testen (welche Bedingungen führen zu welchem Status).
-- **DoD:** offen.
+- **DoD:** umgesetzt (2026-09-06). Backend: `objekt_readiness()` in
+  `app/services/dashboard.py` - Fallunterscheidung aus `einsatzbereitschaft()`
+  in `_kategorie_und_gruende()` extrahiert, keine Duplizierung, für ein
+  einzelnes Objekt statt aller. Neue Felder `einsatzbereitschaft_status`/
+  `einsatzbereitschaft_gruende` an `/akte/objekt/{id}`. Frontend:
+  `ReadinessBadge` + Gründeliste (gemeinsames `GRUND_TEXT`-Mapping mit
+  Dashboard) statt des rohen `objekt.status`-Badges - Objekt-Lebenszyklus-
+  Status (aktiv/ausser_dienst/in_wartung) bleibt separat als Text sichtbar,
+  keine Vermischung. Getestet: kritischer Mangel -> "not-ready", nie
+  kontrolliert ohne sonstige Auffälligkeit -> "unknown" (nie "ready").
+  Nebenbei (Nutzer-Nachfrage): Dokumente in der Akte waren bisher nur Text
+  ohne jede Interaktion - jetzt `DokumentePanel` eingebunden (Upload/Liste/
+  Löschen wie in Mängel/Admin), plus neuer "Ansehen"-Klick (`ladeDokumentAnsehen`
+  öffnet PDF/Bild im neuen Tab) zusätzlich zum bisherigen Zwangs-Download.
 
 ## UI-006 — Kontrolle & Beladung modernisiert
 

backend/app/schemas/akte.py

@@ -24,6 +24,8 @@ class AkteRead(BaseModel):
     03_digital_file.md)."""
 
     objekt: ObjektRead
+    einsatzbereitschaft_status: str
+    einsatzbereitschaft_gruende: list[str]
     objekttyp_name: str
     standort_name: str
     fahrzeugdetails: FahrzeugdetailsRead | None

backend/app/services/akte.py

@@ -18,6 +18,7 @@ from app.schemas.historie import HistorieRead
 from app.schemas.mangel import MangelRead
 from app.schemas.objekt import FahrzeugdetailsRead, ObjektRead
 from app.schemas.zustaendigkeit import KontrollverantwortungRead
+from app.services.dashboard import objekt_readiness
 from app.services.objekte import letzte_kontrollen_map
 
 
@@ -89,12 +90,16 @@ async def akte_fuer_objekt(db: AsyncSession, objekt_id: int) -> AkteRead | None:
 
     maengel_result = await db.execute(select(Mangel).where(Mangel.objekt_id == objekt_id))
 
+    readiness = await objekt_readiness(db, objekt_id)
+
     objekt_read = ObjektRead.model_validate(objekt).model_copy(
         update={"letzte_kontrolle_am": letzte_map.get(objekt_id)}
     )
 
     return AkteRead(
         objekt=objekt_read,
+        einsatzbereitschaft_status=readiness["status"],
+        einsatzbereitschaft_gruende=readiness["gruende"],
         objekttyp_name=objekttyp.name if objekttyp else "",
         standort_name=standort.name if standort else "",
         fahrzeugdetails=FahrzeugdetailsRead.model_validate(fahrzeugdetails) if fahrzeugdetails else None,

backend/app/services/dashboard.py

@@ -199,8 +199,51 @@ async def einsatzbereitschaft(db: AsyncSession) -> dict:
     bereit = eingeschraenkt = unbekannt = 0
     details: list[dict] = []
     for objekt in objekte:
+        kategorie, gruende = _kategorie_und_gruende(
+            objekt,
+            letzte_kontrolle_map.get(objekt.id),
+            objekt_ids_mit_fehlbestand.get(objekt.id, set()),
+            fehlbestand_ids_genehmigt,
+            objekt_ids_abgelaufen,
+            objekt_ids_pruefung_ueberfaellig,
+            objekt_ids_gesperrt,
+            objekt_ids_kritischer_mangel,
+            objekt_ids_hu_uvv_ueberfaellig,
+        )
+        if kategorie == "ready":
+            bereit += 1
+        else:
+            if kategorie == "limited":
+                eingeschraenkt += 1
+            elif kategorie == "unknown":
+                unbekannt += 1
+            details.append({"objekt_id": objekt.id, "code": objekt.code, "name": objekt.name, "gruende": gruende})
+
+    return {
+        "einsatzbereit": bereit,
+        "eingeschraenkt_einsatzbereit": eingeschraenkt,
+        "unbekannt": unbekannt,
+        "nicht_einsatzbereit": len(objekte) - bereit - eingeschraenkt - unbekannt,
+        "gesamt": len(objekte),
+        "details": details,
+    }
+
+
+def _kategorie_und_gruende(
+    objekt: Objekt,
+    letzte_kontrolle,
+    fehlbestand_ids: set,
+    fehlbestand_ids_genehmigt: set,
+    objekt_ids_abgelaufen: set,
+    objekt_ids_pruefung_ueberfaellig: set,
+    objekt_ids_gesperrt: set,
+    objekt_ids_kritischer_mangel: set,
+    objekt_ids_hu_uvv_ueberfaellig: set,
+) -> tuple[str, list[str]]:
+    """UI-005 (Epic 20): aus der `einsatzbereitschaft()`-Schleife extrahiert, damit
+    `objekt_readiness()` (Begründung auf der Objektakte) dieselbe Logik nutzt statt
+    sie zu duplizieren."""
     gruende: list[str] = []
-        fehlbestand_ids = objekt_ids_mit_fehlbestand.get(objekt.id, set())
     ungenehmigt = fehlbestand_ids - fehlbestand_ids_genehmigt
     if ungenehmigt:
         gruende.append("fehlbestand_offen")
@@ -218,28 +261,102 @@ async def einsatzbereitschaft(db: AsyncSession) -> dict:
         gruende.append("hu_uvv_ueberfaellig")
 
     if not gruende and fehlbestand_ids and fehlbestand_ids <= fehlbestand_ids_genehmigt:
-            eingeschraenkt += 1
-            details.append(
-                {"objekt_id": objekt.id, "code": objekt.code, "name": objekt.name, "gruende": ["mindermenge_genehmigt"]}
-            )
-        elif not gruende and letzte_kontrolle_map.get(objekt.id) is None:
-            unbekannt += 1
-            details.append(
-                {"objekt_id": objekt.id, "code": objekt.code, "name": objekt.name, "gruende": ["noch_nie_kontrolliert"]}
-            )
-        elif not gruende:
-            bereit += 1
-        else:
-            details.append({"objekt_id": objekt.id, "code": objekt.code, "name": objekt.name, "gruende": gruende})
+        return "limited", ["mindermenge_genehmigt"]
+    if not gruende and letzte_kontrolle is None:
+        return "unknown", ["noch_nie_kontrolliert"]
+    if not gruende:
+        return "ready", []
+    return "not-ready", gruende
 
-    return {
-        "einsatzbereit": bereit,
-        "eingeschraenkt_einsatzbereit": eingeschraenkt,
-        "unbekannt": unbekannt,
-        "nicht_einsatzbereit": len(objekte) - bereit - eingeschraenkt - unbekannt,
-        "gesamt": len(objekte),
-        "details": details,
-    }
+
+async def objekt_readiness(db: AsyncSession, objekt_id: int) -> dict:
+    """UI-005 (Epic 20): begründete Einsatzbereitschaft für EIN Objekt (Objektakte),
+    dieselbe Fachlogik wie `einsatzbereitschaft()` (Dashboard-Aggregat), nur für
+    einen einzelnen Datensatz statt aller Objekte. `ausser_dienst` zählt hier
+    bewusst nicht als eigener Fall - Objektakte zeigt das Objekt so oder so an,
+    der Objekt-Lebenszyklus-Status wird separat dargestellt."""
+    heute = datetime.now(timezone.utc).date()
+    objekt = await db.get(Objekt, objekt_id)
+    if objekt is None:
+        return {"status": "unknown", "gruende": []}
+
+    fehlbestand_ids = set(
+        (
+            await db.execute(
+                select(Fehlbestand.id).where(
+                    Fehlbestand.objekt_id == objekt_id, Fehlbestand.status.in_(OFFEN_STATI)
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    fehlbestand_ids_genehmigt = set(
+        (
+            await db.execute(
+                select(func.distinct(MindermengenGenehmigung.fehlbestand_id)).where(
+                    MindermengenGenehmigung.fehlbestand_id.in_(fehlbestand_ids),
+                    MindermengenGenehmigung.status == MindermengeStatus.aktiv,
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    hat_ablaufdatum = (
+        await db.execute(
+            select(Objektposition.id).where(
+                Objektposition.objekt_id == objekt_id,
+                Objektposition.ablaufdatum.is_not(None),
+                Objektposition.ablaufdatum < heute,
+            ).limit(1)
+        )
+    ).first() is not None
+    hat_ueberfaellige_pruefung = (
+        await db.execute(
+            select(GeraetInstanz.id)
+            .join(Objektposition, GeraetInstanz.objektposition_id == Objektposition.id)
+            .where(
+                Objektposition.objekt_id == objekt_id,
+                GeraetInstanz.naechste_pruefung.is_not(None),
+                GeraetInstanz.naechste_pruefung < heute,
+            )
+            .limit(1)
+        )
+    ).first() is not None
+    ist_gesperrt = (
+        await db.execute(
+            select(Kontrolle.id)
+            .where(Kontrolle.objekt_id == objekt_id, Kontrolle.status == KontrollStatus.in_bearbeitung)
+            .limit(1)
+        )
+    ).first() is not None
+    hat_kritischen_mangel = objekt_id in await objekt_ids_mit_kritischem_offenem_mangel(db)
+    hat_ueberfaellige_hu_uvv = (
+        await db.execute(
+            select(Fahrzeugdetails.objekt_id).where(
+                Fahrzeugdetails.objekt_id == objekt_id,
+                (
+                    (Fahrzeugdetails.naechste_hu.is_not(None)) & (Fahrzeugdetails.naechste_hu < heute)
+                )
+                | ((Fahrzeugdetails.naechste_uvv.is_not(None)) & (Fahrzeugdetails.naechste_uvv < heute)),
+            )
+        )
+    ).first() is not None
+    letzte_kontrolle_map = await letzte_kontrollen_map(db, [objekt_id])
+
+    kategorie, gruende = _kategorie_und_gruende(
+        objekt,
+        letzte_kontrolle_map.get(objekt_id),
+        fehlbestand_ids,
+        fehlbestand_ids_genehmigt,
+        {objekt_id} if hat_ablaufdatum else set(),
+        {objekt_id} if hat_ueberfaellige_pruefung else set(),
+        {objekt_id} if ist_gesperrt else set(),
+        {objekt_id} if hat_kritischen_mangel else set(),
+        {objekt_id} if hat_ueberfaellige_hu_uvv else set(),
+    )
+    return {"status": kategorie, "gruende": gruende}
 
 
 async def bevorstehende_prueftermine(db: AsyncSession, warnzeitraum_tage: int = 30) -> list[dict]:

backend/tests/test_akte.py

@@ -48,6 +48,21 @@ async def test_akte_buendelt_teilbereiche(client, db_session, objekt_mit_positio
     assert body["maengel"][0]["beschreibung"] == "Riss im Gurt"
     assert len(body["historie"]) == 1
     assert body["historie"][0]["entitaet_typ"] == "objekt"
+    assert body["einsatzbereitschaft_status"] == "not-ready"
+    assert "mangel_kritisch_offen" in body["einsatzbereitschaft_gruende"]
+
+
+@pytest.mark.asyncio
+async def test_akte_readiness_unbekannt_bei_nie_kontrolliert(client, objekt_mit_position, admin_user):
+    """UI-005: ein Objekt ohne jede Auffälligkeit, aber noch nie kontrolliert,
+    gilt als "unbekannt" - NIE als "einsatzbereit" (Akzeptanzkriterium)."""
+    objekt, _material = objekt_mit_position
+    token = await login(client, "admin1")
+    antwort = await client.get(f"/api/v1/akte/objekt/{objekt.id}", headers=auth_header(token))
+    assert antwort.status_code == 200
+    body = antwort.json()
+    assert body["einsatzbereitschaft_status"] == "unknown"
+    assert body["einsatzbereitschaft_status"] != "ready"
 
 
 @pytest.mark.asyncio

frontend/src/api/client.ts

@@ -106,6 +106,24 @@ export async function ladeDokumentHerunter(dokumentId: string, dateiname: string
   URL.revokeObjectURL(url);
 }
 
+// UI-005 (Epic 20): Dokumente waren bisher nur per Zwangs-Download einsehbar,
+// nicht direkt im Browser anschaubar (PDF/Bild in neuem Tab statt Datei
+// speichern). Auch hier: Auth-Header nötig, daher Blob statt einfachem
+// <a href> auf den Download-Endpunkt. Object-URL wird bewusst NICHT sofort
+// revoked (Tab braucht sie noch); der Browser räumt sie beim Tab-Schließen auf.
+export async function ladeDokumentAnsehen(dokumentId: string): Promise<void> {
+  const headers: Record<string, string> = {};
+  if (authToken) headers["Authorization"] = `Bearer ${authToken}`;
+
+  const response = await fetch(`${BASE_URL}/dokumente/${dokumentId}/download`, { headers });
+  if (!response.ok) {
+    throw new ApiError(response.status, null);
+  }
+  const blob = await response.blob();
+  const url = URL.createObjectURL(blob);
+  window.open(url, "_blank", "noopener");
+}
+
 export async function login(username: string, password: string): Promise<string> {
   const body = new URLSearchParams({ username, password });
   const response = await fetch(`${BASE_URL}/auth/login`, {

frontend/src/api/types.ts

@@ -262,6 +262,8 @@ export interface ZustaendigerBenutzer {
 
 export interface Akte {
   objekt: Objekt;
+  einsatzbereitschaft_status: "ready" | "limited" | "not-ready" | "unknown";
+  einsatzbereitschaft_gruende: string[];
   objekttyp_name: string;
   standort_name: string;
   fahrzeugdetails: Fahrzeugdetails | null;

frontend/src/components/DokumentePanel.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 
-import { apiRequest, ladeDokumentHerunter, ladeDokumentHoch } from "../api/client";
+import { apiRequest, ladeDokumentAnsehen, ladeDokumentHerunter, ladeDokumentHoch } from "../api/client";
 import { useAuth } from "../auth/AuthContext";
 import type { Dokument } from "../api/types";
 
@@ -63,6 +63,14 @@ export function DokumentePanel({ entitaetTyp, entitaetId, onFehler }: Props) {
     }
   }
 
+  async function ansehen(d: Dokument) {
+    try {
+      await ladeDokumentAnsehen(d.id);
+    } catch {
+      onFehler("Datei konnte nicht geöffnet werden.");
+    }
+  }
+
   async function herunterladen(d: Dokument) {
     try {
       await ladeDokumentHerunter(d.id, d.dateiname);
@@ -100,7 +108,8 @@ export function DokumentePanel({ entitaetTyp, entitaetId, onFehler }: Props) {
             <li key={d.id} className="row-between" style={{ padding: "0.3rem 0" }}>
               <span>
                 <button
-                  onClick={() => herunterladen(d)}
+                  onClick={() => ansehen(d)}
+                  title="In neuem Tab ansehen"
                   style={{
                     background: "none",
                     border: "none",
@@ -115,11 +124,16 @@ export function DokumentePanel({ entitaetTyp, entitaetId, onFehler }: Props) {
                 {d.beschreibung && <span className="text-muted"> – {d.beschreibung}</span>}
                 <span className="text-muted"> ({formatGroesse(d.groesse_bytes)})</span>
               </span>
+              <span className="row" style={{ gap: "0.4rem" }}>
+                <button className="btn btn-secondary" onClick={() => herunterladen(d)}>
+                  Herunterladen
+                </button>
                 {darfLoeschen && (
                   <button className="btn btn-secondary" onClick={() => loeschen(d)}>
                     Löschen
                   </button>
                 )}
+              </span>
             </li>
           ))}
         </ul>

frontend/src/components/status/gruendeText.ts

@@ -0,0 +1,13 @@
+/** Spiegelt die Grund-Codes aus app/services/dashboard.py (einsatzbereitschaft/
+ * objekt_readiness) - gemeinsam genutzt von DashboardPage und AktePage. */
+export const GRUND_TEXT: Record<string, string> = {
+  fehlbestand_offen: "Offener Fehlbestand",
+  ablaufdatum_abgelaufen: "Ablaufdatum überschritten",
+  pruefung_ueberfaellig: "Geräteprüfung überfällig",
+  kontrolle_laeuft: "Kontrolle läuft (gesperrt)",
+  mangel_kritisch_offen: "Kritischer Mangel offen",
+  in_wartung: "In Wartung",
+  hu_uvv_ueberfaellig: "HU/UVV überfällig",
+  noch_nie_kontrolliert: "Noch nie kontrolliert",
+  mindermenge_genehmigt: "Mindermenge genehmigt",
+};

frontend/src/pages/AktePage.tsx

@@ -3,6 +3,9 @@ import { Link, useParams } from "react-router-dom";
 
 import { apiRequest } from "../api/client";
 import type { Akte } from "../api/types";
+import { DokumentePanel } from "../components/DokumentePanel";
+import { ReadinessBadge } from "../components/status/ReadinessBadge";
+import { GRUND_TEXT } from "../components/status/gruendeText";
 
 const MANGEL_PRIORITAET_LABEL: Record<string, string> = {
   niedrig: "Niedrig",
@@ -39,11 +42,20 @@ export function AktePage() {
         <div>
           <h1 style={{ marginBottom: "0.15rem" }}>{objekt.name}</h1>
           <div className="text-muted">
-            {objekt.code} · {akte.objekttyp_name}
+            {objekt.code} · {akte.objekttyp_name} · Objekt-Status: {objekt.status}
           </div>
         </div>
-        <span className="badge badge-neutral">{objekt.status}</span>
+        <ReadinessBadge status={akte.einsatzbereitschaft_status} />
       </div>
+      {akte.einsatzbereitschaft_gruende.length > 0 && (
+        <ul className="card-list" style={{ marginTop: "0.5rem" }}>
+          {akte.einsatzbereitschaft_gruende.map((g) => (
+            <li key={g} className="text-muted" style={{ fontSize: "0.9rem" }}>
+              • {GRUND_TEXT[g] ?? g}
+            </li>
+          ))}
+        </ul>
+      )}
 
       <div className="card" style={{ marginTop: "1rem" }}>
         <h3 style={{ marginTop: 0 }}>Stammdaten</h3>
@@ -118,16 +130,7 @@ export function AktePage() {
 
       <div className="card" style={{ marginTop: "1rem" }}>
         <h3 style={{ marginTop: 0 }}>Dokumente</h3>
-        {akte.dokumente.length === 0 && <p className="text-muted">Keine Dokumente hinterlegt.</p>}
-        {akte.dokumente.length > 0 && (
-          <ul>
-            {akte.dokumente.map((d) => (
-              <li key={d.id}>
-                {d.dateiname} <span className="text-muted">({Math.round(d.groesse_bytes / 1024)} KB)</span>
-              </li>
-            ))}
-          </ul>
-        )}
+        <DokumentePanel entitaetTyp="objekt" entitaetId={String(objekt.id)} onFehler={setFehler} />
       </div>
 
       <div className="card" style={{ marginTop: "1rem" }}>

frontend/src/pages/DashboardPage.tsx

@@ -7,6 +7,7 @@ import { InspectionStatus } from "../components/status/InspectionStatus";
 import { InventoryStatus } from "../components/status/InventoryStatus";
 import type { Readiness } from "../components/status/ReadinessBadge";
 import { ReadinessBadge } from "../components/status/ReadinessBadge";
+import { GRUND_TEXT } from "../components/status/gruendeText";
 
 interface Kennzahlen {
   anzahl_offener_fehlbestaende: number;
@@ -69,18 +70,6 @@ function readinessVonGruenden(gruende: string[]): Readiness {
   return "not-ready";
 }
 
-const GRUND_TEXT: Record<string, string> = {
-  fehlbestand_offen: "Offener Fehlbestand",
-  ablaufdatum_abgelaufen: "Ablaufdatum überschritten",
-  pruefung_ueberfaellig: "Geräteprüfung überfällig",
-  kontrolle_laeuft: "Kontrolle läuft (gesperrt)",
-  mangel_kritisch_offen: "Kritischer Mangel offen",
-  in_wartung: "In Wartung",
-  hu_uvv_ueberfaellig: "HU/UVV überfällig",
-  noch_nie_kontrolliert: "Noch nie kontrolliert",
-  mindermenge_genehmigt: "Mindermenge genehmigt",
-};
-
 // Leitungs-Dashboard (Karte-Nachtrag): zwei neue Kacheln (Einsatzbereitschaft,
 // Prüftermine) plus die bestehende Ablaufdaten-Kachel, alle drei eigenständig -
 // widersprechen sich nicht, da überfällige Prüfung/Ablauf beide zusätzlich als