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.