Laborbuch — Administrator-Handbuch

Laborprofil, Projekte, Benutzer und 2FA, Storno, Übersetzungen, Wochenabschlüsse, Backups, Lizenz, Updates.

Administrator-Handbuch der Laborbuch-Instanz — Konfiguration, Benutzer, Wochenabschlüsse, Backups und Lizenz. Die tägliche Arbeit beschreibt das Benutzerhandbuch.

Adminbereich

Der Adminbereich liegt unter /admin/ (Anmeldung mit demselben Konto und 2FA wie das Journal — der Adminbereich ist nicht ohne 2FA erreichbar). Zugriff haben Konten mit „Mitarbeiter”-Recht (staff); die volle Konfiguration erledigt der bei der Installation angelegte Superuser.

Erstkonfiguration — Seiteneinstellungen

Seiteneinstellungen → Laborprofil passt das System an die Arbeitsweise an:

Einstellung	Bedeutung
Git/GitHub-Integration	Repositories, Commit-Synchronisierung und Commit-Anker — Profil IT/Hardware; im Labor ohne Code deaktivieren
Datei-Anker (Uploads)	Beweisdateien an Einträge anhängen
Modus der Datei-Anker	`Upload` — Datei wird in der Instanz gespeichert; `Hash-only` — die Datei bleibt beim Benutzer, das System speichert nur den SHA-256-Fingerabdruck (Geschäftsgeheimnisse erreichen den Server nie)

Projekte

Projekte → Hinzufügen: Name, Slug, Vorhabens-Code (Zuordnung zum BSFZ-Antrag), Beschreibung der Abgrenzung FuE/Routine. Zwei Personenlisten:

Mitglieder — legen Einträge an und sehen die Projektdaten.
Beobachter — sehen Einträge und Berichte (Teamarbeit), aber ohne Stunden anderer Personen (Maskierung „—”) und ohne Eintragsrecht.

Ein neues Konto wird automatisch Mitglied aller aktiven Projekte, und ein neues Projekt erhält alle vorhandenen Konten. Der Ausschluss aus einem Projekt ist das bewusste Entfernen aus der Liste Mitglieder — eine einmal entfernte Person wird nicht erneut hinzugefügt.

Bei aktivem Git fügen Sie dem Projekt Repositories hinzu (Format owner/name; das Zugriffstoken wird in der Instanzkonfiguration als GITHUB_TOKEN gesetzt). Commits werden alle 15 Minuten geholt; manuell: Button im Dashboard oder Admin-Aktion Commits von GitHub synchronisieren.

Ein Fine-grained-Token deckt nur Repositories eines Ressourcenbesitzers ab; ein Organisations-Repository ist für das Token eines persönlichen Kontos unsichtbar (GitHub antwortet dann mit 404, nicht 403). Ein solches Repository erhält ein eigenes Token im Feld Zugriffstoken — ausgestellt auf die Organisation (Resource owner = Organisation, ausgewähltes Repository, Berechtigung Contents: Read-only); die Organisation muss den Zugriff über Fine-grained-PATs erlauben. Leeres Feld = globales Token. Die Aktion GitHub-Zugriff prüfen verifiziert die Konfiguration, ohne Commits zu holen.

Benutzer und 2FA

Benutzer → Hinzufügen: Login und Passwort, dann im Konto die Rechte („Mitarbeiter” für den Adminbereich) und Rollengruppen. Die 2FA-Methode legen Sie je Konto fest — unten auf der Benutzerseite:

2FA — TOTP (App / Hardware-Karte): Gerät hinzufügen; für Apps (z. B. Google Authenticator) wird der Schlüssel automatisch erzeugt — den QR-Code finden Sie beim Öffnen des Geräts im Bereich „TOTP devices”; für Hardware-Karten den Karten-Seed in key eintragen, Uhren-Drift über drift/tolerance korrigieren.
2FA — Code per E-Mail: Gerät hinzufügen; leeres email = Kontoadresse. Erfordert konfigurierten Mailversand (EMAIL_* in der Instanzkonfiguration).
Ein Konto ohne Gerät meldet sich nur mit Passwort an.

Das Lizenzlimit zählt aktive Konten: Bei ausgeschöpftem Limit lässt sich kein Konto anlegen oder aktivieren — Deaktivierung („aktiv” abwählen) gibt den Platz frei, ohne die Eintragshistorie zu verlieren.

Abrechnungsparameter (Bereich auf der Kontoseite) enthalten die persönliche Wochenobergrenze. Leeres Feld = globale Obergrenze der Instanz, standardmäßig 40 Std., also die Eigenleistungsregel nach § 3 Abs. 3 FZulG. Für Arbeitnehmer die vertragliche Arbeitszeit eintragen: Ihre Stunden sind in der tatsächlich geleisteten Höhe förderfähig, bei einer halben Stelle also 20 Std.; Überstunden eines Arbeitnehmers sind kein „FuE über der Obergrenze”. Die gesetzte Obergrenze erscheint auch im Dashboard der Person — im Wochenbalken und als Linie im Diagramm.

Welche Vorhaben auf die Obergrenze angerechnet werden. Auf die Wochenobergrenze werden nur Stunden der Vorhaben angerechnet, die der Administrator festlegt: Vorhaben → BSFZ-Status (direkt in der Liste bearbeitbar, Spalte „Auf Obergrenze angerechnet”). Vor der Antragstellung erhalten die Vorhaben des Antrags den Status „Eingereicht”. Nach dem Bescheid setzen Sie bescheinigte Vorhaben auf „Bescheinigt” und abgelehnte auf „Abgelehnt”: deren Stunden belegen die Obergrenze nicht mehr, und in derselben Woche wird Platz für „FuE über der Obergrenze” bei bescheinigten Vorhaben frei. Arbeit an anderen Projekten und an „nicht eingereichten” Vorhaben belegt die Obergrenze nicht. Solange kein Vorhaben den Status „Eingereicht” oder „Bescheinigt” hat, umfasst die Obergrenze alle Projekte zusammen. Ein Eintrag ohne Aufteilung auf Vorhaben (z. B. aus dem Dashboard) belegt die Obergrenze, wenn das Feld „Vorhaben” den Code eines angerechneten Vorhabens enthält; ein Eintrag mit Aufteilung — mit der Summe der Zuordnungen zu solchen Vorhaben.

Einträge, Korrekturen (Storno) und Übersetzungen

Einträge im Adminbereich: vollständige Liste mit Filtern. Einträge offener Wochen sind korrigierbar; abgeschlossene (🔒) sind endgültig schreibgeschützt.

Storno: neuen Eintrag mit negativen Stunden anlegen und im Feld corrects den korrigierten Eintrag angeben. Das Original bleibt — die Korrektur ist offen, wie in der Buchhaltung.
Übersetzungen: mit gesetztem TRANSLATE_AUTO_LANGS (z. B. de) wird jeder neue oder korrigierte Eintrag direkt nach dem Speichern automatisch im Hintergrund übersetzt. Lücken (ältere Einträge, kurzzeitige API-Störung) schließt der Bericht beim Generieren in der jeweiligen Sprache selbst — schubweise; massenhaft: manage.py translate_entries --lang de. Manuell: Einträge markieren → Aktion Ins Deutsche / Englische / Polnische übersetzen (Claude). Die Übersetzung ist ein separater Datensatz (Original unangetastet), wird einmal erstellt und kann unter Übersetzungen der Einträge manuell korrigiert werden. Erfordert ANTHROPIC_API_KEY; jede Übersetzung ist ein kostenpflichtiger API-Aufruf — aber nur einer pro Eintrag und Sprache.
Anker (Bereich im Eintrag): Commits, Dateien (Hash automatisch), mtime, Ereignisprotokoll, Sonstiges.

Wochenabschluss — der Arbeitsrhythmus

Die Woche wird per Schaltfläche im Dashboard abgeschlossen — die Kachel „Nicht abgeschlossene Wochen” zeigt die älteste offene Woche und die Schaltfläche „2026-W29 abschließen”. Kein Server-Login nötig.

Sichtbar für Konten mit der Rolle F&E-Leitung (Recht core.add_weekclose) und für Superuser. Forschende erfassen Einträge, schließen aber keine Wochen ab — der Abschluss sperrt die Arbeit aller Autoren.

Drei Sperren, die die Schaltfläche durchsetzt:

eine laufende Woche lässt sich nicht abschließen — die restliche Arbeit entsteht erst noch,
Wochen werden der Reihe nach abgeschlossen, älteste zuerst: W30 bei offener W29 hinterließe eine Lücke in der Siegelkette,
der Abschluss ist unumkehrbar — deshalb fragt die Schaltfläche nach einer Bestätigung.

Dieselbe Operation auf der Konsole, falls nötig (z. B. in einem Migrationsskript):

docker compose exec web python manage.py close_week 2026-W29

Der Abschluss: baut die kanonische Fassung aller Wocheneinträge → berechnet SHA-256 → stempelt über BeatTime (Ed25519-Signatur) und OpenTimestamps (Bitcoin-Verankerung) → sperrt die Einträge (🔒). Die Nachweise stehen unter Wochenabschlüsse. Der OTS-Stempel reift nach der Bitcoin-Bestätigung — upgrade_ots aktualisiert die Nachweise.

Nach dem Abschluss nachgetragene Einträge. Der Abschluss sperrt die Bearbeitung der enthaltenen Einträge — er verhindert aber nicht das Nachtragen eines neuen Eintrags mit einem Arbeitsdatum in dieser Woche (Regime „Rekonstruktion”). Ein solcher Eintrag fällt nicht unter das Siegel: Er fehlt in der kanonischen Fassung und im Zeitstempel und gelangt auch nicht mehr dorthin. Der Bericht weist das ausdrücklich aus — Spalte „Vom Siegel erfasst” in der CSV sowie die Kennzeichnung „nicht vom Wochensiegel erfasst” und der Hinweis über der Tabelle in HTML/PDF.

Grundsatz: Schließen Sie eine Woche ab, wenn sie vollständig dokumentiert ist — nicht früher, aber auch nicht endlos später. Eine offene Woche sind Einträge ohne Stempel; eine zu früh geschlossene Woche sind Einträge außerhalb des Siegels. Wer Einträge mit einigen Wochen Verzug schreibt, schließt einfach mit demselben Verzug ab.

Wenn kein Stempel zustande kommt (kein Netz, Dienst vorübergehend nicht erreichbar): Die Woche wird abgeschlossen, gehasht und gesperrt, erhält aber den Status „abgeschlossen” und nicht „gestempelt” — der Prüfbericht zeigt genau diesen Stand, denn der Status ergibt sich aus den tatsächlichen Nachweisen, nicht aus dem bloßen Versuch. Es ist nichts zu tun: Der Autopilot wiederholt den Stempel beim nächsten Durchlauf, bis er gelingt. BeatTime und OpenTimestamps sind unabhängige Zeitanker — ein erfolgreicher genügt.

Autopilot — was von selbst läuft

Im Container läuft eine Schleife (standardmäßig alle 15 Minuten), die alles Ausstehende erledigt. Kein Cron auf dem Server, keine Konfiguration — sie kommt mit dem Image.

Was	Wann
Commits von GitHub holen	jeder Durchlauf
fehlende Stempel abgeschlossener Wochen	jeder Durchlauf, mind. 1 h Abstand zwischen Versuchen
Nachweise reifen lassen: OTS → Bitcoin-Bestätigung, BeatTime-Wochensignatur	jeder Durchlauf
Übersetzungen (`TRANSLATE_AUTO_LANGS`)	jeder Durchlauf, in Blöcken zu 50 Einträgen

Was der Autopilot nicht tut: Wochen abschließen. Der Abschluss sperrt Einträge unumkehrbar, und in eine gerade beendete Woche trägt vielleicht noch jemand Nacharbeit ein — deshalb entscheidet das ein Mensch per Schaltfläche.

Ausstehendes anzeigen, ohne etwas auszuführen:

docker compose exec web python manage.py autopilot --dry-run

Bericht für den Antrag beim Finanzamt

Der Reiter Antrag beim Finanzamt (/reports/fa/) stellt die Stunden für den Antrag auf Forschungszulage zusammen, der nach Ablauf des Wirtschaftsjahres in ELSTER gestellt wird — einer je Wirtschaftsjahr, für alle Vorhaben mit BSFZ-Bescheinigung. Der Bericht ändert nichts an der Aufzeichnung.

Was vor der Antragstellung im Adminbereich zu setzen ist:

Wo	Was
Vorhaben → BSFZ-Status	„Bescheinigt” für Vorhaben mit Bescheinigung — nur sie gehen in die Aufstellung ein
Vorhaben → Aktenzeichen der Bescheinigung / Entscheidung	Aktenzeichen aus der BSFZ-Bescheinigung; der Bericht nennt es bei jedem Vorhaben
Vorhaben → Beginn des Vorhabens (laut Antrag)	im BSFZ-Antrag angegebener Beginn; davon hängt die Gemeinkostenpauschale von 20 % ab
Benutzer → Konto → Abrechnungsparameter → Eigenleistung	für Einzelunternehmer oder Mitunternehmer ankreuzen; bei Arbeitnehmern leer lassen

Was der Bericht berechnet. Stunden aus der Aufteilung der Einträge auf bescheinigte Vorhaben, mit der persönlichen Wochenobergrenze in zeitlicher Reihenfolge: Stunden über der Obergrenze fallen am Ende der Woche weg, und der Bericht weist sie aus. Einträge „außerhalb FuE” und „FuE über der Obergrenze” sowie Stunden nicht bescheinigter Vorhaben gehen nicht in die Aufstellung ein — der Bericht zeigt sie gesondert zur Information. Für Personen mit Eigenleistung schätzt der Bericht den Betrag nach den gesetzlichen Sätzen: 40 €/Std. bis 27.03.2024, 70 €/Std. ab 28.03.2024, 100 €/Std. ab 2026; dazu die Gemeinkostenpauschale von 20 % (§ 3 Abs. 3b FZulG) für Vorhaben mit Beginn nach dem 31.12.2025; Fördersatz 25 %, für KMU ab 28.03.2024 um 10 Prozentpunkte höher (Umschalter in den Filtern). Für Arbeitnehmer weist der Bericht nur Stunden aus — Grundlage ist ihr Arbeitslohn aus der Lohnbuchhaltung. Über den Betrag entscheidet der Bescheid des Finanzamts.

Prüfungen vor der Antragstellung stehen oben im Bericht: offene Wochen (vor der Antragstellung abschließen — das Siegel belegt, dass die Aufzeichnung nicht verändert wurde), durch die Obergrenze gekürzte Stunden, Einträge ohne Aufteilung auf Vorhaben (gehen nicht ein — Aufteilung im Eintrag ergänzen), Tage über 20 Std., Vorhaben ohne Beginndatum oder Aktenzeichen. Ist alles in Ordnung, zeigt der Bericht „Alle Prüfungen ohne Beanstandung”.

Export: Filter nach Wirtschaftsjahr oder Von/Bis, PDF und CSV (Trennzeichen ;, Dezimalkomma), Fassungen PL/DE/EN. Jeder Aufruf wird unter Lesezugriffe (Audit) protokolliert.

Im ELSTER-Antrag geben Sie je Vorhaben das Aktenzeichen der Bescheinigung und die Stunden aus der Tabelle an. Der erhöhte KMU-Fördersatz setzt einen Antrag mit Erklärung zum KMU-Status nach EU-Definition (einschließlich verbundener Unternehmen) voraus; der Antrag enthält außerdem Angaben zu anderen Förderungen derselben Aufwendungen. Bericht, Prüferbericht und Beweisanker der Einträge (Commits, Dateien) als Nachweise aufbewahren — das Finanzamt kann sie anfordern.

Backups

Admin-Startseite → Datenbank-Backups: Backup erstellen (ohne Systemstopp), Liste mit Daten, Herunterladen (Kopie außerhalb des Servers ablegen!), Wiederherstellen (sichert den vorherigen Stand automatisch als pre-restore-…) und Löschen. Das Backup umfasst die Datenbank; Beweisdateien in media/ benötigen eine separate Verzeichniskopie. Alle Operationen landen im Audit-Journal.

Lesezugriffs-Audit

Lesezugriffe (Audit) — append-only Register: wer wann Berichte öffnete, Beweisdateien herunterlud, Backups erstellte und wiederherstellte. Einträge sind weder änderbar noch löschbar.

Lizenz

Die Datei license.json liegt im Installationsverzeichnis. Den Status zeigt das Dashboard (Kunde, Paket, Kontenlimit, Gültigkeit). Nach Ablauf wechselt die Instanz in den Nur-Lese-Betrieb mit vollem Export — Daten werden nie eingeschlossen. Verlängerung: Datei gegen die neue austauschen (ohne Neustart).

Updates

cd laborbuch && docker compose pull && docker compose up -d

Datenbankmigrationen laufen beim Start automatisch. Die Images sind signiert (cosign). Vor größeren Updates ein Backup erstellen.