Ranggefuege: Rollen, die aufeinander aufbauen

Bisher trug jede Rolle ihre Rechte vollstaendig selbst. Bei achtzehn Rollen
und zweiundzwanzig Rechten heisst das, dass eine hoehere Rangrolle die ganze
Liste der darunterliegenden noch einmal abhaken muss - beim Anlegen
fehleranfaellig und bei jeder spaeteren Aenderung doppelt zu pflegen.

Ein Gefuege ist eine benannte, geordnete Folge von Rollen. Jede Sprosse
erbt alles von jeder Sprosse unter ihr, verwaltet wird nur noch das, was
oben dazukommt. Geerbt wird nicht nur die Rechteliste, sondern auch
Freigabestufe und Anmeldung: sonst waere eine Befoerderung unter Umstaenden
eine Herabstufung, naemlich immer dann, wenn Discord beim Befoerdern die
alte Rangrolle abnimmt.

Die Ordnung ist bewusst eine Reihenfolge und kein Zeiger je Rolle - ueber
ganzen Zahlen gibt es keinen Zyklus, den man abfangen muesste. Aufloesen
eines Gefueges laesst die Rollen stehen und nimmt nur das Geerbte weg.

Die Rechnung steht als reine Funktion in lib/auth/ladders.ts und wird an
drei Stellen benutzt: bei der Rechteaufloesung, in der Verwaltung und in
der Vorschau des Editors, die im Browser mitrechnet. Eine Vorschau, die den
Stand vor dem Verschieben zeigt, waere schlimmer als keine.

Die Rollenseite zeigt Geerbtes kursiv und gesperrt an, damit dort niemand
blind Kaestchen setzt, die laengst gesetzt sind.

Nebenbei: Aenderungen an der Rollenzuordnung landen jetzt im Protokoll, mit
Vorher und Nachher. Wer Rollen aendert, aendert die Rechte anderer - genau
dafuer ist es da.

packages/db/prisma/migrations/20260904140000_ranggefuege/migration.sql

@@ -0,0 +1,68 @@
+-- Ranggefüge: Rollen, die aufeinander aufbauen.
+--
+-- Bisher trug jede Rolle ihre Rechte vollständig selbst. Bei achtzehn Rollen
+-- und zweiundzwanzig Rechten heisst das, dass beim Anlegen einer höheren
+-- Rangrolle die ganze Liste der darunterliegenden noch einmal abgehakt werden
+-- muss - fehleranfällig und bei jeder späteren Änderung doppelt zu pflegen.
+--
+-- Eine Leiter ist eine benannte, geordnete Folge von Rollen. Jede Sprosse erbt
+-- alles von jeder Sprosse unter ihr. Verwaltet wird nur noch das, was oben
+-- hinzukommt.
+--
+-- Die Reihenfolge steht in `ladderRank`, 0 ist unten. Bewusst **ohne**
+-- eindeutigen Index über (ladderId, ladderRank): das Umsortieren schreibt alle
+-- Sprossen einer Leiter in einem Zug neu, und ein sofort geprüfter Index
+-- verböte die Zwischenzustände. Doppelte Ränge sind harmlos, sie erben dann
+-- gegenseitig voneinander.
+--
+-- Zyklen sind ausgeschlossen, weil eine Ordnung über ganzen Zahlen keine
+-- zulässt. Das ist der Grund für die Leiter statt eines Zeigers je Rolle.
+
+CREATE TABLE "RoleLadder" (
+    "id"          TEXT         NOT NULL,
+    "name"        TEXT         NOT NULL,
+    "note"        TEXT,
+    "createdById" TEXT,
+    "createdAt"   TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt"   TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "RoleLadder_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "RoleLadder_name_key" ON "RoleLadder"("name");
+
+ALTER TABLE "RoleMapping" ADD COLUMN "ladderId"   TEXT;
+ALTER TABLE "RoleMapping" ADD COLUMN "ladderRank" INTEGER;
+
+-- Verschwindet eine Leiter, stehen ihre Rollen wieder für sich. Ihre eigenen
+-- Rechte behalten sie; nur das Geerbte fällt weg. Ein Rollenverlust durch
+-- Löschen einer Leiter ist damit sichtbar und keine stille Rechteerweiterung.
+ALTER TABLE "RoleMapping"
+    ADD CONSTRAINT "RoleMapping_ladderId_fkey"
+    FOREIGN KEY ("ladderId") REFERENCES "RoleLadder"("id")
+    ON DELETE SET NULL ON UPDATE CASCADE;
+
+CREATE INDEX "RoleMapping_ladderId_ladderRank_idx" ON "RoleMapping"("ladderId", "ladderRank");
+
+-- Eine Sprosse ohne Leiter ist sinnlos, eine Leiter ohne Sprosse nicht.
+ALTER TABLE "RoleMapping"
+    ADD CONSTRAINT "RoleMapping_ladder_vollstaendig"
+    CHECK (("ladderId" IS NULL) = ("ladderRank" IS NULL));
+
+-- Eine Änderung an der Leiter ändert die Rechte jedes Trägers. Derselbe Kanal
+-- wie bei RoleMapping selbst, damit die Web-Anwendung ihre zwischengespeicherten
+-- Rechte sofort verwirft und nicht erst nach der Verfallszeit.
+-- Eigene Funktion, weil `notify_role_mapping_changed` die Spalte
+-- "discordRoleId" liest, die es auf dieser Tabelle nicht gibt. Der Kanal ist
+-- derselbe: die Gegenstelle unterscheidet nicht, wodurch die Zuordnung
+-- ungueltig wurde, sie verwirft ohnehin alles.
+CREATE OR REPLACE FUNCTION notify_role_ladder_changed() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_notify('role_mapping_changed', COALESCE(NEW."id", OLD."id"));
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER role_ladder_notify
+    AFTER INSERT OR UPDATE OR DELETE ON "RoleLadder"
+    FOR EACH ROW EXECUTE FUNCTION notify_role_ladder_changed();

packages/db/prisma/schema.prisma

@@ -107,9 +107,35 @@ model RoleMapping {
   /// loeschen: die Adminseite schlaegt sie anhand des Namens neu zu.
   isPresent Boolean @default(true)
 
+  /// Ranggefuege: die Leiter, in der diese Rolle steht, und ihre Sprosse
+  /// darin. Eine Rolle erbt alles von jeder Sprosse unter ihr - siehe
+  /// lib/auth/ladders.ts. Ohne Leiter steht die Rolle fuer sich.
+  ladderId String?
+  ladder   RoleLadder? @relation(fields: [ladderId], references: [id], onDelete: SetNull)
+
+  /// 0 ist die unterste Sprosse. Innerhalb einer Leiter aufsteigend.
+  ladderRank Int?
+
   updatedAt DateTime @updatedAt
 
   @@index([category, sortOrder])
+  @@index([ladderId, ladderRank])
+}
+
+/// Ein Ranggefuege: mehrere Rollen in einer festen Reihenfolge, in der die
+/// obere alles kann, was die untere kann. Damit haken Verwalter bei einer
+/// Befoerderungsrolle nur noch das Zusaetzliche an, statt die ganze Liste
+/// erneut durchzugehen.
+model RoleLadder {
+  id    String  @id @default(cuid())
+  name  String  @unique
+  note  String?
+
+  createdById String?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  roles RoleMapping[]
 }
 
 enum RoleCategory {