feat: Projektgerüst, gehärteten Betriebsstand und Prozess aufsetzen

Legt die Grundlage, auf der alle weiteren Meilensteine nur noch Fachlichkeit ergänzen: Next 16 mit App Router und TypeScript strict, Tailwind 4, Prisma 7, Vitest 5, Playwright, ESLint, Prettier und die Hooks für Lint und Commits. Zwei Dinge sind bewusst so gebaut und durch Tests festgehalten: Die Datenbank ist im Betriebsstand von außen nicht erreichbar. Sie hat kein ports:-Mapping und hängt allein im Netz "intern", das ohne Gateway läuft; nur "web" kommt zusätzlich nach draußen. tests/betriebsstand.test.ts schlägt an, falls ein Port-Mapping zurückkehrt. Geprüft, nicht behauptet: docker compose up startet den Stack, 5432 ist vom Host aus zu, aus "web" offen. pnpm pruefe:doku hält Dokumentation und Code zusammen — Version im Changelog, Issue-Dateien gegen ihre Übersicht, keine Verweise auf fehlende Dateien, keine fehlenden Bilder. Das Skript wurde gegen vier eingebaute Fehler gegengeprüft. Drei Versions-Obergrenzen sind nötig und in CLAUDE.md begründet: eslint bleibt auf 9.x, weil eslint-plugin-react keinen Nachfolger für eslint 10 hat und das Regelwerk sonst beim Laden abbricht; typescript bleibt auf 6.0.x, weil typescript-eslint TypeScript 7 noch nicht unterstützt; prisma ist exakt auf 7.10.0 gepinnt, weil sein latest-Tag auf einen 8.0-RC zeigt, der von @prisma/client aber nicht. Auth.js entfällt entgegen der ursprünglichen Vorgabe: v5 steht dauerhaft auf Beta, das Projekt ist im Wartungsmodus und sein Prisma-Adapter deckt Prisma 7 nicht ab. Stattdessen openid-client und jose, wie in ProxLedger. Dieser erste Commit geht direkt auf main, weil es noch keinen Branch gibt, von dem abzuzweigen wäre. Ab #006 läuft jedes Issue über einen eigenen Branch. Closes #5 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-24 23:33:49 +02:00
commit 49ce06f206
84 changed files with 13511 additions and 0 deletions
@@ -0,0 +1,128 @@
+#!/usr/bin/env tsx
+/**
+ * Spiegelt docs/issues/NNN-*.md in den Gitea-Tracker. Die Dateien sind die Quelle,
+ * der Tracker die Anzeige.
+ *
+ * Das Token kommt aus GITEA_TOKEN oder, falls das fehlt, aus ~/.git-credentials
+ * fuer denselben Host. Es wird nie ausgegeben.
+ *
+ *   pnpm issues:sync            spiegelt
+ *   pnpm issues:sync --pruefen  meldet nur Abweichungen, schreibt nichts
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const VERZEICHNIS = "docs/issues";
+const nurPruefen = process.argv.includes("--pruefen");
+
+function remoteLesen(): { host: string; besitzer: string; repo: string } {
+  const konfiguration = readFileSync(".git/config", "utf8");
+  const treffer = konfiguration.match(
+    /url\s*=\s*https?:\/\/(?<host>[^/]+)\/(?<besitzer>[^/]+)\/(?<repo>[^/\s]+?)(?:\.git)?\s*$/m,
+  );
+  if (!treffer?.groups) throw new Error("Konnte den Remote aus .git/config nicht lesen.");
+  const { host, besitzer, repo } = treffer.groups;
+  return { host: host!, besitzer: besitzer!, repo: repo! };
+}
+
+function tokenLesen(host: string): string {
+  const ausUmgebung = process.env["GITEA_TOKEN"];
+  if (ausUmgebung) return ausUmgebung;
+  try {
+    const zeilen = readFileSync(join(homedir(), ".git-credentials"), "utf8");
+    const treffer = zeilen.match(new RegExp(`https://[^:]+:([^@]+)@${host.replace(".", "\\.")}`));
+    if (treffer?.[1]) return treffer[1];
+  } catch {
+    // Datei fehlt – dann greift die Meldung unten.
+  }
+  throw new Error(
+    `Kein Token. Setze GITEA_TOKEN oder lege einen Zugang fuer ${host} in ~/.git-credentials ab.`,
+  );
+}
+
+const { host, besitzer, repo } = remoteLesen();
+const API = `https://${host}/api/v1/repos/${besitzer}/${repo}`;
+const TOKEN = tokenLesen(host);
+
+async function ruf<T>(methode: string, pfad: string, rumpf?: unknown): Promise<T> {
+  for (let versuch = 1; versuch <= 5; versuch += 1) {
+    try {
+      const antwort = await fetch(API + pfad, {
+        method: methode,
+        headers: { Authorization: `token ${TOKEN}`, "Content-Type": "application/json" },
+        ...(rumpf === undefined ? {} : { body: JSON.stringify(rumpf) }),
+        signal: AbortSignal.timeout(30_000),
+      });
+      if (!antwort.ok) {
+        throw new Error(`HTTP ${antwort.status} bei ${methode} ${pfad}: ${await antwort.text()}`);
+      }
+      return (await antwort.json().catch(() => null)) as T;
+    } catch (fehler) {
+      if (versuch === 5 || String(fehler).includes("HTTP 4")) throw fehler;
+      await new Promise((f) => setTimeout(f, versuch * 1000));
+    }
+  }
+  throw new Error("unerreichbar");
+}
+
+function feld(text: string, name: string): string {
+  return text.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+?)(?=\\s*\\*\\*|$)`, "m"))?.[1]?.trim() ?? "";
+}
+
+type Label = { id: number; name: string };
+type Meilenstein = { id: number; title: string };
+type Issue = { number: number; title: string };
+
+const labels = new Map((await ruf<Label[]>("GET", "/labels?limit=100")).map((l) => [l.name, l.id] as const));
+const meilensteine = new Map(
+  (await ruf<Meilenstein[]>("GET", "/milestones?state=all")).map((m) => [m.title, m.id] as const),
+);
+const vorhanden = new Map(
+  (await ruf<Issue[]>("GET", "/issues?state=all&limit=100")).map((i) => [i.title, i.number] as const),
+);
+
+let geaendert = 0;
+for (const name of readdirSync(VERZEICHNIS)
+  .filter((n) => /^\d{3}-.+\.md$/.test(n))
+  .sort()) {
+  const text = readFileSync(join(VERZEICHNIS, name), "utf8");
+  const kopf = text.match(/^#\s*#(\d+)\s+(.+)$/m);
+  if (!kopf) throw new Error(`${name}: keine Kopfzeile der Form "# #007 Titel".`);
+  const titel = kopf[2]!.trim();
+
+  const labelNamen = feld(text, "Labels")
+    .split(",")
+    .map((n) => n.trim())
+    .filter(Boolean);
+  const unbekannt = labelNamen.filter((n) => !labels.has(n));
+  if (unbekannt.length > 0) {
+    console.warn(`  ${name}: unbekannte Labels: ${unbekannt.join(", ")}`);
+  }
+
+  const nutzlast: Record<string, unknown> = {
+    title: titel,
+    body:
+      `${text.slice(kopf.index! + kopf[0].length).replace(/^\n+/, "")}\n\n---\n\n` +
+      `Quelle: \`${VERZEICHNIS}/${name}\` — dort gepflegt, hierher gespiegelt.`,
+    labels: labelNamen.filter((n) => labels.has(n)).map((n) => labels.get(n)!),
+  };
+  const meilenstein = meilensteine.get(feld(text, "Meilenstein"));
+  if (meilenstein !== undefined) nutzlast["milestone"] = meilenstein;
+
+  const nummer = vorhanden.get(titel);
+  if (nurPruefen) {
+    if (nummer === undefined) console.log(`  fehlt im Tracker: ${titel}`);
+    continue;
+  }
+  if (nummer === undefined) {
+    const neu = await ruf<Issue>("POST", "/issues", nutzlast);
+    const warnung = String(neu.number) === String(Number(name.slice(0, 3))) ? "" : "  ⚠ Nummer weicht ab";
+    console.log(`  angelegt     #${neu.number} ${titel}${warnung}`);
+  } else {
+    await ruf("PATCH", `/issues/${nummer}`, nutzlast);
+    console.log(`  aktualisiert #${nummer} ${titel}`);
+  }
+  geaendert += 1;
+}
+console.log(nurPruefen ? "Prüfung beendet." : `Fertig, ${geaendert} Issues gespiegelt.`);
@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Prueft, dass Dokumentation und Code nicht auseinanderlaufen. Laeuft in CI und
+ * vor jedem Commit. Geprueft wird:
+ *
+ *   1. Die Version aus package.json hat einen Abschnitt im Changelog.
+ *   2. Jede Issue-Datei steht in der Uebersicht – und umgekehrt.
+ *   3. Geschaetzte und tatsaechliche Zeiten stimmen zwischen Datei und Uebersicht.
+ *   4. Alle in der Anleitung verlinkten Bilder sind vorhanden.
+ *   5. Kein Markdown verweist auf eine Datei, die es nicht gibt.
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+
+const wurzel = resolve(import.meta.dirname, "..");
+const befunde = [];
+
+function melde(text) {
+  befunde.push(text);
+}
+
+function lies(pfad) {
+  return readFileSync(join(wurzel, pfad), "utf8");
+}
+
+function feld(text, name) {
+  const treffer = text.match(new RegExp(`\\*\\*${name}:\\*\\*\\s*(.+?)(?=\\s*\\*\\*|$)`, "m"));
+  return treffer?.[1]?.trim() ?? "";
+}
+
+// ---- 1. Version im Changelog ----------------------------------------------
+{
+  const { version } = JSON.parse(lies("package.json"));
+  const changelog = lies("CHANGELOG.md");
+  const veroeffentlicht = changelog.includes(`## [${version}]`);
+  const unveroeffentlicht = /^## \[Unveröffentlicht\]/m.test(changelog);
+  if (!veroeffentlicht && !unveroeffentlicht) {
+    melde(
+      `Version ${version} hat keinen Abschnitt im Changelog und es gibt keinen Abschnitt ` +
+        `[Unveröffentlicht].`,
+    );
+  }
+}
+
+// ---- 2. und 3. Issue-Dateien gegen die Uebersicht --------------------------
+{
+  const verz = "docs/issues";
+  const dateien = readdirSync(join(wurzel, verz))
+    .filter((n) => /^\d{3}-.+\.md$/.test(n))
+    .sort();
+  const uebersicht = lies(join(verz, "README.md"));
+
+  for (const name of dateien) {
+    if (!uebersicht.includes(`(${name})`)) {
+      melde(`${verz}/${name} fehlt in ${verz}/README.md.`);
+      continue;
+    }
+    const text = lies(join(verz, name));
+    const kopf = text.match(/^#\s*#(\d+)\s+(.+)$/m);
+    if (!kopf) {
+      melde(`${verz}/${name} hat keine Kopfzeile der Form "# #007 Titel".`);
+      continue;
+    }
+    const [, nummer, titel] = kopf;
+    if (Number(nummer) !== Number(name.slice(0, 3))) {
+      melde(`${verz}/${name} nennt #${nummer}, der Dateiname sagt ${name.slice(0, 3)}.`);
+    }
+    const zeile = uebersicht.split("\n").find((z) => z.includes(`(${name})`));
+    for (const [beschriftung, wert] of [
+      ["Status", feld(text, "Status")],
+      ["Geschätzt", feld(text, "Geschätzt")],
+      ["Tatsächlich", feld(text, "Tatsächlich")],
+    ]) {
+      if (wert && !zeile.includes(`| ${wert} |`)) {
+        melde(`${verz}/${name}: "${beschriftung}: ${wert}" weicht von der Übersicht ab.`);
+      }
+    }
+    if (!zeile.includes(titel)) {
+      melde(`${verz}/${name}: Titel "${titel}" weicht von der Übersicht ab.`);
+    }
+  }
+
+  for (const treffer of uebersicht.matchAll(/\((\d{3}-[^)]+\.md)\)/g)) {
+    if (!dateien.includes(treffer[1])) {
+      melde(`${verz}/README.md verweist auf ${treffer[1]}, die Datei fehlt.`);
+    }
+  }
+}
+
+// ---- 4. Verlinkte Bilder in der Anleitung ----------------------------------
+{
+  const verz = join(wurzel, "docs/anleitung");
+  if (existsSync(verz)) {
+    const sammeln = (ordner) =>
+      readdirSync(ordner, { withFileTypes: true }).flatMap((eintrag) => {
+        const pfad = join(ordner, eintrag.name);
+        if (eintrag.isDirectory()) return sammeln(pfad);
+        return eintrag.name.endsWith(".md") ? [pfad] : [];
+      });
+    for (const datei of sammeln(verz)) {
+      const text = readFileSync(datei, "utf8");
+      for (const treffer of text.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
+        const ziel = treffer[1];
+        if (/^https?:/.test(ziel)) continue;
+        if (!existsSync(resolve(dirname(datei), ziel))) {
+          melde(`${datei.replace(`${wurzel}/`, "")} verlinkt das fehlende Bild ${ziel}.`);
+        }
+      }
+    }
+  }
+}
+
+// ---- 5. Verweise zwischen Markdown-Dateien --------------------------------
+{
+  const sammeln = (ordner) =>
+    readdirSync(ordner, { withFileTypes: true }).flatMap((eintrag) => {
+      if (["node_modules", ".git", ".next"].includes(eintrag.name)) return [];
+      const pfad = join(ordner, eintrag.name);
+      if (eintrag.isDirectory()) return sammeln(pfad);
+      return eintrag.name.endsWith(".md") ? [pfad] : [];
+    });
+
+  for (const datei of sammeln(wurzel)) {
+    const text = readFileSync(datei, "utf8");
+    for (const treffer of text.matchAll(/(?<!!)\[[^\]]*\]\(([^)]+)\)/g)) {
+      const ziel = treffer[1];
+      if (/^(https?:|mailto:|#)/.test(ziel)) continue;
+      const ohneAnker = ziel.split("#")[0];
+      if (!ohneAnker) continue;
+      if (!existsSync(resolve(dirname(datei), ohneAnker))) {
+        melde(`${datei.replace(`${wurzel}/`, "")} verweist auf ${ohneAnker}, das es nicht gibt.`);
+      }
+    }
+  }
+}
+
+// ---- Ergebnis --------------------------------------------------------------
+if (befunde.length > 0) {
+  console.error(`\nDokumentation und Code laufen auseinander (${befunde.length}):\n`);
+  for (const b of befunde) console.error(`  - ${b}`);
+  console.error("");
+  process.exit(1);
+}
+console.log("Dokumentation stimmt.");
@@ -0,0 +1,110 @@
+#!/usr/bin/env tsx
+/**
+ * Erzeugt die Screenshots reproduzierbar neu – fuer die Meilenstein-Belege unter
+ * docs/screenshots/<meilenstein>/ und fuer die Anleitung unter docs/anleitung/bilder/.
+ *
+ * Bilder werden nie von Hand nachbearbeitet. Aendert sich die Oberflaeche, laeuft
+ * dieses Skript erneut.
+ *
+ *   pnpm docs:screenshots                  alle Seiten nach docs/anleitung/bilder/
+ *   pnpm docs:screenshots --ziel m0        nach docs/screenshots/m0/
+ *   pnpm docs:screenshots --nur uebersicht nur diese Seite
+ *
+ * Voraussetzung: die App laeuft (pnpm start oder pnpm dev). Adresse ueber
+ * E2E_APP_URL, Standard http://127.0.0.1:3000.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { chromium, type Browser } from "@playwright/test";
+
+const APP_URL = process.env["E2E_APP_URL"] ?? "http://127.0.0.1:3000";
+
+const ANSICHTEN = [
+  { name: "desktop", breite: 1440, hoehe: 900 },
+  { name: "handy", breite: 390, hoehe: 844 },
+] as const;
+
+/** Seiten, die abgebildet werden. Waechst mit jedem Meilenstein. */
+const SEITEN: readonly { readonly name: string; readonly pfad: string }[] = [
+  { name: "uebersicht", pfad: "/" },
+];
+
+function argument(name: string): string | undefined {
+  const index = process.argv.indexOf(`--${name}`);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+async function warteAufApp(): Promise<void> {
+  for (let versuch = 1; versuch <= 30; versuch += 1) {
+    try {
+      const antwort = await fetch(APP_URL, { signal: AbortSignal.timeout(2000) });
+      if (antwort.ok) return;
+    } catch {
+      // noch nicht da
+    }
+    await new Promise((f) => setTimeout(f, 1000));
+  }
+  throw new Error(`Die App antwortet nicht auf ${APP_URL}. Erst "pnpm start" laufen lassen.`);
+}
+
+/** Erzeugt die PWA-Kacheln aus dem SVG, damit keine Bilddatei von Hand entsteht. */
+async function kachelnErzeugen(browser: Browser): Promise<void> {
+  const svg = new URL(`${APP_URL}/icon-kachel.svg`).toString();
+  for (const kante of [192, 512]) {
+    const seite = await browser.newPage({ viewport: { width: kante, height: kante } });
+    await seite.goto(svg, { waitUntil: "load" });
+    await seite.screenshot({ path: join("public", `icon-${kante}.png`), omitBackground: false });
+    await seite.close();
+    console.log(`  public/icon-${kante}.png`);
+  }
+}
+
+const zielMeilenstein = argument("ziel");
+const nur = argument("nur");
+const ziel = zielMeilenstein
+  ? join("docs", "screenshots", zielMeilenstein)
+  : join("docs", "anleitung", "bilder");
+
+await warteAufApp();
+await mkdir(ziel, { recursive: true });
+
+const browser = await chromium.launch();
+try {
+  await kachelnErzeugen(browser);
+
+  for (const seite of SEITEN.filter((s) => !nur || s.name === nur)) {
+    for (const ansicht of ANSICHTEN) {
+      const kontext = await browser.newContext({
+        viewport: { width: ansicht.breite, height: ansicht.hoehe },
+        colorScheme: "dark",
+        locale: "de-DE",
+        timezoneId: "Europe/Berlin",
+        deviceScaleFactor: 2,
+      });
+      const tab = await kontext.newPage();
+      await tab.goto(`${APP_URL}${seite.pfad}`, { waitUntil: "networkidle" });
+      // Schriften muessen geladen sein, sonst wackelt das Bild zwischen Laeufen.
+      await tab.evaluate(() => document.fonts.ready);
+
+      const datei = join(ziel, `${seite.name}-${ansicht.name}.png`);
+      await tab.screenshot({ path: datei, fullPage: ansicht.name === "desktop" });
+
+      // Am Handy darf nie horizontal gescrollt werden – hier gleich mitgeprueft.
+      if (ansicht.name === "handy") {
+        const masse = await tab.evaluate(() => ({
+          scroll: document.documentElement.scrollWidth,
+          sichtbar: document.documentElement.clientWidth,
+        }));
+        if (masse.scroll > masse.sichtbar) {
+          throw new Error(`${seite.pfad} scrollt am Handy horizontal: ${masse.scroll} > ${masse.sichtbar}`);
+        }
+      }
+
+      console.log(`  ${datei}`);
+      await kontext.close();
+    }
+  }
+} finally {
+  await browser.close();
+}
+console.log("Screenshots erzeugt.");