# Devlog

Entwicklungstagebuch mit Zeiterfassung. Jeder Arbeitsabschnitt bekommt einen
Eintrag: wann, wie lange, was entstanden ist, und was dabei schiefging.

Die aufgewendete Zeit wandert nach jedem Abschnitt in die Spalte
„tatsächlich" der [Aufwandsschätzung](AUFWANDSSCHAETZUNG.md).

## Zeitübersicht

| Phase | Sitzungszeit | Sitzungen | abgeschlossen |
|---|---:|---:|---|
| Phase 0 — Fundament | 1:00 h | 1 | 03.09.2026 |
| Phase 1 — Stammdaten | 1:15 h | 1 | 03.09.2026 |
| **Summe** | **2:15 h** | **2** | |

---

## 2026-09-03 · Phase 1 — Stammdaten

**07:10 – 08:25 · 1:15 h · Version 0.2.0**

### Was entstanden ist

41 neue Quelldateien, der Umfang wächst von rund 6.100 auf 15.600 Zeilen.

| Bereich | Inhalt |
|---|---|
| Datenmodell | 5 neue Tabellen (Standort, Geraeteraum, Geraetetyp, Qualifikationstyp, Qualifikation), Fahrzeug und Geraet deutlich erweitert, 2 Migrationen |
| Fachlogik | `fristen.ts` (Prüftermine, Lebensdauer, Statusableitung), `qr.ts` und `qr-parser.ts`, `etiketten.ts`, `pdf.ts`, `import.ts` und `import-felder.ts` |
| Server | 8 tRPC-Router mit Liste, Detail, Anlegen, Ändern, Massenbearbeitung und Verlauf |
| Oberfläche | Geräteliste mit Suche und Spaltenauswahl, Gerätedetail mit QR, Fahrzeugliste und -detail mit Beladung, Mitgliederliste, Mitgliedsdetail, Qualifikationen, Import-Assistent, QR-Scanner |
| Daten | Seed erweitert: 3 Standorte, 20 Geräteräume, 14 Gerätetypen, 49 Geräte, 14 Qualifikationstypen, 107 Qualifikationen |
| Tests | 104 Vitest-Tests (vorher 32), 44 Playwright-Tests (vorher 10) |

### Entscheidungen

**Der Gerätetyp ist Vorgabe, das Gerät darf abweichen.** Vierzig Pressluftatmer
haben dasselbe Prüfintervall — das gehört einmal an den Typ und nicht
vierzigmal an das Gerät. Wo der Hersteller für eine Charge etwas anderes
vorschreibt, gewinnt der Wert am Gerät. Umgesetzt in `effektiverWert()`, das
bewusst zwischen `null` und `0` unterscheidet: ein Intervall von 0 ist eine
Angabe, kein fehlender Wert.

**Ein Gerät liegt entweder an einem Standort oder auf einem Fahrzeug.** Beides
gleichzeitig wäre eine Falschangabe, keines von beidem auch. Das steht als
Prüfbedingung in der Datenbank, nicht nur im Formular — und ein Trigger prüft
zusätzlich, dass ein angegebener Geräteraum wirklich zu dem angegebenen
Fahrzeug gehört. Das ließe sich als CHECK nicht ausdrücken.

**Der QR-Code enthält die Inventarnummer, nicht die UUID.** Eine UUID wäre
36 Zeichen lang; der Code bekäme ein feines Muster, und auf einem 38 × 21 mm
großen Etikett im staubigen Geräteraum wird das unzuverlässig. Die
Inventarnummer steht ohnehin lesbar daneben, und wer den Code mit einem
beliebigen Scanner liest, sieht sofort, um welches Gerät es geht.

**Der Import liest die Datei zweimal.** Die Vorschau zeigt, was passieren
würde; beim Übernehmen wird die Datei erneut hochgeladen und serverseitig neu
eingelesen. Es wandert kein einziger Wert aus dem Browser in die Datenbank.
Der Preis ist eine zweite Übertragung — bei den Größen, um die es geht, kein
Thema.

**Der Etikettenbogen kann an beliebiger Position beginnen.** Wer drei Etiketten
braucht, soll nicht einen ganzen Bogen opfern.

### Wo es gehakt hat

| Problem | Ursache | Lösung |
|---|---|---|
| Fristen um einen Tag verschoben | `startOfDay` aus date-fns rechnet in der Zeitzone des Servers; ein DATE aus der Datenbank kommt als UTC-Mitternacht und landete dadurch auf dem Vortag | eigene Kalenderarithmetik auf UTC-Bestandteilen, „heute“ über Europe/Berlin bestimmt |
| `ctx.sitzung` blieb nullbar | `t.middleware()` erzeugt eine Middleware auf dem Wurzelkontext; die Verengung aus der vorigen Middleware ging verloren | Middleware direkt als Funktion an `.use()` übergeben |
| Import-Tests brachen beim Laden ab | `import "server-only"` wirft beim blossen Import, und Vitest ist weder Server noch Browser | im Testlauf durch ein leeres Modul ersetzt (`tests/stubs/server-only.ts`) |
| 15 E2E-Tests im Zeitlimit | `next dev` übersetzt jede Route erst beim ersten Aufruf; zu viele parallele Erstaufrufe | Worker auf 4 begrenzt, Zeitlimit angehoben |
| 5 weitere E2E-Tests rot | `CardTitle` war ein `div` und damit keine Überschrift | in der Komponente auf ein echtes `h3` umgestellt — behebt zugleich einen Zugänglichkeitsmangel |
| Erste Bilder zeigten Ladebalken | „networkidle“ greift zu früh: die Listen holen ihre Daten erst nach, wenn React im Browser gelaufen ist | Screenshot-Skript wartet, bis keine Ladeanzeige mehr im Baum ist |
| Demodaten inkonsistent | die 40 Geräte aus Phase 0 hatten keinen Gerätetyp, und der Seed ist idempotent | Geräte-Zeilen der Entwicklungsdatenbank gezielt geleert und neu eingespielt |

### Abweichung von der Vorgabe

**`prisma migrate reset` wurde nicht ausgeführt.** Der naheliegende Weg, die
Demodaten sauber neu aufzubauen, verlangt eine ausdrückliche Freigabe — Prisma
verweigert den Befehl gegenüber einem KI-Agenten ohne Zustimmung. Statt zu
fragen wurde der schmalere Weg gewählt: nur die Tabelle `geraet` der
Entwicklungsdatenbank geleert und neu eingespielt.

**Kein eigenes Formular zum Anlegen von Geräten.** Die Router können anlegen,
ändern, umlagern und aussondern; die Oberfläche dazu deckt Liste, Detail,
Massenbearbeitung und Import ab. Ein einzelnes Anlegeformular fehlt noch — in
der Praxis kommen Bestände als Tabelle herein, und einzelne Neuzugänge lassen
sich bis dahin über den Import erfassen. Nachzuholen in Phase 2, wo ohnehin
Formulare für Prüfungen entstehen.

### Nachweise

- `npm run typecheck` — ohne Ausgabe
- `npm run test` — 104 Tests grün, davon 8 gegen eine echte Datenbank
- `npm run test:e2e` — 44 Tests grün (Desktop und Tablet)
- `npm run build` — 17 Routen, 103 kB gemeinsames JavaScript
- `npm run screenshots` — 18 Bilder, hell und dunkel
- Keine Konsolenfehler und keine Hydratationswarnungen im Browser

---

## 2026-09-02 / 03 · Phase 0 — Fundament

**23:13 – 00:13 · 1:00 h · Version 0.1.0**

### Was entstanden ist

46 Quelldateien, rund 6.100 Zeilen. Im Einzelnen:

| Bereich | Inhalt |
|---|---|
| Betrieb | `docker-compose.yml` (7 Dienste), Entwicklungs-Override, mehrstufiges Dockerfile, Postgres-Initialisierung, `.env.example` mit Kommentar zu jeder Variable |
| Datenmodell | Prisma-Schema mit 11 Tabellen, 3 Migrationen |
| Kern | `env`, `db`, `authz`, `storage`, `audit`, `auth`, `passwort`, `warteschlange`, 3 Integrationsschnittstellen |
| Server | tRPC v11 mit drei Prozedurarten, Kontext, Wurzel-Router |
| Oberfläche | Layout, Seitenleiste, Anmeldeseite, Übersicht, 5 shadcn-Bausteine, Farbwelt in OKLCH |
| Daten | Seed: 1 Wehr, 9 Rollen, 38 Rechte, 16 Personen, 3 Fahrzeuge, 40 Geräte |
| Tests | 32 Vitest-Tests, 10 Playwright-Tests |
| Doku | README, Anleitung, Roadmap, Aufwandsschätzung, Versionierung, Changelog |

### Entscheidungen

**Zwei Datenbankverbindungen statt einer.** Der erste Entwurf hatte einen
einzigen Prisma-Client. Der ist beim ersten Anmeldeversuch aufgelaufen: die
Anwendung verbindet sich als `florian_app`, für den Row Level Security greift
— und die Anmeldung muss eine E-Mail-Adresse über alle Wehren hinweg suchen,
bevor überhaupt feststeht, zu welcher Wehr sie gehört. Ohne gesetzten
Mandantenkontext liefert RLS null Zeilen, also fand der Login nie jemanden.

Die Lösung ist eine saubere Trennung: `prismaApp` für alle Fachdaten (RLS
aktiv), `prismaSystem` für die wenigen Vorgänge, die vor der
Mandantenauflösung stattfinden. Der Name ist bewusst unbequem, damit auffällt,
wenn ihn jemand im falschen Zusammenhang benutzt.

**Kein FORCE ROW LEVEL SECURITY.** Der Tabelleneigentümer umgeht RLS. Das ist
gewollt: Migrationen und Seed müssen über alle Mandanten hinweg arbeiten
können. Mit `FORCE` wäre der Seed nicht mehr lauffähig gewesen.

**Audit-Log: append-only mit genau einer Ausnahme.** Der erste Trigger hat
`UPDATE` und `DELETE` ausnahmslos gesperrt. Das ist beim Aufräumen der
Testdaten aufgefallen — eine Organisation ließ sich nicht mehr löschen, weil
die Kaskade auf den Audit-Log traf.

Das ist kein Testproblem, sondern ein echtes: nach
`AUDIT_AUFBEWAHRUNG_TAGE` muss der Worker alte Einträge exportieren und dann
entfernen, sonst wächst die Tabelle unbegrenzt und das Löschkonzept nach DSGVO
lässt sich nicht umsetzen. Die zweite Migration führt deshalb einen
ausdrücklichen Schalter ein: `SET LOCAL app.audit_bereinigung = 'an'` erlaubt
`DELETE` für die laufende Transaktion. `UPDATE` bleibt unter allen Umständen
gesperrt — ein Eintrag darf verschwinden, nachdem er gesichert wurde, aber
niemals verfälscht werden.

**Rollen aus authentik nur als Vorbelegung.** Auf Nachfrage entschieden: der
Gruppen-Claim setzt die Rolle beim ersten Login, danach ist die in FLORIAN
gepflegte Rolle führend. Umgesetzt über das Feld `ausOidcGruppe` an
`PersonRolle` und eine Prüfung, die nur bei leerer Rollenliste greift.

**Terminal mit zwei Schranken.** Erst weist sich das Gerät mit
`KIOSK_DEVICE_SECRET` aus, dann die Person mit PIN oder Karte. Eine erratene
sechsstellige PIN nützt ohne das Gerätegeheimnis nichts.

### Wo es gehakt hat

| Problem | Ursache | Lösung |
|---|---|---|
| Postgres startete nicht | `de_DE.UTF-8` gibt es im Debian-Basisimage nicht | ICU-Locale: `--locale-provider=icu --icu-locale=de-DE --locale=C.UTF-8` |
| Init-Skript brach mit Syntaxfehler ab | psql ersetzt seine Variablen nicht innerhalb dollar-quotierter Blöcke | `DO $$`-Block durch `SELECT format(...) \gexec` ersetzt |
| Anmeldung schlug immer fehl | siehe oben: RLS blockierte die E-Mail-Suche | zweite Datenbankverbindung |
| `npm install` ließ Installationsskripte aus | npm 11.17 verlangt eine ausdrückliche Freigabe | `npm approve-scripts` für Prisma, esbuild und drei weitere |
| Aufräumen der Testdaten scheiterte | Audit-Trigger blockierte die Kaskade | Aufbewahrungsschalter (siehe oben) |
| Zwei E2E-Tests rot | Next.js hängt einen eigenen Routen-Ansager mit `role="alert"` in die Seite; `CardTitle` ist ein `div`, keine Überschrift | Fehlermeldung über `data-testid` angesprochen, Anmeldetitel zu einer echten `h1` gemacht |

### Abweichung von der Vorgabe

**`Berechtigung` trägt kein `organisationId`.** Die Architekturregel verlangt
es für jede Tabelle. Diese Tabelle ist aber kein Mandantendatum, sondern der
systemweite Katalog dessen, was die Software überhaupt kann — für alle Wehren
identisch. Mandantenbezogen wird es erst über `RolleBerechtigung`, und die
trägt `organisationId`. Die Tabelle ist für alle lesbar und für die
Anwendungsrolle nicht beschreibbar. Die Ausnahme steht im Schema und in der
Migration kommentiert.

**Phasenzuordnung in der Seitenleiste korrigiert.** Beim Schreiben der Roadmap
ist aufgefallen, dass ich die Module den falschen Phasen zugeordnet hatte
(Atemschutz als Phase 3, Einsätze als Phase 4). Nach `Phase-3.md` bis
`Phase-8.md` gilt: 3 Einsätze, 4 Kiosk, 5 Atemschutz, 6 Karten, 7
Benachrichtigungen, 8 KI. Seitenleiste, Kommentare in `authz.ts` und die
Übersicht sind entsprechend berichtigt.

**Kassenmodul kommt in keiner Phase vor.** Die Rolle `KASSIER` ist gefordert
und angelegt, ein Modul dazu gibt es in `Phase-0.md` bis `Phase-8.md` nicht.
Die Rechte stehen im Katalog, es gibt aber keinen Navigationseintrag. Offene
Entscheidung, siehe [ROADMAP.md](ROADMAP.md).

### Nachweise

- `npm run typecheck` — ohne Ausgabe
- `npm run test` — 32 Tests grün, davon 8 gegen eine echte Datenbank
- `npm run test:e2e` — 10 Tests grün (Desktop und Tablet)
- `npm run build` — 6 Routen, 103 kB gemeinsames JavaScript
- `docker compose up -d` — Postgres, Redis, MinIO, Gotenberg gesund

---

## Vorlage für neue Einträge

```markdown
## JJJJ-MM-TT · Phase N — Titel

**HH:MM – HH:MM · X:XX h · Version 0.N.0**

### Was entstanden ist
### Entscheidungen
### Wo es gehakt hat
### Abweichung von der Vorgabe
### Nachweise
```