Suchindex ins Schema, Testdatenbank je Lauf frisch

Zwei Funde beim Nachsehen, warum `pnpm db:migrate` hängt.

**Der Befehl hing nicht, er fragte.** `prisma migrate dev` fand einen
Unterschied zwischen schema.prisma und den Migrationen und wartete auf einen
Namen für eine neue Migration. Deren Inhalt wäre gewesen, den GIN-Index über
den Suchvektor zu löschen: er stand nur in der Migration, weil
Unsupported("tsvector") dazu verleitet, den Index für nicht darstellbar zu
halten. Er ist darstellbar. Wer die Frage in Eile beantwortet hätte, hätte die
gestufte Volltextsuche verloren und es erst gemerkt, wenn die Suche leer
bleibt.

packages/db/tests/schema-drift.test.ts prüft das jetzt und nennt im Fehlerfall
das fehlende Stück. Gegengeprobt: ohne die Zeile im Schema schlägt der Test an.

Die Sperre, an der der zweite Versuch scheiterte (P1002), hielt eine verwaiste
Verbindung eines abgeschossenen migrate-dev. Wie man den Halter findet und
freigibt, steht jetzt in docs/11.

**Die Testdatenbank wird verworfen und neu angelegt.** Weil Akten nicht
löschbar sind, hatte sie 2487 angesammelt, und drei Zusicherungen auf eine auf
zehn Einträge begrenzte Liste fanden ihre eigene Akte nicht mehr darin. Das
sieht aus wie ein Fehler im Code und ist keiner. Neu aufsetzen kostet
dreieinhalb Sekunden; KEEP_TEST_DB=1 behält den Bestand.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/11-betrieb.md

@@ -261,3 +261,27 @@ Als Anker `<<: *logging` bei jedem Dienst einhängen.
 Tägliche Aufgabe in der Anwendung, kein eigener Container: abgelaufene Sessions löschen,
 Quarantäne-Dateien älter als 24 Stunden löschen, PDF-Cache älter als 30 Tage löschen.
 Der Audit-Log wird nie gelöscht.
+
+## Wenn eine Migration hängt
+
+`prisma migrate dev` ist **interaktiv**. Findet es einen Unterschied zwischen `schema.prisma`
+und den Migrationen, fragt es nach einem Namen für eine neue Migration und wartet — ohne
+Terminal sieht das aus wie ein Aufhänger. `pnpm exec prisma migrate status` sagt
+nicht-interaktiv, woran man ist, `migrate diff --from-config-datasource --to-schema
+prisma/schema.prisma --script` zeigt den Unterschied. Im Betrieb läuft ohnehin
+`migrate deploy`, das fragt nie.
+
+Wird ein laufendes `migrate dev` abgeschossen, bleibt seine Datenbankverbindung offen und
+hält die Sperre, mit der Prisma parallele Migrationen verhindert. Der nächste Versuch läuft
+dann in `P1002: Timed out trying to acquire a postgres advisory lock`. Den Halter findet man
+so:
+
+```sql
+SELECT l.pid, a.state, now() - a.state_change AS untaetig_seit, a.query
+  FROM pg_locks l JOIN pg_stat_activity a ON a.pid = l.pid
+ WHERE l.locktype = 'advisory';
+```
+
+Die verwaiste Verbindung erkennt man an `state = idle` und einer Untätigkeit, die zum
+Zeitpunkt des Abbruchs passt. `SELECT pg_terminate_backend(<pid>)` gibt die Sperre frei.
+**Nur die untätige beenden** — eine aktive gehört einem laufenden Versuch.

docs/13-entscheidungen.md

@@ -1045,3 +1045,39 @@ betroffenen Feld.
 
 Lichtbilder bleiben ausgenommen: ein Bild wird hochgeladen und geprüft, das ist ein eigener
 Vorgang mit eigener Prüfkette und keine Feldänderung.
+
+### Von Hand angelegte Indizes gehören auch ins Schema
+
+Der GIN-Index über den Suchvektor stand in der Migration, aber nicht in `schema.prisma` —
+`Unsupported("tsvector")` verleitet dazu, den Index für nicht darstellbar zu halten. Er ist
+darstellbar: `@@index([vector], type: Gin)`.
+
+Ohne die Zeile hielt Prisma den Index für einen Rückstand und fragte bei jedem `migrate dev`
+nach einem Namen für eine neue Migration. Deren Inhalt wäre gewesen, **den Suchindex zu
+löschen**. Wer die Frage in Eile beantwortet, verliert die gestufte Volltextsuche und merkt es
+erst, wenn die Suche leer bleibt — der Index ist keine Optimierung, ohne ihn scannt jede
+Anfrage sechs Zeilen je Akte.
+
+`packages/db/tests/schema-drift.test.ts` prüft das jetzt: `migrate diff` gegen die Datenbank
+des Testlaufs muss leer sein. Die Fehlermeldung nennt das fehlende Stück, damit man nicht
+sucht.
+
+Die Regel daraus: **was eine Migration von Hand anlegt, muss im Schema stehen, oder Prisma
+räumt es beim nächsten `migrate dev` weg.** Das gilt für Indizes; Regeln, Trigger und CHECKs
+kennt Prisma nicht und lässt sie in Ruhe.
+
+### Die Testdatenbank wird bei jedem Lauf neu aufgesetzt
+
+Sie wurde bisher nur angelegt, wenn sie fehlte. Weil Akten, Verlaufseinträge und
+Protokollzeilen nach harter Regel 2 nicht löschbar sind, bleibt aber alles stehen, was ein
+Testlauf anlegt — nach einigen Dutzend Läufen standen 2487 Akten darin.
+
+Das ging so lange gut, bis drei Zusicherungen brachen, die eine **auf zehn Einträge begrenzte
+Liste** prüfen: die eigene, gerade angelegte Akte war nicht mehr unter den zehn nächsten
+Fristen. Das ist die unangenehmste Sorte Fehlschlag, weil sie aussieht wie ein Fehler im Code
+und keiner ist.
+
+`test:prepare` verwirft die Datenbank jetzt und legt sie neu an; das dauert dreieinhalb
+Sekunden. Der Aufwand, so einen Fehlschlag einmal falsch zu deuten, ist grösser.
+`KEEP_TEST_DB=1` behält den Bestand, für das schnelle Nacheinander an einer einzelnen
+Testdatei. Eine Sicherung im Skript besteht darauf, dass der Name auf `_test` endet.