MABEA/arbeitskacheln/03_digital_file.md

# Epic 03 — Digital File (Akte)

Details zu FILE-001 … FILE-009. FILE-001-007 vollständig, FILE-008 ergänzt am 2026-09-09
aus Open-Source-Vergleich (KP Front/InvenTree), FILE-009 (Notizen) ergänzt am
2026-09-10 — beide offen/ungeplant.

---

## FILE-001 — Akte-Grundgerüst

- **Ziel:** Zentrale Entität, die alle Teilbereiche einer Ressource bündelt.
- **Beschreibung:** Konzeptionelle „Akte" muss keine eigene Tabelle sein, sondern eine
  Aggregations-Sicht (View/Backend-Endpunkt), der Stammdaten+Standort+Historie+Dokumente+
  Prüfungen+Wartungen+Mängel für eine gegebene Ressourcen-ID zusammenführt.
- **Benutzerwert:** Ein Helfer/Prüfer sieht auf einen Blick alles zu einer Ressource, ohne
  mehrere Screens durchklicken zu müssen.
- **Abhängigkeiten:** IDENT-001
- **Datenmodell:** kein neues Datenmodell — Aggregations-Logik über bestehende Tabellen (die
  zum Zeitpunkt dieser Kachel z.T. noch nicht existieren, daher zunächst nur
  Stammdaten+Historie als Platzhalter, Rest wird nachgezogen sobald die jeweiligen Module
  existieren)
- **Backend:** GET /akte/{ressourcen_id} (aggregiert)
- **Frontend/Mobile:** —
- **QR-Code:** Ziel des QR-Scans (IDENT-008)
- **Seriennummer/Inventarnummer:** werden hier nur angezeigt, nicht neu verwaltet
- **Akte:** ist diese Kachel selbst
- **Rechte:** Lesen wie Ressourcen-Leserecht
- **Audit:** Akte-Aufruf selbst wird NICHT geloggt (zu granular/kein Mehrwert), nur
  Änderungen an den Teilbereichen
- **Akzeptanzkriterien:** Endpunkt liefert für eine existierende Ressourcen-ID ein
  zusammengesetztes JSON, für unbekannte ID 404.
- **Tests:** Aggregations-Test mit Dummy-Daten in mind. zwei Teilbereichen.
- **DoD:** Grundgerüst erweiterbar, ohne bestehende Endpunkt-Konsumenten zu brechen, wenn
  neue Teilbereiche dazukommen.

## FILE-002 — Akte-Stammdatenbereich

- **Ziel:** Feste, immer sichtbare Kopfzeile jeder Akte.
- **Beschreibung:** Name, Kategorie/Typ, Inventarnummer, Seriennummer, Hersteller/Modell,
  Status-Badge gebündelt.
- **Benutzerwert:** Sofortige Grundorientierung ohne Scrollen.
- **Abhängigkeiten:** FILE-001, IDENT-002/004/005, ASSET-004
- **Datenmodell:** keins neu, reine Aggregation
- **Backend:** Teil des FILE-001-Aggregations-Endpunkts
- **Frontend:** Kopfzeilen-Komponente
- **Mobile:** kompakte Variante (Karte statt Tabellenzeile)
- **QR-Code:** Druckbutton hier verankert (IDENT-007)
- **Seriennummer/Inventarnummer:** zentrale Anzeige hier
- **Akte:** ist dieser Bereich selbst
- **Rechte:** wie Lese-Recht
- **Audit:** nein (nur Anzeige)
- **Akzeptanzkriterien:** alle Kernfelder korrekt angezeigt, Status-Badge farbcodiert.
- **Tests:** Rendering-Test mit Beispieldaten.
- **DoD:** an mind. zwei unterschiedlichen Ressourcentypen (z.B. Fahrzeug + Gerät) getestet.

## FILE-003 — Akte-Standortbereich

- **Ziel:** Aktueller Standort direkt sichtbar, mit Sprung zur vollständigen
  Standorthistorie.
- **Beschreibung:** Anzeige aktueller Standort (Lagerplatz/Fahrzeug/Person), Link zu
  WH-Modul für Details.
- **Benutzerwert:** „Wo ist das Ding gerade" ist die häufigste Frage im Alltag.
- **Abhängigkeiten:** FILE-001, WH-001 (zumindest Platzhalter-Standortfeld, bevor
  Warehouse-Epic fertig ist)
- **Datenmodell:** Referenz auf aktuellen Standort (Feld existiert ggf. schon am Asset,
  hier nur Anzeige)
- **Backend:** Teil des Aggregations-Endpunkts
- **Frontend:** Standort-Kachel in der Akte
- **Mobile:** gleiche Anzeige, kompakt
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** ist dieser Bereich
- **Rechte:** wie Lese-Recht
- **Audit:** nein (Standortänderung selbst wird in WH-Modul geloggt, hier nur Anzeige)
- **Akzeptanzkriterien:** aktueller Standort korrekt, Link funktioniert.
- **Tests:** Rendering-Test.
- **DoD:** funktioniert, sobald WH-001 minimal existiert (auch als Platzhalter-Freitextfeld
  vor vollem Warehouse-Modul akzeptabel).

## FILE-004 — Akte-Verantwortlichkeitsbereich

- **Ziel:** Klar erkennbar, wer für eine Ressource zuständig ist.
- **Beschreibung:** Anzeige zuständige Person/Einheit (aus Personnel-Epic).
- **Benutzerwert:** Ansprechpartner bei Fragen/Problemen sofort ersichtlich.
- **Abhängigkeiten:** FILE-001, PERS-003 (zumindest Einheiten-Grundgerüst)
- **Datenmodell:** Referenz auf zuständige Einheit/Person
- **Backend:** Teil des Aggregations-Endpunkts
- **Frontend:** Verantwortlichkeits-Kachel
- **Mobile:** gleiche Anzeige
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** ist dieser Bereich
- **Rechte:** wie Lese-Recht; Ändern nur Administrator/Zugführer
- **Audit:** Änderung wird geloggt
- **Akzeptanzkriterien:** Zuständigkeit anzeigen/ändern funktioniert, Änderung geloggt.
- **Tests:** Anzeige- und Änderungstest.
- **DoD:** funktioniert mit mind. einer Einheit.

## FILE-005 — Akte-Historienbereich

- **Ziel:** Chronologische Ereignisliste je Ressource, direkt in der Akte statt in einem
  separaten globalen Log.
- **Beschreibung:** Gefilterte Sicht auf FOUND-006 (Audit-Log), gefiltert nach
  `entitaet_id`.
- **Benutzerwert:** „Was ist mit diesem Gerät in letzter Zeit passiert" auf einen Blick.
- **Abhängigkeiten:** FILE-001, FOUND-006
- **Datenmodell:** keins neu
- **Backend:** Filter-Query auf Audit-Log nach Ressourcen-ID
- **Frontend:** Zeitleisten-Komponente in der Akte
- **Mobile:** kompakte Liste
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** ist dieser Bereich
- **Rechte:** wie Lese-Recht (evtl. eingeschränkter als Vollzugriff auf globales Audit-Log)
- **Audit:** zeigt Audit-Daten, erzeugt selbst keine
- **Akzeptanzkriterien:** Ereignisse chronologisch, korrekt gefiltert auf die Ressource.
- **Tests:** Filter-Test mit mehreren Ressourcen (keine Vermischung).
- **DoD:** mind. drei unterschiedliche Ereignistypen sichtbar getestet.

## FILE-006 — Akte-Übersichtsseite (UI)

- **Ziel:** EIN Screen, der alle Teilbereiche zusammen zeigt.
- **Beschreibung:** Frontend-Seite, konsumiert den FILE-001-Aggregations-Endpoint, rendert
  FILE-002…005 untereinander (Desktop) bzw. als Tabs (Mobile).
- **Benutzerwert:** zentrale Anlaufstelle je Ressource — Zielseite des QR-Scans (IDENT-008).
- **Abhängigkeiten:** FILE-002…005
- **Datenmodell:** keins
- **Backend:** keins zusätzlich
- **Frontend:** Seite `/akte/{typ}/{id}`
- **Mobile:** responsive Variante (Tabs statt nebeneinander)
- **QR-Code:** Zielseite von IDENT-008
- **Seriennummer/Inventarnummer:** Anzeige via FILE-002
- **Akte:** ist diese Kachel selbst
- **Rechte:** wie Lese-Recht
- **Audit:** nein
- **Akzeptanzkriterien:** Seite lädt alle Teilbereiche fehlerfrei; fehlende Teilbereiche
  (z.B. noch keine Dokumente) zeigen „keine Daten" statt Fehler.
- **Tests:** Rendering-Test mit vollen Daten, Rendering-Test mit leeren Teilbereichen.
- **DoD:** von IDENT-008 aus erreichbar, produktiv nutzbar.

## FILE-007 — Akte-Audit-Anbindung

- **Ziel:** Sicherstellen, dass jede Änderung an einem Akte-Teilbereich auch im
  Historienbereich (FILE-005) auftaucht — keine stillen Lücken.
- **Beschreibung:** Audit-Log-Aufrufe an den Schreib-Endpunkten der Teilbereiche
  systematisch nachrüsten/verifizieren (Konsistenz-Check über alle Mutations-Endpunkte).
- **Benutzerwert:** Vertrauen, dass die Akte-Historie wirklich vollständig ist.
- **Abhängigkeiten:** FILE-005
- **Datenmodell:** keins
- **Backend:** Audit-Log-Aufruf-Vervollständigung, ggf. Lint-Regel/Test dagegen
- **Frontend/Mobile:** keins
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** Qualitätssicherung für den Historienbereich
- **Rechte:** keine neuen
- **Audit:** ist Gegenstand dieser Kachel
- **Akzeptanzkriterien:** für jeden Schreibendpunkt eines Akte-Teilbereichs existiert ein
  Audit-Log-Test.
- **Tests:** Coverage-Check „jeder Mutations-Endpunkt loggt".
- **DoD:** keine bekannte Lücke mehr — vgl. MABEA, wo genau diese Art Lücke (Mangel/
  Personal/Objekt-Änderungen ohne Audit-Eintrag) schon einmal real gefunden und gefixt
  wurde. Diese Kachel ist der methodische Nachfolgeschritt: systematisch statt punktuell.

## FILE-008 — Manipulationssicheres Audit-Journal (Hash-Kette, P2, neu)

- **Ziel:** Nachweisen können, dass ein Audit-Log-Eintrag nachträglich nicht verändert
  wurde — über reines Vorhandensein (FILE-007) hinaus.
- **Beschreibung:** Jeder Audit-Log-Eintrag bekommt zusätzlich einen Hash über
  (Eintragsinhalt + Hash des Vorgängereintrags) — bricht die Kette erkennbar, sobald
  irgendein historischer Eintrag verändert wird. Betrifft insbesondere Kontroll-
  Ergebnisse, Wartungsprotokolle und Soll/Ist-Korrekturbuchungen (WH-006), wo
  BOS-Dokumentationspflichten Nachweisbarkeit verlangen.
- **Benutzerwert:** Rechtssicherer Nachweis bei Prüfungen/Vorfällen, dass Protokolle
  echt und unverändert sind — nicht nur „es gibt einen Log-Eintrag", sondern „der
  Log-Eintrag ist beweisbar unverändert".
- **Abhängigkeiten:** FOUND-006 (Audit-Log), FILE-007
- **Datenmodell:** `historie.hash` (SHA-256 über Inhalt+Vorgänger-Hash) — **nicht**
  `audit_log`, MABEAs reale Tabelle heißt `historie` (`FOUND-006`). **Entschieden
  (2026-09-09): Kette läuft pro Ressource (Objekt-ID)**, nicht global — jedes
  Objekt hat seine eigene Kette, erster Eintrag je Objekt mit fixem
  Genesis-Wert. Verifikations-Endpoint prüft/meldet damit je Objekt einzeln statt
  eine einzige globale Bruchstelle für die ganze `historie`-Tabelle.
- **Backend:** Hash-Berechnung beim Schreiben, Verifikations-Endpoint (Kette prüfen,
  Bruchstelle melden falls vorhanden)
- **Frontend:** „Integrität geprüft ✓"-Anzeige im Akte-Historienbereich (FILE-005),
  Warnung bei Kettenbruch
- **Mobile:** nein
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** Vertrauensanzeige im Historienbereich
- **Rechte:** Verifikation: Administrator; Anzeige „geprüft"-Status: wie Lese-Recht
- **Audit:** ist Gegenstand dieser Kachel selbst
- **Akzeptanzkriterien:** nachträgliche Änderung eines historischen Eintrags (z.B. direkt
  in der DB) wird vom Verifikations-Lauf erkannt und gemeldet.
- **Tests:** Kettenbruch-Erkennungstest (Eintrag nachträglich manipuliert → Verifikation
  schlägt fehl), Normalfall-Test (unveränderte Kette → Verifikation erfolgreich).
- **DoD:** offen. **Referenz (Open-Source-Vergleich 2026-09-09):** KP Front
  (`feuerwehr-oberwil/kp-front`, AGPL-3.0-or-later — nur Muster) nutzt genau dieses
  Hash-Ketten-Prinzip für sein Einsatzjournal. Kombiniert mit InvenTree-Vorbild
  (lückenloser Stock-History-Trail bei jeder Bestandsänderung) — WH-006-Korrekturbuchungen
  sollten ebenfalls durch diese Kette laufen, sobald WH-006 umgesetzt wird.

## FILE-009 — Freitext-Notizen in der Akte (P2, neu, 2026-09-10)

- **Ziel:** Formlose, freie Notizen zu einer Ressource festhalten — Dinge, die in
  keinen strukturierten Teilbereich (Prüfung/Mangel/Wartung) passen.
- **Beschreibung:** Einfaches Freitextfeld je Ressource, mehrere Notizen möglich
  (chronologische Liste, nicht nur ein einzelnes Textfeld), mit Autor+Zeitstempel.
  Kein Rich-Text/Formatierung nötig, reiner Text reicht.
- **Benutzerwert:** Raum für Kontext, der sonst mündlich verlorengeht (z.B.
  „Funkgerät klemmt manchmal beim Einschalten, noch kein reproduzierbarer Fehler
  für ein Mangel-Ticket" oder „Rücksprache mit Hersteller am 12.03. — Ersatzteil
  in 2 Wochen").
- **Abhängigkeiten:** FILE-001
- **Datenmodell:** `akte_notiz` (id, entitaet_typ, entitaet_id, text, autor_id,
  erstellt_am) — polymorph wie `dokument` (DOC-001), gleiches Kopplungsmuster
- **Backend:** POST/GET/DELETE (Löschen nur eigene Notiz oder Administrator)
- **Frontend:** Notiz-Panel in der Akte (FILE-006-Übersichtsseite), Eingabefeld +
  chronologische Liste
- **Mobile:** Anzeige + Erfassung (einfaches Textfeld, kein Zusatzaufwand)
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** ist dieser Bereich selbst
- **Rechte:** Anlegen: Mitarbeiter+; Löschen: eigene Notiz oder Administrator
- **Audit:** Anlegen/Löschen geloggt
- **Akzeptanzkriterien:** mehrere Notizen chronologisch je Ressource sichtbar,
  Löschen nur durch Autor oder Administrator möglich.
- **Tests:** CRUD-Test, Berechtigungstest (fremde Notiz nicht löschbar außer als
  Administrator).
- **DoD:** offen.

---

**MABEA-Ist-Stand-Abgleich (aktualisiert 2026-09-05):** FILE-001…006 sind umgesetzt und
live deployed — `GET /api/v1/akte/objekt/{id}` bündelt Stammdaten/Standort/
Verantwortlichkeit/Historie/Dokumente/Geräte-Prüfungen/Mängel, Frontend-Seite
`/akte/objekt/{id}` konsumiert den Endpunkt, Link aus der Objektliste. **FILE-007**
(systematischer Audit-Konsistenz-Check über alle Mutations-Endpunkte) bewusst noch offen
gelassen — eigene, spätere Qualitätssicherungs-Kachel, keine Sichtbarkeits-/Nutzenlücke für
den Anwender. QR-Scan (IDENT-008) zeigt weiterhin auf die Kontrolle, nicht auf die Akte -
Verknüpfung dorthin ist ein kleiner Nachzug, kein Neubau.