# Anleitung Bedienung von FLORIAN, Stand Phase 1 (Version 0.2.0). Die Bilder zeigen die Beispielwehr aus dem Seed und werden mit `npm run screenshots` neu erzeugt. > Prüfungen, Einsätze, Atemschutz und die Kiosk-Oberfläche kommen in den > folgenden Phasen dazu. Siehe [ROADMAP.md](ROADMAP.md). --- ## 1. Anmelden Aufgerufen wird FLORIAN im Browser unter der Adresse, die der Administrator eingerichtet hat — in der Entwicklung `http://localhost:3100`. ![Anmeldeseite](screenshots/01-anmeldung-light.png) Die Anmeldeseite zeigt genau die Wege, die in dieser Installation eingerichtet sind: | Weg | Wann | |---|---| | **Anmeldung über authentik** | Der Regelweg, sobald authentik eingerichtet ist. Ein Klick, keine Passworteingabe in FLORIAN. | | **E-Mail und Passwort** | Beim Erststart, und wenn authentik gerade nicht erreichbar ist. | | **Terminal im Gerätehaus** | Am Wandtablet, mit PIN oder Ausweiskarte. Eigene Oberfläche, kommt in Phase 4. | Beim allerersten Start gibt es genau ein Konto: das aus `SEED_ADMIN_EMAIL` und `SEED_ADMIN_PASSWORT` in der `.env`. Vorgabe: ``` admin@beispielwehr.de Feuerwehr2026 ``` **Dieses Passwort gehört nach dem ersten Login geändert.** ### Wenn die Anmeldung nicht klappt Nach mehreren Fehlversuchen wird das Konto vorübergehend gesperrt — voreingestellt nach fünf Versuchen für fünf Minuten (`KIOSK_MAX_FEHLVERSUCHE`, `KIOSK_SPERRDAUER`). Die Meldung nennt nicht, ob die E-Mail-Adresse oder das Passwort falsch war; das ist Absicht und verhindert, dass sich vorhandene Konten erraten lassen. --- ## 2. Die Übersicht Nach der Anmeldung steht die Übersicht der eigenen Wehr. ![Übersicht](screenshots/02-uebersicht-light.png) Von oben nach unten: **Kopfzeile.** Name der Wehr und darunter, wer angemeldet ist und mit welchen Rollen. Wer mehrere Rollen trägt — der Gerätewart ist oft auch Ausbilder — sieht alle. **Sicherheitshinweis.** Der gelbe Kasten bleibt stehen, solange die Wehr die Anwendung nicht ausdrücklich freigegeben hat. Er ist keine Formalität: Atemschutzüberwachung und Alarmmonitor sind sicherheitsrelevant, und bis zur Freigabe bleibt die analoge Überwachung führend. **Kennzahlen.** Vier Kacheln mit aktiven Mitgliedern, Fahrzeugen, Geräten und fälligen Prüfungen. Sie zählen nur die eigene Wehr — was eine andere Wehr auf derselben Installation hat, ist nicht sichtbar und nicht abfragbar. **Stand des Aufbaus.** Welche Phasen fertig sind und was als Nächstes kommt. ### Die Seitenleiste Links stehen alle Module. Was noch nicht existiert, ist ausgegraut und trägt rechts sein Phasenkürzel — `P2` heißt „kommt in Phase 2". Was jemand überhaupt sieht, hängt an seinen Rechten. Ein einfaches Mitglied sieht die Mitgliederliste, aber nicht das Protokoll. Wichtig zum Verständnis: das Ausblenden ist nur Bequemlichkeit. Der eigentliche Schutz sitzt auf dem Server — wer eine Adresse direkt aufruft, für die ihm das Recht fehlt, bekommt trotzdem nichts. --- ## 3. Helle und dunkle Darstellung Oben rechts wird zwischen hell und dunkel umgeschaltet. Voreingestellt ist die Einstellung des Betriebssystems. ![Übersicht in dunkler Darstellung](screenshots/02-uebersicht-dark.png) Die dunkle Darstellung ist bewusst kein invertiertes Schwarz, sondern ein warmes Grau. Wer abends vom Fahrzeug hereinkommt und ans Terminal tritt, soll nicht geblendet werden. --- ## 4. Geräte ![Geräteliste](screenshots/03-geraeteliste-light.png) Die Geräteliste ist die Ansicht, die am häufigsten offen ist. Von links nach rechts steht dort, was man beim Suchen braucht: Inventarnummer, was es ist, von wem, wo es liegt, in welchem Zustand und wann es wieder geprüft werden muss. ### Suchen und filtern **Das Suchfeld** durchsucht Inventarnummer, Bezeichnung, Hersteller, Modell und Seriennummer gleichzeitig. Es genügt ein Teil — „press" findet alle Pressluftatmer. Gesucht wird erst, wenn man kurz aufhört zu tippen; das verhindert eine Abfrage bei jedem Anschlag. **Alle Zustände** schränkt auf einen Status ein. Praktisch, wenn man wissen will, was gerade fällig oder gesperrt ist. **Spalten** blendet Spalten ein und aus. Zwölf stehen zur Auswahl, sechs sind voreingestellt. Die Auswahl bleibt im Browser gespeichert — der Gerätewart schaut auf Prüftermine, der Kassier auf Anschaffungspreise, und beide finden ihre Einstellung beim nächsten Mal wieder. **Sortiert** wird durch einen Klick auf die Spaltenüberschrift, ein zweiter Klick dreht die Richtung um. ### Farben und Fristen | Farbe | Bedeutung | |---|---| | grün | einsatzbereit | | gelb | Prüfung fällig, oder eine Frist läuft in den nächsten 30 Tagen ab | | rot | gesperrt, ausgesondert oder überfällig | | grau | in Reparatur | Hinter jedem Datum steht, wie viele Tage noch bleiben — „in 12 Tagen" sagt mehr als ein Datum, das man erst im Kopf ausrechnen muss. Was vorbei ist, steht als „seit 62 Tagen" da. Die Farbe allein trägt nie die Information: daneben steht immer Klartext. ### Mehrere Geräte auf einmal Über die Kästchen links lassen sich Geräte auswählen. Sobald mindestens eines ausgewählt ist, erscheint eine Leiste mit zwei Möglichkeiten: - **Etiketten drucken** erzeugt den Etikettenbogen als PDF. - **Status setzen auf …** ändert den Zustand aller ausgewählten Geräte. Der häufigste Handgriff überhaupt: Nach einer Sammelprüfung stehen zwanzig Geräte auf einmal wieder auf einsatzbereit. Jede Änderung wird einzeln protokolliert — am jeweiligen Gerät, nicht als Sammelvorgang, den später niemand mehr zuordnen kann. --- ## 5. Ein einzelnes Gerät ![Gerätedetail](screenshots/04-geraet-light.png) ### Woher das Prüfintervall kommt Steht am Gerät kein eigenes Intervall, gilt die Vorgabe des Gerätetyps. Das Bild zeigt es: „alle 12 Monate (aus dem Gerätetyp)". So muss man bei vierzig Pressluftatmern nicht vierzigmal dasselbe eintragen. Schreibt der Hersteller für eine bestimmte Charge etwas anderes vor, wird der Wert am Gerät gesetzt und gewinnt dann. Dasselbe gilt für die Lebensdauer. Ob sie ab Herstellung oder ab Indienststellung zählt, hängt von der Vorschrift ab: Seile und Druckbehälter altern ab Herstellung, Schutzkleidung meist ab Indienststellung. ### QR-Code Rechts steht der QR-Code des Geräts. **Etikett drucken** erzeugt daraus einen Aufkleber für den Geräteraum. Der Code zeigt auf `.../g/`. Wer ihn scannt und angemeldet ist, landet direkt auf dieser Seite. Wer nicht angemeldet ist, landet zuerst auf der Anmeldung und danach hier — **der Aufkleber ist keine Berechtigung.** Wer ihn fotografiert, bekommt dadurch keinen Zugang. Bewusst steht die Inventarnummer im Code und nicht die interne Kennung: Eine UUID wäre 36 Zeichen lang, das Muster entsprechend fein, und auf einem 38 × 21 mm großen Aufkleber im staubigen Geräteraum wird das unzuverlässig. ### Verlauf Unten steht, was mit dem Gerät passiert ist — direkt aus dem Audit-Log. Es gibt bewusst keine zweite Historie: zwei Quellen könnten auseinanderlaufen. --- ## 6. Etiketten drucken Der Bogen ist auf das gängige Format mit **65 Etiketten je DIN-A4-Seite** (38,1 × 21,2 mm, 5 Spalten × 13 Zeilen) ausgelegt — den gibt es in jedem Schreibwarenladen und er passt in jeden Laserdrucker. Auf jedem Etikett stehen drei Dinge: der QR-Code, die Inventarnummer zum Ablesen ohne Handy, und die Bezeichnung. Bei verlasteten Geräten kommt der Funkrufname des Fahrzeugs dazu. Der Druck kann an einer beliebigen Position des Bogens beginnen. Wer drei Etiketten braucht, muss so keinen ganzen Bogen opfern. > Erzeugt wird das PDF von Gotenberg, einem eigenen Container im Stack. Kommt > die Meldung „Der Etikettenbogen ließ sich nicht erzeugen", läuft er nicht: > `docker compose ps` zeigt es. --- ## 7. Gerät scannen Über **Scannen** in der Geräteliste öffnet sich der QR-Scanner. Der Browser fragt beim ersten Mal nach der Kamerafreigabe. Das Bild verlässt das Gerät nicht — ausgewertet wird direkt im Browser. Zwei Dinge sind bewusst so gebaut: - **Es geht immer auch ohne Kamera.** Darunter steht ein Eingabefeld für die Inventarnummer. Wenn die Freigabe verweigert wurde oder das Etikett zerkratzt ist, tippt man sie ein. - **Fremde Codes brechen nichts ab.** Der Barcode des Herstellers klebt oft direkt daneben. Wird er erkannt, kommt ein Hinweis statt einer Fehlermeldung. --- ## 8. Fahrzeuge ![Fahrzeugdetail](screenshots/06-fahrzeug-light.png) Die Übersicht zeigt die Fahrzeuge als Kacheln — eine Wehr hat drei bis zehn, nicht dreihundert. Auf jeder Kachel stehen der nächste TÜV-Termin und die Zahl der verlasteten Geräte. Auf der Detailseite steht die **Beladung nach Geräteräumen**, in der Reihenfolge der Beladeordnung: G1 bis G6, Heck, Dach, Mannschaftsraum. Genau so sucht der Gerätewart — nicht „wo ist die Motorsäge", sondern „was ist in G3". Beim Anlegen eines neuen Fahrzeugs werden diese Räume auf Wunsch gleich mitangelegt. Ein Mannschaftstransportwagen bekommt weniger Fächer als ein Löschfahrzeug. Ein Gerät liegt **entweder** an einem Standort **oder** auf einem Fahrzeug. Beides gleichzeitig lässt die Datenbank nicht zu — das ist keine Formalität, sondern verhindert, dass ein Gerät zweimal gezählt wird. Was verlastet ist, aber keinem Raum zugeordnet wurde, erscheint unter „Ohne Raumangabe" statt stillschweigend zu verschwinden. --- ## 9. Mitglieder und Qualifikationen ![Qualifikationen](screenshots/08-qualifikationen-light.png) Die Mitgliederliste ist nach Abteilung gruppiert — Aktive, Jugendfeuerwehr, Passive. Eine durchlaufende alphabetische Liste vermischt Gruppen, die in der Wehr nichts miteinander zu tun haben. Auf der Seite **Qualifikationen** steht oben, was abgelaufen ist oder demnächst abläuft. Das ist der Grund, warum jemand diese Seite öffnet. **Gewarnt wird mit der Vorwarnzeit des jeweiligen Typs**, nicht mit einer pauschalen Frist. Eine G26.3-Untersuchung braucht 120 Tage Vorlauf, weil erst ein Termin beim Betriebsarzt gefunden werden muss; eine jährliche Unterweisung kommt mit deutlich weniger aus. Einsatzrelevante Qualifikationen sind gekennzeichnet. Das Ablaufdatum wird beim Speichern aus der Gültigkeitsdauer des Typs gerechnet — lässt sich aber überschreiben. Auf einer Urkunde steht manchmal etwas anderes, als die Regel hergäbe. --- ## 10. Daten importieren ![Import-Assistent](screenshots/09-import-light.png) Der Import geht in drei Schritten, und der mittlere ist der eigentliche Punkt. ### Schritt 1: Datei wählen CSV oder Excel (`.xlsx`). Die erste Zeile muss die Spaltenüberschriften enthalten. Höchstens 10 MB und 5.000 Zeilen. Erkannt werden die Formate, die in der Praxis herauskommen: | Fall | Wird verstanden | |---|---| | Trennzeichen | Semikolon, Komma, Tabulator, senkrechter Strich | | Zeichensatz | UTF-8 (auch mit BOM) und Windows-1252 | | Datum | 02.09.2026, 2.9.26, 2026-09-02, und die Seriennummer aus Excel | | Zahlen | 1.234,56 und 1,234.56, mit und ohne Eurozeichen | | Ja/Nein | ja, j, x, 1, wahr — und die Gegenstücke | ### Schritt 2: Zuordnung prüfen FLORIAN rät die Zuordnung anhand der Überschriften. „Inv.-Nr." landet bei Inventarnummer, „Fabrikat" bei Hersteller. Jede Zuordnung lässt sich ändern, und die Vorschau passt sich sofort an. **Die Vorschau ist der Grund, warum es diesen Zwischenschritt gibt.** Sie zeigt Zeile für Zeile, was übernommen würde, und markiert rot, was nicht stimmt: fehlende Pflichtfelder, unlesbare Daten, Inventarnummern, die in der Datei doppelt vorkommen. Eine falsch zugeordnete Spalte verteilt sonst Seriennummern auf Inventarnummern, und das merkt man erst Wochen später am Regal. ### Schritt 3: Übernehmen Übernommen wird nur, was fehlerfrei ist. Zeilen mit Fehlern bleiben in der Datei und lassen sich nach der Korrektur erneut einlesen. **Vorhandene Datensätze aktualisieren** entscheidet, was mit Datensätzen passiert, die es schon gibt: überspringen (Vorgabe) oder überschreiben. Erkannt werden sie über die Inventarnummer, bei Mitgliedern über die Mitgliedsnummer oder die E-Mail-Adresse. Zum Schluss steht da, wie viele Datensätze angelegt, aktualisiert und übersprungen wurden. Der ganze Vorgang steht auch im Protokoll. --- ## 11. Rollen und was sie dürfen Neun Rollen, jede mit einem festen Satz Rechte. Die Zuordnung steht zentral in `src/lib/authz.ts` und wird beim Seed in die Datenbank gespiegelt — eine Wehr kann sie also nachträglich zuschneiden, ohne dass jemand Code ändert. | Rolle | Darf im Kern | |---|---| | **Administrator** | alles, auch über Wehren hinweg | | **Kommandant** | alles innerhalb der eigenen Wehr, einschließlich Rollen vergeben und Protokoll einsehen | | **Gerätewart** | Fahrzeuge und Geräte anlegen, ändern, aussondern; Prüfungen planen und durchführen | | **Atemschutzgerätewart** | zusätzlich Atemschutzgeräte, Träger und die Überwachung nach FwDV 7 | | **Kassier** | Buchungen und Kassenabschluss (Modul noch nicht geplant, siehe Roadmap) | | **Schriftführer** | Mitglieder pflegen, Einsätze und Berichte erfassen | | **Ausbilder** | Übungen planen, Teilnahme und Qualifikationen erfassen | | **Mitglied** | eigene Daten, Listen lesen | | **Terminal** | nur anmelden und erfassen — nie verwalten | Zwei Dinge sind bewusst so gebaut: **Der Gerätewart kommt nicht an die Kasse, der Kassier nicht an die Geräte.** Trennung nach Verantwortung, nicht nach Bequemlichkeit. **Das Terminal darf fast nichts.** Wer am Wandtablet arbeitet, meldet sich zusätzlich mit PIN oder Karte an und handelt dann unter seiner eigenen Person. Das Terminal selbst ist nur die Tür. --- ## 12. Anmeldung über authentik einrichten authentik läuft **getrennt** von FLORIAN und ist nicht Teil dieses Stacks. ### In authentik 1. Neuen Provider anlegen, Typ **OAuth2/OpenID Provider** 2. Client-Typ: **Confidential** 3. Redirect-URI genau so eintragen: ``` https:///api/auth/callback/authentik ``` 4. Scopes: `openid`, `profile`, `email` 5. Für die Rollenvorbelegung zusätzlich ein Scope-Mapping, das die Gruppen des Benutzers als Claim `groups` ausliefert 6. Eine Application anlegen und mit dem Provider verbinden. Der Slug der Application ist der letzte Teil der Issuer-URL. ### In der `.env` ```bash AUTH_OIDC_ENABLED=true AUTH_OIDC_ISSUER=https://auth.beispiel.de/application/o/florian/ AUTH_OIDC_CLIENT_ID= AUTH_OIDC_CLIENT_SECRET= AUTH_OIDC_GROUP_CLAIM=groups AUTH_OIDC_GROUP_MAPPING=feuerwehr-kommandant:KOMMANDANT,feuerwehr-geraetewart:GERAETEWART AUTH_OIDC_AUTO_PROVISION=true AUTH_OIDC_STANDARD_ORGANISATION=ff-musterhausen ``` Danach die Anwendung neu starten. Auf der Anmeldeseite erscheint der Knopf für authentik. ### Wie die Rollenvorbelegung wirkt Die Zuordnung greift **nur beim allerersten Login** einer Person. Danach ist die in FLORIAN gepflegte Rolle führend, und authentik überschreibt sie nicht mehr. Wer also einem Mitglied in FLORIAN die Rolle „Gerätewart" gibt, behält sie — auch wenn die authentik-Gruppe etwas anderes sagt. Steht `AUTH_OIDC_AUTO_PROVISION=false`, muss die Person vorher in FLORIAN angelegt sein. Verknüpft wird über die E-Mail-Adresse. ### Wenn authentik ausfällt Solange `AUTH_LOCAL_ENABLED=true` steht, bleibt der Passwort-Login als Rückfallweg erreichbar. Für den Wirkbetrieb ist es sinnvoll, mindestens ein Konto mit Passwort zu behalten — sonst sperrt ein Ausfall von authentik die ganze Wehr aus. --- ## 13. Terminal-Anmeldung im Gerätehaus Die Oberfläche dazu kommt in Phase 4; der Anmeldeweg steht bereits. Am Terminal wird zweifach geprüft: 1. **Das Gerät** weist sich mit `KIOSK_DEVICE_SECRET` aus. Ohne diesen Wert nimmt der Server keine PIN und keine Karte an. 2. **Die Person** meldet sich mit einer sechsstelligen PIN (zusammen mit ihrer Mitgliedsnummer) oder mit einer RFID-Karte an. Beides wird nur als Hash gespeichert — weder die PIN noch die Kartenkennung liegen im Klartext in der Datenbank. PINs, die sich zu leicht raten lassen, weist FLORIAN ab: lauter gleiche Ziffern und fortlaufende Folgen wie `123456`. Aus dem Seed lässt sich das ausprobieren: Mitgliedsnummer `0001` (Andreas Huber), PIN `471203`. --- ## 14. Was protokolliert wird Jede schreibende Änderung erzeugt einen Eintrag mit Zeitpunkt, Person, betroffenem Datensatz und den geänderten Feldern im Vorher-Nachher-Vergleich. Auch jede Anmeldung — erfolgreich wie gescheitert. Zwei Eigenschaften sind wichtig: **Der Log lässt sich nicht ändern.** Nicht über die Oberfläche, nicht über die Datenbank, auch nicht vom Administrator. Die Datenbank selbst verhindert es. **Er lässt sich nur im Aufbewahrungslauf kürzen.** Nach der eingestellten Frist (`AUDIT_AUFBEWAHRUNG_TAGE`, Vorgabe 10 Jahre) sichert der Hintergrundprozess die alten Einträge und entfernt sie danach. Das ist der einzige Weg, auf dem etwas aus dem Log verschwindet. **Passwörter, PINs und Kartenkennungen stehen nie im Log** — sie werden vor dem Schreiben herausgenommen. Einsehbar ist der Log mit dem Recht `system.auditlog`, das Kommandant und Administrator haben. Am Gerät und am Fahrzeug ist der Verlauf bereits auf der jeweiligen Detailseite sichtbar. --- ## 15. Wenn etwas nicht geht | Beobachtung | Wahrscheinliche Ursache | Was hilft | |---|---|---| | Die Anwendung startet nicht und meldet fehlende Variablen | `.env` unvollständig | Die Meldung nennt jede fehlende Variable. Erklärungen dazu stehen in `.env.example`. | | Anmeldung schlägt immer fehl, obwohl das Passwort stimmt | Konto nach Fehlversuchen gesperrt | Fünf Minuten warten, oder `gesperrtBis` in der Datenbank zurücksetzen | | Listen sind leer, obwohl Daten da sind | Kein Mandantenkontext gesetzt | Das ist der Schutzmechanismus. Der Zugriff muss über `fuerOrganisation()` laufen. | | Dateien lassen sich nicht hochladen | MinIO nicht erreichbar oder Bucket fehlt | `http://localhost:9011` öffnen; `docker compose logs minio-init` | | Der Knopf für authentik fehlt | Issuer, Client-ID oder Secret nicht gesetzt | Alle drei sind nötig, sonst wird der Weg ausgeblendet | | Etikettenbogen lässt sich nicht erzeugen | Gotenberg läuft nicht | `docker compose ps`, dann `docker compose up -d gotenberg` | | Kamera bleibt schwarz | Freigabe abgelehnt, oder die Seite läuft nicht über HTTPS | Der Browser fragt nur bei HTTPS oder localhost. Sonst die Inventarnummer eintippen | | Import meldet fehlende Pflichtfelder | Keine Spalte ist Inventarnummer oder Bezeichnung zugeordnet | In Schritt 2 die Zuordnung von Hand setzen | | Umlaute im Import verstümmelt | Die Datei ist weder UTF-8 noch Windows-1252 | In Excel als „CSV UTF-8" speichern | | Gerät lässt sich nicht speichern | Standort **und** Fahrzeug gesetzt, oder keines von beidem | Genau eines von beiden angeben | | `docker compose up` startet Traefik mit | Override-Datei wurde nicht mitgeladen | In Produktion `-f docker-compose.yml` angeben | Zustand aller Randsysteme auf einen Blick: ``` http://localhost:3100/api/health ``` Antwortet mit `200` und `"status": "ok"`, wenn Datenbank, Objektspeicher und Warteschlange erreichbar sind — sonst mit `503` und der Angabe, welcher Dienst fehlt. --- ## Bilder erneuern ```bash docker compose up -d npm run dev npm run screenshots ``` Die Bilder entstehen in `docs/screenshots/`, jeweils in heller und dunkler Darstellung, und werden mit eingecheckt — die Anleitung soll auch dann lesbar sein, wenn gerade kein Stack läuft.