Laufzettel/docs/devlog.md

# DEVLOG – Laufzettel

Entwicklungstagebuch mit Zeiterfassung. Eine Sitzung ist ein Abschnitt; Sub-Agenten-Läufe stehen
als Unterpunkte mit Aufgabe und Dauer.

## Zeitübersicht

| Issue | Titel | Tatsächlich |
|---|---|---|
| #005 | M0 – Gerüst, Prozess, Design-Token | 1 h 25 min |
| #006 | M1 – Datenmodell | 1 h 10 min |
| #007 | M2 – Auth, Rollen, Benutzer | 1 h 35 min |
| #008 | M3 – Betriebsmodus und Kunden | 1 h 20 min |
| | **Summe** | **5 h 30 min** |

| Meilenstein | Tatsächlich | Status |
|---|---|---|
| v0.1.0 | 5 h 30 min | in Arbeit |

---

## 2026-09-24 · Sitzung 1 · 22:05–23:30

**Issue:** #005 (M0)
**Version:** 0.1.0

### Erledigt

- Umgebung geprüft: Node v24.21.0 nur über nvm (nicht im `PATH` nicht-interaktiver Shells),
  Docker 29.1.3, Chromium-Systembibliotheken vorhanden, kein `pandoc`
- Gitea aufgesetzt: 11 Labels, 5 Meilensteine (`v0.1.0`–`v0.5.0`), 19 Issues (#1–#19), Nummern
  passen zu den Dateinamen unter `docs/issues/`
- Projektgerüst angelegt und alle vier Schranken grün: `lint`, `typecheck`, `test`, `build`
- Betriebsstand gehärtet und der Nachweis in `tests/betriebsstand.test.ts` festgeschrieben
- Abnahme von #005 wirklich gefahren, nicht behauptet: `docker compose up -d --build` startet den
  Stack, `migrate` läuft und beendet sich, `web` wartet korrekt darauf, `/api/gesundheit` meldet
  `ok` — und `5432` ist vom Host nicht erreichbar, aus `web` schon
- `scripts/pruefe-doku.mjs` gegen vier eingebaute Fehler geprüft: es findet abweichende Zeiten,
  fehlende Einträge, Verweise auf fehlende Dateien und fehlende Bilder

### Entscheidungen

- **Deutsch im Code, auch für Bezeichner.** Der Auftragstext verlangte Englisch; Florian hat sich
  für Einheitlichkeit mit ProxLedger entschieden. Verbindliche Namensabbildung in `CLAUDE.md`.
- **Kein Auth.js.** v5 steht seit Jahren auf Beta (`5.0.0-beta.32`), authjs.dev führt das Projekt
  im Wartungsmodus („now part of Better Auth"), die Maintainer nennen „no immediate plans for v5",
  und `@auth/prisma-adapter` deklariert Prisma nur bis 6 — wir fahren Prisma 7. Stattdessen
  `openid-client` + `jose` wie in ProxLedger. Dieselbe Überlegung wie dort, nur ein Jahr später
  noch deutlicher.
- **`prisma` exakt auf 7.10.0 gepinnt.** Der `latest`-Tag von `prisma` zeigt auf `8.0.0-rc.17`,
  der von `@prisma/client` auf `7.10.0`. Ein unbedachtes `pnpm add prisma` hätte einen
  Versions-Konflikt erzeugt.
- **`eslint` bleibt auf 9.x.** Mit eslint 10 bricht das Regelwerk beim Laden ab:
  `eslint-config-next` bringt `eslint-plugin-react@7.37.5` mit, das `eslint` nur bis `^9.7`
  unterstützt, und eine neuere Fassung des Plugins gibt es nicht (letzte Veröffentlichung
  April 2025). Empirisch festgestellt, nicht geraten.
- **`typescript` bleibt auf `~6.0.3`.** `typescript-eslint@8.70.1` erlaubt nur
  `>=4.8.4 <6.1.0`; TypeScript 7.0.2 ist zwar `latest`, aber noch nicht unterstützt.
- **`@node-rs/argon2` statt `argon2`.** Liefert vorgebaute musl- und gnu-Binaries, braucht auf
  `node:24-alpine` also keine C++-Toolchain in der Bau-Stufe.
- **`barcode-detector` statt `jsQR`.** `jsqr` ist seit April 2021 unveröffentlicht. Der Polyfill
  bietet dieselbe API wie das native `BarcodeDetector`, also ein Codepfad statt zwei.
- **Seed läuft nicht automatisch.** Die Migrationen schon, der Seed bleibt ein dokumentierter
  Handgriff — so steht es in den Abnahmekriterien.
- **shadcn/ui eingerichtet, aber der Button folgt der Vorgabe, nicht dem Preset.** Der Vertrag
  von shadcn (`--background`, `--primary`, `--border`, …) wird in `globals.css` aus den
  Laufzettel-Token gespeist; jedes später kopierte Bauteil sieht damit sofort richtig aus und
  folgt auch dem hellen Modus. Der Scannen-Knopf nutzt den shadcn-Button, überschreibt aber Form
  und Höhe (Pille, 44 px am Handy statt 32 px).
- **PDF der Anleitung über Playwright.** `pandoc` und `wkhtmltopdf` fehlen und sind ohne root
  nicht installierbar; Chromium ist für die E2E-Tests ohnehin da.

### Probleme

- **Projektverzeichnis gehörte `root`.** `~/Projekte/Laufzettel` war root-eigen, die Sitzung läuft
  als `florianwilde`, und `sudo` verlangt hier ein Passwort. Bis Florian den `chown` gemacht hat,
  wurde das Gerüst im Scratchpad vorgebaut und danach hineinverschoben — die Gitea-Arbeit brauchte
  das Verzeichnis nicht und lief parallel.
- **pnpm 12 hat die Einstellung für Build-Skripte umbenannt.** `onlyBuiltDependencies` wird noch
  von `pnpm config list` angezeigt, aber nicht mehr angewandt; wirksam ist `allowBuilds` als
  Zuordnung in `pnpm-workspace.yaml`. Das `pnpm`-Feld in `package.json` liest pnpm 12 gar nicht
  mehr. Gefunden über `pnpm approve-builds --all`, das die richtige Form selbst schreibt.
- **Context7-MCP ist nicht autorisiert**, der OAuth-Ablauf geht in dieser Sitzung nicht. Alle
  Versionen wurden stattdessen direkt gegen das npm-Registry und die offiziellen Docs geprüft.
- **pnpm 12 prüft die Lieferkette und lehnt taufrische Pakete ab.** `vite@8.3.1` (8,7 h alt) und
  `lucide-react@1.48.0` (15,3 h alt) fielen durch. Beide auf die Vorgängerfassung gesetzt, die
  Richtlinie bleibt an. Bei der Gelegenheit alle direkten Abhängigkeiten auf ihr Alter geprüft.
- **`shadcn init` lässt sich nicht skripten.** Es fragt auch mit `--yes` nach einem Preset und
  bleibt hinter einer Pipe stumm hängen. `shadcn add <bauteil> --yes --overwrite < /dev/null`
  geht dagegen. Zusätzlich nötig: Pfad `"cn": ["./src/lib/utils"]` in `tsconfig.json` und das
  Paket `radix-ui`, beides schreibt `init` nicht.
- **Port 3000 ist von ProxLedger belegt.** Die Abnahme lief auf 3100 und 3200.
- **Kein Gitea-Actions-Runner registriert** (0 Runner). `.gitea/workflows/ci.yml` wird trotzdem
  angelegt und ist nutzbar, sobald ein Runner da ist; verbindlich sind bis dahin der
  Pre-Commit-Hook und die Durchläufe vor jedem Commit.

### Offen

- Der `pct create`-Teil des Proxmox-Skripts (#019) lässt sich hier nicht ausführen, weil kein
  PVE-Host erreichbar ist. Geplant: `shellcheck` plus `--dry-run`, und `deploy/install.sh`
  vollständig in einem `debian:13`-Container geprüft. Der Lauf auf echtem Proxmox braucht eine
  Gegenprüfung durch Florian, dafür kommt eine Prüfliste.
- Der OpenLDAP-Testcontainer wandert von #005 nach #016, wo er tatsächlich benutzt wird — ein
  Dienst, den noch kein Test anfasst, wäre eine Attrappe.

### Nächster Schritt

- #006 Datenmodell: das vollständige Schema in deutscher Benennung, `tagCode`-Generator,
  Krypto-Helfer, erste Migration, idempotenter Seed-Rumpf.

---

## 2026-09-25 · Sitzung 2 · 00:05–01:15

**Issue:** #006 (M1)
**Version:** 0.1.0

### Erledigt

- Vollständiges Schema in deutscher Benennung: 20 Tabellen, 9 Aufzählungen, eine Migration
- `src/lib/tagcode.ts` und `src/lib/geheimnisse.ts` samt Tests, parallel von einem Sub-Agenten
  gebaut, während ich das Schema schrieb (Dauer dort: rund 10 min)
- Idempotenter Seed für Betriebsmodus, eigene Organisation und Administrator — zweimal
  hintereinander gefahren, keine Zeile geändert
- Unabhängiger Review-Agent gegen die Akzeptanzkriterien; alle Blocker und alle neun „sollte
  behoben werden"-Punkte abgearbeitet
- **106 Tests** grün (vorher 11), davon 42 gegen die echten Datenbankregeln

### Entscheidungen

- **Regeln gehören zusätzlich in die Datenbank.** Zwölf CHECK-Bedingungen, zwei partielle
  Eindeutigkeitsindizes und vier zusammengesetzte Fremdschlüssel. Begründung: die Service-Schicht
  ist nicht der einzige Weg, auf dem Daten entstehen — Migrationen, `psql`, Skripte und ab
  Phase 4 die Connectoren schreiben an ihr vorbei.
- **Die Mandantengrenze wird strukturell erzwungen.** `Lauf` verweist mit
  `("geraetId", "kundeId")` auf `Geraet("id", "kundeId")`, analog für Person und Abteilung.
  `docs/architektur.md` nennt die Grenze eine Sicherheitsgrenze — dann soll sie nicht allein an
  `kundeErmitteln()` hängen. `MATCH SIMPLE` lässt einen Lauf ohne Gerät weiter zu.
- **Kein Cascade dort, wo das Archiv hängt.** Ein `DELETE` auf einen Lauf hätte Schrittergebnisse
  und Kommentare stillschweigend mitgenommen, ein Protokolleintrag hätte seinen Urheber verlieren
  können. Beides jetzt `Restrict`.
- **`TagCodeVergabe` als Vergabebuch.** Die Eindeutigkeit allein aus `Geraet.tagCode` zu ziehen
  reicht nicht: verschwindet die Zeile, wäre der Code wieder frei und ein alter Aufkleber im
  Regal zeigte auf ein fremdes Objekt.
- **Widerspruch im Auftrag beim tagCode-Alphabet.** Das wörtliche Alphabet enthält ein `L`,
  die Klammer daneben verbietet es. Aufgelöst zugunsten des wörtlichen Alphabets: die Klammer
  benennt Verwechslungsgruppen, keine Ausschlussliste — aus `{1, I, L}` sind `1` und `I` weg,
  dadurch ist `L` eindeutig. Das Akzeptanzkriterium in #006 ist richtiggestellt worden, statt
  einen grünen Test darüber zu setzen.
- **Ein Systemlauf muss darstellbar sein.** `Lauf.erstelltVonId` ist optional, wie schon
  `Schrittergebnis.aktualisiertVonId`. Wiederkehrende Läufe und der Start per Webhook (Phase 4)
  haben keinen Menschen dahinter.

### Probleme

- **`prisma migrate reset --force` zeigte den Bestätigungsdialog trotzdem** und ließ einen
  Schema-Engine-Prozess zurück, der die Advisory-Sperre hielt; der nächste `migrate dev` lief
  daraufhin in einen Timeout. Verlässlicher: `DROP SCHEMA public CASCADE` per psql, dann
  `migrate dev --create-only < /dev/null`.
- **Port 5433 ist von ProxLedger belegt.** Die Entwicklungsdatenbank liegt jetzt auf 5434,
  umstellbar über `DEV_DB_PORT`.
- **Eine Regex-Ersetzung hat `quelle.length` auch aus der Längenprüfung gerissen** und den
  Krypto-Helfer unübersetzbar gemacht. Die Testsuite hat es sofort gezeigt — ein Argument mehr
  dafür, nach jeder Sammeländerung wirklich alle Schranken laufen zu lassen.

### Nächster Schritt

- #007 Auth, Rollen, Benutzer: `openid-client` mit Discovery, `jose`-Sitzungscookie, lokaler
  Login mit argon2, `RECHTE`-Tabelle, Login-Seite mit Rücksprung auf die ursprüngliche URL.

---

## 2026-09-25 · Sitzung 3 · 01:55–03:35

**Issue:** #007 (M2)
**Version:** 0.1.0

### Erledigt

- OIDC mit `openid-client` 6.8.8: Discovery, PKCE, `state`, `nonce`; API vorher gegen die
  Typdefinitionen im Paket geprüft statt aus dem Gedächtnis geschrieben
- `jose`-Sitzungscookie, lokaler Login mit argon2, Rechtetabelle, JIT-Provisionierung
- Anmeldeseite, geschützter Bereich, Benutzerverwaltung, rollenabhängige Navigation
- Sub-Agent hat `rollen.ts` und `sitzung.ts` samt 85 Tests parallel gebaut (rund 6 min)
- Unabhängiger Review-Agent: ein Blocker, acht weitere Befunde, alle abgearbeitet
- **274 Tests** grün (vorher 106)

### Entscheidungen

- **Rücksprungziel wird aufgelöst, nicht mit Präfixen verglichen.** Die Präfix-Prüfung war eine
  offene Weiterleitung: `/<TAB>/fremd.example` besteht `startsWith("/")`, ist kein `//` und kein
  `/\` — Browser entfernen den Tabulator aber beim Verarbeiten der URL, übrig bleibt
  `//fremd.example`. Das Auflösen gegen eine Wegwerf-Basis macht genau das, was der Browser tut,
  und der Vergleich der Herkunft erschlägt alle Formen auf einmal.
- **Alle Umleitungen über `APP_URL`.** `nextUrl.origin` lieferte im Test `localhost` statt
  `127.0.0.1`; hinter einem Reverse Proxy wäre es der interne Host. Neues Modul
  `src/lib/adressen.ts`, die Herkunft der Anfrage ist nur noch Notnagel.
- **Ohne `OIDC_GROUP_*` bleibt die Rolle, wie sie ist.** Sonst wäre jede OIDC-Anmeldung eine
  stille Herabstufung auf `LESER` — bei einem einzigen Administrator ohne Rückweg.
- **Verknüpfung über die Adresse nur bei `email_verified`.** Sonst wäre ein Anbieter mit frei
  wählbaren Adressen der Weg, den lokalen Notfall-Administrator zu übernehmen.
- **Der letzte aktive Administrator ist geschützt**, gegen Herabstufung wie gegen Abschalten.
- **Kein `overflow-x: hidden` auf `body`.** Es sieht aus wie eine Lösung, verdeckt aber nur: zu
  breiter Inhalt wird abgeschnitten statt erreichbar, und die Prüfung im Screenshot-Skript kann
  ihn nicht mehr finden. Layouts müssen bei 390 px von sich aus passen.
- **`ROLLEN_TEXT` liegt in `src/lib`,** nicht in der Server-Schicht: eine Client-Komponente hätte
  sonst die komplette Rechtetabelle ins Browser-Bündel gezogen.

### Probleme

- **Der Platzhalter-Hash gegen den Zeitkanal war erfunden** und hätte sofort geworfen statt Zeit
  zu kosten. Die Zusage wäre damit schlicht falsch gewesen. Jetzt ein echter, lazy erzeugter
  argon2-Hash; nachgemessen rund 1 ms Unterschied über je 60 Anfragen.
- **Beim Verschieben der Übersicht nach `(app)/` blieb `<Huelle>` in der Seite stehen.** Die Hülle
  wurde doppelt gerendert — zwei Kopfzeilen, das innere Menü ohne Benutzer. Es war im Screenshot
  zu sehen und ist mir trotzdem entgangen; gefunden hat es der Review-Agent. Ein Bild anzusehen
  ersetzt nicht, gezielt nach dem zu suchen, was sich gerade geändert hat.
- **Prisma-Modelltypen kommen aus `@/generated/prisma/client`,** nicht aus `.../models` — dort
  liegen nur die Hilfstypen der Abfragen. Steht jetzt in `CLAUDE.md`.
- **`networkidle` als Wartebedingung in Playwright** läuft bei einer Anwendung mit offenen
  Verbindungen in den Timeout. `load` plus geladene Schriften ist deterministisch.

### Nächster Schritt

- #008 Betriebsmodus und Kunden: `betriebsmodus()`, `kundeErmitteln()`, Moduswechsel in beiden
  Richtungen, Kundenverwaltung, Admin-Einstellungen.

---

## 2026-09-25 · Sitzung 4 · 05:35–07:00

**Issue:** #008 (M3)
**Version:** 0.1.0

### Erledigt

- `src/server/mandant.ts` als die eine Stelle für die Mandantenregel
- Moduswechsel in beiden Richtungen, Kundenverwaltung (Sub-Agent, 25 Tests), Admin-Einstellungen
- Wechsel per Playwright **durch die Oberfläche** gefahren, nicht nur im Service: Navigation
  wechselt sofort, `/kunden` wird erreichbar
- Unabhängiger Review: drei Blocker, sechs weitere Befunde, alle abgearbeitet
- **336 Tests** grün (vorher 274)

### Entscheidungen

- **Die Sichtbarkeit gehört in `kundeErmitteln`,** nicht in eine zweite Funktion daneben. Sonst
  müsste jeder künftige Service daran denken — und #009 ff. übernehmen diese Signatur.
- **Lesemodelle filtern selbst.** Sie verlangen den Benutzer, statt sich auf den Aufrufer zu
  verlassen. `undefined` heißt „keine Einschränkung", `[]` heißt „sieht nichts"; die Umsetzung
  steht an einer Stelle, und beide Fälle haben einen Test.
- **`pg_advisory_xact_lock` statt Serializable.** Der Wechsel ist selten und kurz; ein Schloss auf
  Transaktionsebene ist verständlicher als eine Isolationsstufe, die man beim Lesen übersieht, und
  wird auch bei einem Abbruch freigegeben.
- **Die Prüfung läuft zweimal** — einmal für den Dialog, einmal innerhalb der Transaktion. Beide
  Male derselbe Code, damit es keine nachgebaute zweite Wahrheit gibt.
- **ASCII-Faltung gilt für Bezeichner, nicht für Fließtext.** Steht jetzt ausdrücklich in
  `CLAUDE.md`; Protokoll-Aktionen sind entsprechend nachgezogen.

### Probleme

- **Ich habe in einem Kommentar etwas behauptet, das nicht stimmte** („Alles in einer
  Transaktion"), während der Protokolleintrag dahinter stand. Ein Kommentar, der eine Zusage
  macht, gehört genauso geprüft wie der Code darunter.
- **`sichtbareKundenIds` hatte keinen einzigen Aufrufer.** Eine Funktion zu schreiben, die eine
  Regel durchsetzt, und sie dann nirgends zu rufen, sieht im Review aus wie Absicht und ist es
  nicht. Der Volltextlauf über `src` hätte das in zehn Sekunden gezeigt.
- **Der Wettlauf war reproduzierbar**, nicht theoretisch: zwei gleichzeitige Wechsel liefen beide
  durch.

### Nächster Schritt

- #009 Vorlagen-Versionierung: Veröffentlichen, tiefe Kopie als Entwurf, höchstens ein Entwurf,
  Unveränderlichkeit, JSON-Export und -Import.