feat(laeufe): Uebergabeprotokoll als PDF (#041)

Neben "Drucken" steht am Lauf "Als PDF", im Archiv an jedem Treffer "Protokoll
als PDF" — dasselbe Blatt als fertige Datei, zum Verschicken oder Abheften.
Unten darauf jetzt zwei Unterschriftsfelder mit Zeile fuer Ort, Datum und Namen;
wo eine Vier-Augen-Freigabe erteilt wurde, steht sie mit im Kopf.

Erzeugt wird es, indem der Server seine eigene Druckansicht ueber 127.0.0.1
laedt und druckt — mit dem Sitzungscookie des Anfragenden. Damit gibt es genau
eine Vorlage fuer Papier und Datei, und fuer das PDF gilt dieselbe Rechte- und
Mandantenpruefung wie fuer die Seite. Ein zweites Layout waere billiger und
wuerde frueher oder spaeter abweichen, ohne dass es jemandem auffaellt.

Ein eigener Browser-Kontext je PDF, kein geteilter: er traegt die fremde
Sitzung, und ein geteilter gaebe sie an das naechste PDF weiter. Gespeichert
wird nichts — ein abgelegtes PDF waere eine zweite Wahrheit neben dem Lauf.
Ein erzeugtes Passwort steht auch hier nie darauf, geprueft am extrahierten
Text des fertigen PDF und nicht an den Bytes: der Inhalt ist komprimiert, dort
nichts zu finden bewiese nichts.

Chromium bleibt optional, und die gemessene Zahl ist der Grund: das
Laufzeitbild waechst von 370 MB auf 1,52 GB, Alpines chromium kostet allein
1,13 GB. Er kommt nur mit `--build-arg MIT_PDF=1` beziehungsweise
`deploy/install.sh --mit-pdf` mit. Fehlt er, erscheint der Knopf gar nicht
erst — ein Knopf, der zuverlaessig in eine Fehlermeldung fuehrt, ist schlimmer
als keiner. Ein direkter Aufruf bekommt 503 mit einer Meldung, die sagt, was
fehlt und wo es steht; ein leeres PDF gibt es in keinem Fall.

Meine Schaetzung lag um das Dreieinhalbfache daneben: "+328 MB" war das
.apk-Paket, nicht das Bild, und stand schon im Dockerfile-Kommentar, bevor ich
gebaut hatte. Jetzt steht die gemessene Zahl an drei Stellen.

1545 Vitest-Tests (vorher 1526): 15 in tests/pdf.test.ts, die den Handler echt
fahren, 3 in tests/pdf-grenze.test.ts fuer die Obergrenze mit gestelltem
Browser, einer in tests/archiv.test.ts. Dazu drei E2E-Ablaeufe; volle Suite
gruen mit 118 bestanden. Ein Blatt wurde wirklich erzeugt und angesehen.

Sechs Gegenproben, alle angeschlagen — darunter ein echtes Passwort auf dem
Blatt und die Freigabe des Zaehlers aus dem finally genommen, der Fall, in dem
ein Fehlschlag die PDF-Erzeugung bis zum Neustart leise stilllegt.

Closes #41

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/archiv.test.ts

@@ -669,7 +669,7 @@ describe("Trefferzeile", () => {
 
   it("führt in den Lauf und hebt jedes Vorkommen hervor", () => {
     const html = renderToStaticMarkup(
-      createElement(ArchivTreffer, { zeile, begriff: "meier", kundenEbene: false }),
+      createElement(ArchivTreffer, { zeile, begriff: "meier", kundenEbene: false, mitPdf: false }),
     );
 
     expect(html).toContain('href="/laeufe/lauf-1"');
@@ -681,9 +681,33 @@ describe("Trefferzeile", () => {
     expect(html).not.toContain("Eigene Organisation");
   });
 
+  /*
+   * Der PDF-Knopf haengt daran, ob der Server Chromium hat (#041). Beide
+   * Richtungen stehen hier, weil nur die eine Richtung allein nichts beweist:
+   * ein Knopf, der immer erscheint, waere genauso gruen.
+   */
+  it("bietet das PDF nur an, wo es eines geben kann", () => {
+    const mit = renderToStaticMarkup(
+      createElement(ArchivTreffer, { zeile, begriff: "", kundenEbene: false, mitPdf: true }),
+    );
+    expect(mit).toContain('href="/api/laeufe/lauf-1/protokoll.pdf"');
+    expect(mit).toContain("Protokoll als PDF");
+
+    const ohne = renderToStaticMarkup(
+      createElement(ArchivTreffer, { zeile, begriff: "", kundenEbene: false, mitPdf: false }),
+    );
+    expect(ohne).not.toContain("protokoll.pdf");
+    expect(ohne).not.toContain("Protokoll als PDF");
+  });
+
   it("markiert ohne Begriff nichts", () => {
     const html = renderToStaticMarkup(
-      createElement(ArchivTreffer, { zeile: { ...zeile, fundstellen: [] }, begriff: "", kundenEbene: true }),
+      createElement(ArchivTreffer, {
+        zeile: { ...zeile, fundstellen: [] },
+        begriff: "",
+        kundenEbene: true,
+        mitPdf: false,
+      }),
     );
 
     expect(html).not.toContain("<mark");

tests/e2e/uebersicht-druck.spec.ts

@@ -1,6 +1,18 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { expect, test } from "@playwright/test";
 import "dotenv/config";
 import { prisma } from "@/lib/db";
+import {
+  PASSWORT_GROSS,
+  PASSWORT_IM_DRUCK,
+  PASSWORT_KLEIN,
+  PASSWORT_LAENGE,
+  PASSWORT_SONDER,
+  PASSWORT_ZIFFERN,
+} from "@/lib/passwort";
 import { anmelden } from "./helfer";
 
 /**
@@ -163,6 +175,146 @@ test.describe("Druckansicht", () => {
   });
 });
 
+/**
+ * Ob `pdftotext` da ist – ohne es laesst sich der Text eines PDF nicht lesen.
+ *
+ * Der Inhalt eines PDF ist komprimiert. In den rohen Bytes nach einem Passwort
+ * zu suchen und nichts zu finden wuerde **nichts** beweisen: ein Passwort, das
+ * drinsteht, stuende dort auch nicht im Klartext. Entweder richtig extrahieren
+ * oder den Test ueberspringen und das laut sagen – wie bei `ldap` und `mailpit`
+ * im Commit-Tor.
+ */
+const MIT_PDFTOTEXT = (() => {
+  try {
+    execFileSync("pdftotext", ["-v"], { stdio: "ignore" });
+    return true;
+  } catch {
+    process.stderr.write(
+      "\n[uebersicht-druck] pdftotext fehlt – der Text des PDF wird nicht geprueft.\n" +
+        "  Auf Debian: apt-get install poppler-utils\n\n",
+    );
+    return false;
+  }
+})();
+
+/** Der Text eines PDF, ueber `pdftotext`. */
+function pdfText(bytes: Buffer): string {
+  const ordner = mkdtempSync(join(tmpdir(), "laufzettel-pdf-"));
+  try {
+    const datei = join(ordner, "blatt.pdf");
+    writeFileSync(datei, bytes);
+    execFileSync("pdftotext", ["-layout", datei, join(ordner, "blatt.txt")]);
+    return readFileSync(join(ordner, "blatt.txt"), "utf8");
+  } finally {
+    rmSync(ordner, { recursive: true, force: true });
+  }
+}
+
+test.describe("Das PDF-Übergabeprotokoll", () => {
+  /**
+   * Holt das PDF eines Laufs oder ueberspringt den Ablauf.
+   *
+   * **Der Knopf ist das Signal.** Er erscheint nur, wenn der Server Chromium
+   * findet (#041); fehlt er, ist das keine Stoerung, sondern eine Installation
+   * ohne PDF-Erzeugung. Dann hat dieser Ablauf nichts zu pruefen und sagt es.
+   */
+  async function pdfHolen(seite: import("@playwright/test").Page, laufId: string): Promise<Buffer> {
+    const knopf = seite.getByRole("link", { name: "Als PDF" });
+    test.skip(
+      (await knopf.count()) === 0,
+      "Dieser Server hat kein Chromium – der PDF-Knopf erscheint deshalb nicht. " +
+        "Siehe docs/betrieb/pdf.md.",
+    );
+
+    const antwort = await seite.request.get(`/api/laeufe/${laufId}/protokoll.pdf`);
+    expect(antwort.status(), await antwort.text()).toBe(200);
+    expect(antwort.headers()["content-type"]).toBe("application/pdf");
+    const bytes = await antwort.body();
+    // Ein PDF, das keines ist, waere ein leeres Blatt mit richtigem Kopf.
+    expect(bytes.subarray(0, 5).toString("latin1")).toBe("%PDF-");
+    return bytes;
+  }
+
+  test("entsteht aus dem Lauf heraus und traegt das ganze Blatt", async ({ page }) => {
+    test.skip(test.info().project.name !== "desktop", "Das Blatt haengt nicht am Geraet.");
+    const lauf = await laufMitPasswortschritt();
+    await anmelden(page);
+    await page.goto(`/laeufe/${lauf.id}`);
+
+    const bytes = await pdfHolen(page, lauf.id);
+    test.skip(!MIT_PDFTOTEXT, "Ohne pdftotext ist der Text des PDF nicht lesbar.");
+    const text = pdfText(bytes);
+
+    // Titel, Vorlage mit Version, der Abschnitt und der Schritt – das Blatt ist
+    // vollstaendig und nicht nur ein gueltiges PDF.
+    expect(text).toContain(lauf.titel);
+    expect(text).toContain("Version 1");
+    expect(text).toContain("Konto");
+    expect(text).toContain("Konto angelegt");
+    // Und das Unterschriftenfeld, das dieses Blatt zum Uebergabeprotokoll macht.
+    expect(text).toContain("Übergeben von");
+    expect(text).toContain("Übernommen von");
+  });
+
+  test("traegt kein erzeugtes Passwort", async ({ page }) => {
+    /*
+     * **Die Zusage, die am teuersten waere, wenn sie bricht.** Die Vorlage
+     * dieses Laufs enthaelt `{{generiertes_passwort}}` im Befehl; auf dem Blatt
+     * muss der Ersatztext stehen und nirgends ein Passwort.
+     *
+     * Geprueft wird am extrahierten Text und nicht an den Bytes – siehe
+     * `MIT_PDFTOTEXT`.
+     */
+    test.skip(test.info().project.name !== "desktop", "Das Blatt haengt nicht am Geraet.");
+    const lauf = await laufMitPasswortschritt();
+    await anmelden(page);
+    await page.goto(`/laeufe/${lauf.id}`);
+
+    const bytes = await pdfHolen(page, lauf.id);
+    test.skip(!MIT_PDFTOTEXT, "Ohne pdftotext ist der Text des PDF nicht lesbar.");
+    const text = pdfText(bytes);
+
+    expect(text).toContain(PASSWORT_IM_DRUCK);
+    // Der Platzhalter selbst darf auch nicht stehenbleiben.
+    expect(text).not.toContain("generiertes_passwort");
+
+    /*
+     * Und der Beweis, der ohne Kenntnis des Textes auskommt: irgendeine Folge
+     * aus genau den Zeichen, aus denen `passwortErzeugen` baut, in voller
+     * Laenge. Ein echtes Passwort traegt immer eines aus jeder Gruppe, also
+     * verlangt das Muster das auch – sonst traefe es Fliesstext.
+     */
+    const alphabet = PASSWORT_GROSS + PASSWORT_KLEIN + PASSWORT_ZIFFERN + PASSWORT_SONDER;
+    /*
+     * Der Bindestrich geht ans Ende der Zeichenklasse, wo er sich selbst meint.
+     * Ihn zu maskieren ist der naheliegende Weg und war der falsche: in einer
+     * Vorlagenzeichenkette wird aus `\\-` ein `\-`, und mit dem `u`-Schalter
+     * ist das eine ungueltige Maskierung – der Ausdruck wirft dann schon beim
+     * Bauen. Keines der uebrigen Sonderzeichen hat in einer Klasse Bedeutung.
+     */
+    const klasse = alphabet.replace("-", "") + "-";
+    const kandidaten = (text.match(new RegExp(`[${klasse}]{${PASSWORT_LAENGE}}`, "gu")) ?? []).filter(
+      // Eine Kennung aus der Datenbank ist 25 Zeichen aus einem aehnlichen
+      // Alphabet; sie steht im Dateinamen und ist kein Passwort.
+      (treffer) => !lauf.id.includes(treffer),
+    );
+    expect(kandidaten, `Passwortverdacht auf dem Blatt: ${kandidaten.join(", ")}`).toEqual([]);
+  });
+
+  test("gibt den Lauf eines fremden Kunden nicht heraus", async ({ page }) => {
+    /*
+     * Dieselbe Zusage wie an der Druckansicht, nur ueber den neuen Weg. Ein
+     * Endpunkt, der ein ganzes Blatt ausgibt, waere der bequemste Zugang zu
+     * einem fremden Lauf.
+     */
+    test.skip(test.info().project.name !== "desktop", "Die Mandantengrenze haengt nicht am Geraet.");
+    await anmelden(page);
+    const antwort = await page.request.get("/api/laeufe/gibtesnicht/protokoll.pdf");
+    expect(antwort.status()).toBe(404);
+    expect(antwort.headers()["content-type"]).toContain("application/json");
+  });
+});
+
 test.afterAll(async () => {
   const laeufe = await prisma.lauf.findMany({
     where: { titel: { startsWith: PRAEFIX } },

tests/pdf-grenze.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Die Obergrenze gleichzeitiger PDF-Erzeugungen (#041).
+ *
+ * **Eine eigene Datei, weil hier `@/server/pdf` *nicht* gemockt werden darf.**
+ * `tests/pdf.test.ts` ersetzt `seiteAlsPdf`, um den Route Handler zu fahren;
+ * hier läuft genau diese Funktion echt, und nur der Browser darunter ist
+ * gestellt. Sonst prüfte der Test seine eigene Attrappe.
+ *
+ * Geprüft wird das Akzeptanzkriterium „zwei gleichzeitige Erzeugungen laufen,
+ * die dritte wird abgewiesen“ — und dass die Grenze sich wieder öffnet. Eine
+ * Grenze, die nach einem Fehler klemmt, legt die PDF-Erzeugung bis zum
+ * Neustart still, und zwar leise.
+ */
+
+/** Hält jede laufende Erzeugung an, bis der Test sie freigibt. */
+let anhalten: Array<() => void> = [];
+let laufendeSeiten = 0;
+
+const seiteGestellt = {
+  emulateMedia: async () => undefined,
+  goto: async () => ({ status: () => 200 }),
+  evaluate: async () => undefined,
+  pdf: async () => {
+    laufendeSeiten += 1;
+    await new Promise<void>((weiter) => anhalten.push(weiter));
+    return new Uint8Array(Buffer.from("%PDF-1.4\n%%EOF\n", "utf8"));
+  },
+};
+
+const browserGestellt = {
+  isConnected: () => true,
+  newContext: async () => ({
+    newPage: async () => seiteGestellt,
+    close: async () => undefined,
+  }),
+  close: async () => undefined,
+};
+
+vi.mock("playwright-core", () => ({
+  chromium: { launch: async () => browserGestellt },
+}));
+
+const { seiteAlsPdf, PdfFehler, pdfVorratSchliessen } = await import("@/server/pdf");
+
+const VORHER = {
+  pfad: process.env["CHROMIUM_PFAD"],
+  max: process.env["PDF_MAX_GLEICHZEITIG"],
+};
+
+beforeEach(() => {
+  // Irgendeine Datei, die es gibt – `chromiumPfad` prüft nur, ob dort etwas liegt.
+  process.env["CHROMIUM_PFAD"] = process.execPath;
+  anhalten = [];
+  laufendeSeiten = 0;
+});
+
+afterEach(async () => {
+  // Alles freigeben, sonst hängt ein Test am nächsten.
+  for (const weiter of anhalten) weiter();
+  await pdfVorratSchliessen();
+  for (const [name, wert] of [
+    ["CHROMIUM_PFAD", VORHER.pfad],
+    ["PDF_MAX_GLEICHZEITIG", VORHER.max],
+  ] as const) {
+    if (wert === undefined) delete process.env[name];
+    else process.env[name] = wert;
+  }
+});
+
+describe("Die Obergrenze gleichzeitiger PDF-Erzeugungen", () => {
+  it("lässt so viele zu wie eingestellt und weist die nächste ab", async () => {
+    process.env["PDF_MAX_GLEICHZEITIG"] = "2";
+
+    const erste = seiteAlsPdf("/drucken/lauf/a", null);
+    const zweite = seiteAlsPdf("/drucken/lauf/b", null);
+    // Beide müssen wirklich angefangen haben, bevor die dritte kommt.
+    await vi.waitFor(() => expect(laufendeSeiten).toBe(2));
+
+    await expect(seiteAlsPdf("/drucken/lauf/c", null)).rejects.toThrow(PdfFehler);
+    await expect(seiteAlsPdf("/drucken/lauf/c", null)).rejects.toThrow(/noch einmal versuchen/u);
+    // Die dritte hat keinen Browser angefasst.
+    expect(laufendeSeiten).toBe(2);
+
+    for (const weiter of anhalten) weiter();
+    await expect(erste).resolves.toBeInstanceOf(Uint8Array);
+    await expect(zweite).resolves.toBeInstanceOf(Uint8Array);
+  });
+
+  it("gibt den Platz wieder frei, sobald eine fertig ist", async () => {
+    process.env["PDF_MAX_GLEICHZEITIG"] = "1";
+
+    const erste = seiteAlsPdf("/drucken/lauf/a", null);
+    await vi.waitFor(() => expect(laufendeSeiten).toBe(1));
+    await expect(seiteAlsPdf("/drucken/lauf/b", null)).rejects.toThrow(PdfFehler);
+
+    anhalten.shift()?.();
+    await erste;
+
+    // Und jetzt geht es wieder – die Grenze zählt herunter, nicht nur herauf.
+    const zweite = seiteAlsPdf("/drucken/lauf/b", null);
+    await vi.waitFor(() => expect(laufendeSeiten).toBe(2));
+    anhalten.pop()?.();
+    await expect(zweite).resolves.toBeInstanceOf(Uint8Array);
+  });
+
+  it("gibt den Platz auch frei, wenn die Erzeugung scheitert", async () => {
+    /*
+     * **Der Fall, der eine Grenze still klemmen lässt.** Steht die Freigabe
+     * nicht im `finally`, zählt ein Fehlschlag den Zähler nie zurück: nach
+     * `PDF_MAX_GLEICHZEITIG` Fehlern entsteht bis zum Neustart kein PDF mehr,
+     * und die Meldung spricht von Gleichzeitigkeit, obwohl niemand etwas tut.
+     */
+    process.env["PDF_MAX_GLEICHZEITIG"] = "1";
+
+    const kaputt = vi.spyOn(seiteGestellt, "goto").mockResolvedValueOnce({ status: () => 500 });
+    await expect(seiteAlsPdf("/drucken/lauf/a", null)).rejects.toThrow(PdfFehler);
+    kaputt.mockRestore();
+
+    const danach = seiteAlsPdf("/drucken/lauf/b", null);
+    await vi.waitFor(() => expect(laufendeSeiten).toBe(1));
+    anhalten.pop()?.();
+    await expect(danach).resolves.toBeInstanceOf(Uint8Array);
+  });
+});

tests/pdf.test.ts

@@ -0,0 +1,375 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Betriebsmodus, VersionStatus } from "@/generated/prisma/enums";
+import { RechteFehler } from "@/server/auth/sitzungspflicht";
+import { datenbankLeeren, datenbankVerfuegbar, testPrisma } from "./helpers/db";
+
+/**
+ * Das PDF-Übergabeprotokoll (#041).
+ *
+ * **Zwei Teile, und der zweite ist der wichtigere.** Oben stehen die reinen
+ * Helfer — wo Chromium liegt, wie viele PDFs gleichzeitig entstehen dürfen. Die
+ * brauchen keine Datenbank und keinen Browser.
+ *
+ * Unten wird der **Route Handler echt gefahren**, mit echten `Request`-Objekten
+ * und echter Datenbank, wie bei den SCIM-Handlern und bei `/api/anhaenge`. Nur
+ * die Sitzung wird gestellt und die Browser-Erzeugung ersetzt: ein Chromium je
+ * Testfall zu starten kostet Sekunden und prüft nichts, was hier zur Debatte
+ * steht. Dass aus einer echten Druckansicht ein echtes PDF wird, prüft
+ * `tests/e2e/pdf.spec.ts` im Browser — der einzige Ort, an dem das geht.
+ *
+ * Die Prüfung, die diese Datei vor allem festhält: **ohne Sichtbarkeit des Laufs
+ * startet gar kein Browser.** Sonst wäre ein PDF-Versuch ein Weg
+ * herauszufinden, ob es einen Lauf mit dieser Kennung gibt — und zwar einer, der
+ * keine Spur hinterlässt, weil nichts ins Protokoll kommt.
+ */
+
+/* Der Handler wird echt gefahren; nur Sitzung und Browser werden gestellt. */
+vi.mock("@/server/auth/sitzungspflicht", async (original) => {
+  const echt = await original<typeof import("@/server/auth/sitzungspflicht")>();
+  return { ...echt, rechtErforderlich: vi.fn() };
+});
+
+vi.mock("@/server/pdf", async (original) => {
+  const echt = await original<typeof import("@/server/pdf")>();
+  // `PdfFehler` bleibt echt – der Handler unterscheidet daran die Antwort.
+  return { ...echt, seiteAlsPdf: vi.fn() };
+});
+
+const { rechtErforderlich } = await import("@/server/auth/sitzungspflicht");
+const { PdfFehler, seiteAlsPdf, chromiumPfad, maxPdfs, pdfLeerlaufMs, pdfVerfuegbar, eigeneBasis } =
+  await import("@/server/pdf");
+const { GET } = await import("@/app/api/laeufe/[id]/protokoll.pdf/route");
+
+const kennung = (id: string) => ({ params: Promise.resolve({ id }) });
+const anfrage = (kopf: Record<string, string> = {}) =>
+  new Request("http://127.0.0.1:3300/api/laeufe/egal/protokoll.pdf", { headers: kopf });
+
+/** Ein winziges, gültiges PDF – es wird nur durchgereicht. */
+const BLATT = new Uint8Array(Buffer.from("%PDF-1.4\n1 0 obj\n<<>>\nendobj\n%%EOF\n", "utf8"));
+
+describe("Wo Chromium liegt", () => {
+  const VORHER = process.env["CHROMIUM_PFAD"];
+
+  afterEach(() => {
+    if (VORHER === undefined) delete process.env["CHROMIUM_PFAD"];
+    else process.env["CHROMIUM_PFAD"] = VORHER;
+  });
+
+  it("nimmt einen gesetzten Pfad, der auch existiert", async () => {
+    // Eine Datei, die es auf jedem System gibt, auf dem diese Suite läuft.
+    process.env["CHROMIUM_PFAD"] = process.execPath;
+    await expect(chromiumPfad()).resolves.toBe(process.execPath);
+  });
+
+  it("meldet einen gesetzten Pfad, der ins Leere zeigt – und sucht nicht weiter", async () => {
+    /*
+     * **Der Unterschied, der zählt.** Wer `CHROMIUM_PFAD` eingetragen hat, hat
+     * eine Absicht; still auf `/usr/bin/chromium` auszuweichen würde heißen,
+     * dass ein Tippfehler unbemerkt bleibt und ein anderer Browser läuft als
+     * der gemeinte.
+     */
+    process.env["CHROMIUM_PFAD"] = "/gibt/es/nicht/chromium";
+    await expect(chromiumPfad()).rejects.toThrow(PdfFehler);
+    await expect(chromiumPfad()).rejects.toThrow(/gibt\/es\/nicht/);
+    // Und der Verweis auf die Stelle, wo es steht.
+    await expect(chromiumPfad()).rejects.toThrow(/docs\/betrieb\/pdf\.md/);
+  });
+
+  it("sagt der Oberfläche ohne Ausnahme ab, wenn der Pfad falsch steht", async () => {
+    /*
+     * `pdfVerfuegbar` entscheidet, ob der Knopf erscheint. Ein falsch gesetztes
+     * `CHROMIUM_PFAD` darf die Lauf-Seite nicht mitnehmen – dort wäre der Fehler
+     * an der falschen Stelle sichtbar.
+     */
+    process.env["CHROMIUM_PFAD"] = "/gibt/es/nicht/chromium";
+    await expect(pdfVerfuegbar()).resolves.toBe(false);
+
+    process.env["CHROMIUM_PFAD"] = process.execPath;
+    await expect(pdfVerfuegbar()).resolves.toBe(true);
+  });
+});
+
+describe("Die Grenzen der PDF-Erzeugung", () => {
+  const VORHER_MAX = process.env["PDF_MAX_GLEICHZEITIG"];
+  const VORHER_LEER = process.env["PDF_LEERLAUF_MS"];
+  const VORHER_PORT = process.env["PORT"];
+
+  afterEach(() => {
+    for (const [name, wert] of [
+      ["PDF_MAX_GLEICHZEITIG", VORHER_MAX],
+      ["PDF_LEERLAUF_MS", VORHER_LEER],
+      ["PORT", VORHER_PORT],
+    ] as const) {
+      if (wert === undefined) delete process.env[name];
+      else process.env[name] = wert;
+    }
+  });
+
+  it("hält an der Vorgabe fest, wo nichts oder Unsinn eingestellt ist", () => {
+    delete process.env["PDF_MAX_GLEICHZEITIG"];
+    expect(maxPdfs()).toBe(2);
+    delete process.env["PDF_LEERLAUF_MS"];
+    expect(pdfLeerlaufMs()).toBe(60_000);
+
+    /*
+     * Eine `0` oder ein Wort würde die Erzeugung ganz abschalten
+     * beziehungsweise den Browser sofort schließen. Beides wäre eine
+     * Fehlkonfiguration, die aussieht wie ein kaputtes Programm.
+     */
+    for (const unsinn of ["0", "-1", "viele", ""]) {
+      process.env["PDF_MAX_GLEICHZEITIG"] = unsinn;
+      expect(maxPdfs()).toBe(2);
+    }
+    for (const unsinn of ["0", "10", "sofort", ""]) {
+      process.env["PDF_LEERLAUF_MS"] = unsinn;
+      expect(pdfLeerlaufMs()).toBe(60_000);
+    }
+  });
+
+  it("nimmt vernünftige Werte an und schneidet Bruchteile ab", () => {
+    process.env["PDF_MAX_GLEICHZEITIG"] = "4";
+    expect(maxPdfs()).toBe(4);
+    process.env["PDF_MAX_GLEICHZEITIG"] = "3.7";
+    expect(maxPdfs()).toBe(3);
+
+    process.env["PDF_LEERLAUF_MS"] = "5000";
+    expect(pdfLeerlaufMs()).toBe(5000);
+  });
+
+  it("ruft den eigenen Port auf, nicht die öffentliche Adresse", () => {
+    /*
+     * **Mit Absicht nicht `APP_URL`.** Hinter einem Reverse Proxy wäre das ein
+     * Weg nach draußen und zurück, mit TLS, Proxy-Regeln und einer zweiten
+     * Stelle, an der etwas klemmen kann.
+     */
+    process.env["PORT"] = "3300";
+    expect(eigeneBasis()).toBe("http://127.0.0.1:3300");
+    delete process.env["PORT"];
+    expect(eigeneBasis()).toBe("http://127.0.0.1:3000");
+  });
+});
+
+async function aufbau() {
+  const kunde = await testPrisma.kunde.create({
+    data: { name: "Eigene Organisation", kuerzel: "EIGEN", istEigeneOrganisation: true },
+  });
+  await testPrisma.einstellung.create({ data: { id: "global", modus: Betriebsmodus.INTERN } });
+  const admin = await testPrisma.benutzer.create({
+    data: { email: "admin@firma.example", name: "Admin", rolle: "ADMIN" },
+  });
+
+  const vorlage = await testPrisma.vorlage.create({ data: { name: "PC Neuinstallation" } });
+  const version = await testPrisma.vorlagenVersion.create({
+    data: { vorlageId: vorlage.id, version: 1, status: VersionStatus.ENTWURF },
+  });
+  const abschnitt = await testPrisma.vorlagenAbschnitt.create({
+    data: { versionId: version.id, titel: "Vorbereitung", position: 0 },
+  });
+  await testPrisma.vorlagenSchritt.create({
+    data: { abschnittId: abschnitt.id, titel: "Datensicherung geprüft", position: 0 },
+  });
+  await testPrisma.vorlagenVersion.update({
+    where: { id: version.id },
+    data: { status: VersionStatus.VEROEFFENTLICHT, veroeffentlichtAm: new Date() },
+  });
+
+  const lauf = await testPrisma.lauf.create({
+    data: { vorlagenVersionId: version.id, titel: "Ein Lauf", kundeId: kunde.id },
+  });
+
+  return { kunde, admin: { id: admin.id, rolle: admin.rolle }, laufId: lauf.id };
+}
+
+describe.runIf(datenbankVerfuegbar)("Das PDF über seine Adresse", () => {
+  beforeEach(async () => {
+    await datenbankLeeren();
+    vi.mocked(rechtErforderlich).mockReset();
+    vi.mocked(seiteAlsPdf).mockReset();
+  });
+
+  it("weist ohne Anmeldung ab, bevor ein Browser startet", async () => {
+    const { laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockRejectedValue(new RechteFehler("Nicht angemeldet."));
+    const antwort = await GET(anfrage(), kennung(laufId));
+
+    expect(antwort.status).toBe(401);
+    // Und kein Chromium hat angefangen zu laufen.
+    expect(seiteAlsPdf).not.toHaveBeenCalled();
+  });
+
+  it("weist auch ab, wenn die Rolle das Recht lesen nicht hat", async () => {
+    // `MITARBEITER` hat seit #035 kein `lesen`; `selbstauskunft` ist dessen Ersatz.
+    const { laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockRejectedValue(new RechteFehler("Dafür fehlt dir die Berechtigung."));
+    expect((await GET(anfrage(), kennung(laufId))).status).toBe(401);
+    expect(seiteAlsPdf).not.toHaveBeenCalled();
+  });
+
+  it("liefert das Blatt mit den Kopfzeilen eines PDF", async () => {
+    const { admin, laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    vi.mocked(seiteAlsPdf).mockResolvedValue(BLATT);
+    const antwort = await GET(anfrage(), kennung(laufId));
+
+    expect(antwort.status).toBe(200);
+    expect(antwort.headers.get("content-type")).toBe("application/pdf");
+    expect(antwort.headers.get("content-length")).toBe(String(BLATT.byteLength));
+    expect(antwort.headers.get("x-content-type-options")).toBe("nosniff");
+    /*
+     * `inline` und ein Dateiname **ohne** Titel: ein Titel enthält Leerzeichen,
+     * Umlaute und Schrägstriche, und ein `Content-Disposition` mit rohem Titel
+     * ist eine Einladung zum Kopfzeilen-Einschub.
+     */
+    expect(antwort.headers.get("content-disposition")).toBe(`inline; filename="laufzettel-${laufId}.pdf"`);
+    expect(antwort.headers.get("content-disposition")).not.toContain("Ein Lauf");
+    // Ein Blatt gehört einem Kunden; ein öffentlicher Cache gäbe es weiter.
+    expect(antwort.headers.get("cache-control")).toContain("private");
+
+    expect(Buffer.from(await antwort.arrayBuffer()).equals(Buffer.from(BLATT))).toBe(true);
+  });
+
+  it("druckt dieselbe Seite, die die Druckansicht zeigt – mit der Sitzung des Anfragenden", async () => {
+    /*
+     * **Es gibt genau eine Vorlage für das Blatt.** Würde hier ein zweites
+     * Layout entstehen, liefen Papier und PDF auseinander, und niemand merkte
+     * es, bis ein Kunde zwei verschiedene Blätter nebeneinander legt.
+     *
+     * Das Cookie muss mit, weil die Druckansicht ihr Recht selbst prüft. Damit
+     * gilt für das PDF dieselbe Rechte- und Mandantenprüfung wie für die Seite.
+     */
+    const { admin, laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    vi.mocked(seiteAlsPdf).mockResolvedValue(BLATT);
+    await GET(anfrage({ cookie: "laufzettel_sitzung=abc" }), kennung(laufId));
+
+    expect(seiteAlsPdf).toHaveBeenCalledWith(`/drucken/lauf/${laufId}`, "laufzettel_sitzung=abc");
+  });
+
+  it("gibt das Blatt eines fremden Kunden nicht heraus – und startet dafür keinen Browser", async () => {
+    /*
+     * Der Techniker ist auf einen anderen Kunden beschränkt; die Kennung des
+     * Laufs kennt er. Ohne diese Prüfung reicht die Kennung — und das PDF wäre
+     * der bequemste Weg an einen fremden Lauf, weil es den ganzen Inhalt auf
+     * einem Blatt ausgibt.
+     */
+    const vorher = process.env["OIDC_CUSTOMER_GROUP_PREFIX"];
+    process.env["OIDC_CUSTOMER_GROUP_PREFIX"] = "kunde-";
+    try {
+      const { laufId } = await aufbau();
+      await testPrisma.einstellung.update({
+        where: { id: "global" },
+        data: { modus: Betriebsmodus.DIENSTLEISTUNG },
+      });
+
+      const fremd = await testPrisma.kunde.create({ data: { name: "Fremd GmbH", kuerzel: "FRD" } });
+      const techniker = await testPrisma.benutzer.create({
+        data: { email: "tina@firma.example", name: "Tina", rolle: "TECHNIKER" },
+      });
+      await testPrisma.benutzerKunde.create({
+        data: { benutzerId: techniker.id, kundeId: fremd.id },
+      });
+
+      vi.mocked(rechtErforderlich).mockResolvedValue({
+        benutzer: { id: techniker.id, rolle: techniker.rolle },
+      } as never);
+      const antwort = await GET(anfrage(), kennung(laufId));
+
+      /*
+       * `404` und nicht `403`: nicht vorhanden und nicht sichtbar sind dieselbe
+       * Antwort. Die Unterscheidung wäre schon eine Auskunft über fremde Kunden.
+       */
+      expect(antwort.status).toBe(404);
+      expect(seiteAlsPdf).not.toHaveBeenCalled();
+      const daten = JSON.stringify(await antwort.json());
+      expect(daten).not.toContain("Ein Lauf");
+      expect(daten).not.toContain("Eigene Organisation");
+    } finally {
+      if (vorher === undefined) delete process.env["OIDC_CUSTOMER_GROUP_PREFIX"];
+      else process.env["OIDC_CUSTOMER_GROUP_PREFIX"] = vorher;
+    }
+  });
+
+  it("antwortet 404 für eine Kennung, die es nicht gibt", async () => {
+    const { admin } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    const antwort = await GET(anfrage(), kennung("gibtesnicht"));
+
+    expect(antwort.status).toBe(404);
+    expect(seiteAlsPdf).not.toHaveBeenCalled();
+  });
+
+  it("sagt verständlich, wenn Chromium fehlt – und verweist auf die Betriebsdoku", async () => {
+    /*
+     * **Eine Meldung, kein stilles leeres PDF** (Akzeptanzkriterium von #041).
+     * `503` und nicht `500`: es ist kein Fehler in diesem Code, sondern ein
+     * Dienst, der hier nicht eingerichtet ist.
+     */
+    const { admin, laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    vi.mocked(seiteAlsPdf).mockRejectedValue(
+      new PdfFehler(
+        "Auf diesem Server ist kein Chromium installiert, und ohne ihn entsteht kein PDF. " +
+          "Die Druckansicht funktioniert weiterhin: dort im Browser „in eine Datei drucken“. " +
+          "Wie Chromium dazukommt, steht in docs/betrieb/pdf.md.",
+      ),
+    );
+    const antwort = await GET(anfrage(), kennung(laufId));
+
+    expect(antwort.status).toBe(503);
+    const { fehler } = (await antwort.json()) as { fehler: string };
+    expect(fehler).toContain("kein Chromium");
+    // Der Weg, der trotzdem funktioniert, und die Stelle, wo das Nachlesen steht.
+    expect(fehler).toContain("Druckansicht");
+    expect(fehler).toContain("docs/betrieb/pdf.md");
+  });
+
+  it("sagt verständlich, wenn gerade zu viele PDFs entstehen", async () => {
+    const { admin, laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    vi.mocked(seiteAlsPdf).mockRejectedValue(
+      new PdfFehler(
+        "Es entstehen gerade 2 PDFs gleichzeitig, und mehr sind nicht eingestellt. " +
+          "Bitte einen Augenblick warten und noch einmal versuchen.",
+      ),
+    );
+    const antwort = await GET(anfrage(), kennung(laufId));
+
+    expect(antwort.status).toBe(503);
+    expect(((await antwort.json()) as { fehler: string }).fehler).toContain("noch einmal versuchen");
+  });
+
+  it("verrät bei einem unerwarteten Fehler nichts über den Server", async () => {
+    /*
+     * Eine rohe Ausnahme kann Pfade und Zugangsdaten nennen (#025). Sie gehört
+     * ins Protokoll des Prozesses, nicht in die Antwort.
+     */
+    const { admin, laufId } = await aufbau();
+
+    vi.mocked(rechtErforderlich).mockResolvedValue({ benutzer: admin } as never);
+    vi.mocked(seiteAlsPdf).mockRejectedValue(
+      new Error("connect ECONNREFUSED /var/run/postgres/.s.PGSQL.5432 als laufzettel"),
+    );
+    const protokoll = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+      const antwort = await GET(anfrage(), kennung(laufId));
+
+      expect(antwort.status).toBe(500);
+      const roh = JSON.stringify(await antwort.json());
+      expect(roh).not.toContain("ECONNREFUSED");
+      expect(roh).not.toContain("/var/run");
+      expect(roh).not.toContain("laufzettel");
+      // Aber es steht im Protokoll des Dienstes, sonst sucht niemand.
+      expect(protokoll).toHaveBeenCalled();
+      expect(protokoll.mock.calls.flat().join(" ")).toContain("ECONNREFUSED");
+    } finally {
+      protokoll.mockRestore();
+    }
+  });
+});