dogfather-universe/server/workspace-spenden.js

/* =====================================================================
   DIE SPENDEN — die Wege (28.09.2026)

   Drei Herkuenfte, eine Tabelle, ein Weg ins Bild. Die Begruendung
   fuer die drei steht in spenden-tabellen.js.

   ---------------------------------------------------------------------
   DER EINFACHSTE WEG FUER EINEN ZUSCHAUER

   Vier Knoepfe mit Betraegen. Ein Tipp oeffnet PayPal mit schon
   eingetragener Summe (`paypal.me/<name>/5EUR`). Danach kommt er
   zurueck, und die Seite fragt EINMAL: „Hast du gespendet?" Sagt er
   ja, steht die Spende als OFFEN im Pult und wartet auf einen Tipp
   der Leitung.

   DIE ADRESSE WIRD NICHT ZWEIMAL GEPFLEGT. Sie steht auf der
   Unterstuetzen-Seite, dort und nur dort. Was hier passiert, ist
   Lesen und Anhaengen des Betrags -- und wenn dort nichts steht oder
   der Weg auf unsichtbar gestellt ist, gibt es hier auch keine
   Knoepfe. Eine geratene Kontoadresse waere die gefaehrlichste aller
   Abkuerzungen.

   ---------------------------------------------------------------------
   WARUM DER BETRAG NICHT AN DIE ADRESSE GEBUNDEN IST

   `paypal.me/x/5EUR` traegt den Betrag VOR -- aendern kann ihn jeder
   auf PayPals Seite, und das ist auch richtig so. Was hier steht,
   ist deshalb nie die Wahrheit ueber das Geld, sondern nur ein
   Vorschlag. Die Wahrheit kommt entweder von PayPal selbst (Webhook)
   oder von einem Menschen, der die Meldung auf seinem Handy gesehen
   hat. Alles andere waere geraten.
   ===================================================================== */
import express from "express";
import {
  db, sitzungLesen, protokolliere, echteIp, einstellung, einstellungSetzen,
  hausBedingung,
} from "./workspace.js";
import { stromAn } from "./workspace-chat.js";
import { buehneMelden } from "./workspace-buehne.js";
import { join } from "node:path";
import { mkdirSync, writeFileSync, unlinkSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { DATEN_ORDNER } from "./workspace.js";
import {
  BETRAG_MAX_CENT, NAME_MAX, GRUSS_MAX, KNOEPFE_MILLE, SPENDEN_TAGE,
  VORLAGEN, STUFEN_MAX, DAUER_MS_MIN, DAUER_MS_MAX,
  GROESSE_MIN, GROESSE_MAX, BILD_MAX_BYTES,
  centInMille, milleInCent, ZEICHEN_NAME,
} from "./spenden-tabellen.js";

const BILDER = join(DATEN_ORDNER, "spendenbilder");

export const spendenRouter = express.Router();

/** Wer eine Spende bestaetigen, eintragen oder ablehnen darf.
 *
 *  Dieselben zwei, die die Sendung fuehren. Geld ist keine
 *  Moderationsaufgabe: Einen Beitrag wegzunehmen ist umkehrbar,
 *  einen Betrag im Bild gross zu machen nicht. */
const GELD_ROLLEN = new Set(["admin", "hand"]);
export const SPENDEN_ROLLEN = GELD_ROLLEN;

const jetzt = () => new Date().toISOString();

/** Die Obergrenze, wie der Browser sie zu sehen bekommt. */
const DOGEN_MAX_MILLE = centInMille(BETRAG_MAX_CENT);

/* ======================================================================
   EINE ANGABE IN DOGEN WIRD ZU CENT -- AN EINER STELLE

   Jeder Weg, der einen Betrag entgegennimmt, nimmt ihn in
   Tausendsteln Dogen. Dass daraus Cent werden, passiert genau hier.
   Fuenf Wege mit je eigener Umrechnung waeren fuenf Gelegenheiten,
   sich um den Faktor zu vertun -- und der Fehler faellt erst auf,
   wenn er im Bild steht.

   Rueckgabe: die Cent, oder `null`. `null` heisst „nicht brauchbar",
   und der Aufrufer antwortet damit 400.
   ====================================================================== */
function centAusDogen(wert) {
  const mille = Math.round(Number(wert));
  if (!Number.isFinite(mille) || mille <= 0 || mille > DOGEN_MAX_MILLE) return null;
  const cent = milleInCent(mille);
  if (!Number.isFinite(cent) || cent <= 0 || cent > BETRAG_MAX_CENT) return null;
  return cent;
}

/* ======================================================================
   DAS DOGEN-BUCH

   Filipe: „ich will dass die den leuten auch als punkte
   hinzugefuegt werden."
   ====================================================================== */

/** Was jemand hat -- die Summe seiner Buchungen.
 *
 *  KEIN ZAEHLER IRGENDWO DANEBEN. Der Stand IST die Summe; ein
 *  zweiter Wert, der dasselbe behauptet, waere die Gelegenheit, dass
 *  beide auseinanderlaufen. */
export function dogenStand(personId) {
  try {
    const z = db().prepare(`SELECT COALESCE(SUM(mille), 0) AS m
        FROM dogen_buchungen WHERE person_id = ?`).get(Number(personId) || 0);
    return Number(z?.m) || 0;
  } catch { return 0; }
}

/** Die Staende aller -- fuer die Leitung.
 *
 *  Nur wer etwas hat, steht drin. Eine Liste mit lauter Nullen ist
 *  keine Auskunft, sondern eine Personenliste mit Zusatzspalte. */
function dogenStaende(person) {
  try {
    return db().prepare(`SELECT p.id, p.name, p.rolle,
           COALESCE(SUM(b.mille), 0) AS mille
        FROM personen p JOIN dogen_buchungen b ON b.person_id = p.id
       WHERE 1=1 ${hausBedingung(person, "p.rolle")}
       GROUP BY p.id HAVING mille <> 0
       ORDER BY mille DESC, p.name`).all()
      .map((z) => ({ id: z.id, name: z.name, mille: Number(z.mille) || 0 }));
  } catch { return []; }
}

/** Die Dogen einer bestaetigten Spende gutschreiben.
 *
 *  ==== WARUM DAS HIER STEHT UND NICHT AN DEN ZWEI BESTAETIGUNGEN
 *
 *  Es gibt zwei Wege, auf denen eine Spende gueltig wird (die
 *  Leitung traegt sie ein / die Leitung bestaetigt eine Meldung) --
 *  und beide enden in `zeigen()`. Zwei Aufrufe waeren zwei Stellen,
 *  an denen man einen vergessen kann; genau so fehlen Dinge.
 *
 *  DASS ES TROTZDEM NIE DOPPELT GUTSCHREIBT, ENTSCHEIDET DIE
 *  DATENBANK und nicht diese Funktion: `zeigen()` laeuft auch beim
 *  „nochmal zeigen", und ein Strom wird bei einer Stoerung
 *  wiederholt. Der eindeutige Index ueber (spende_id, grund) macht
 *  die zweite Buchung unmoeglich -- eine Bedingung im Programm
 *  haette dieselbe Luecke wie jedes „erst nachsehen, dann
 *  schreiben".
 *
 *  OHNE PERSON KEINE PUNKTE. Eine von Hand eingetragene Spende hat
 *  oft nur einen Namen auf der Karte. Einen Namen einer Person
 *  zuzuordnen hiesse raten, und geratene Punkte sind schlimmer als
 *  keine. Deshalb kann die Leitung beim Eintragen eine Person
 *  auswaehlen -- tut sie es nicht, laeuft die Karte trotzdem, nur
 *  ohne Gutschrift. */
function gutschreiben(z) {
  try {
    if (!z?.id || !z.person_id || z.stand !== "bestaetigt") return;
    const mille = centInMille(z.betrag_cent);
    if (mille <= 0) return;
    const a = db().prepare(`INSERT OR IGNORE INTO dogen_buchungen
        (person_id, mille, grund, spende_id, notiz, erstellt)
        VALUES (?,?,'spende',?,'',?)`)
      .run(z.person_id, mille, z.id, jetzt());

    /* ==== UND DER MENSCH ERFAEHRT ES SOFORT ====================

       Gefunden beim Messen, nicht beim Lesen: Eine Zuschauerin
       bekommt zwar die Karte zu sehen, aber `spendenHolen()` ruft
       bei ihr niemand auf -- das tut nur der Host. Ihr eigener
       Punktestand waere also erst beim naechsten Seitenaufruf
       gewachsen. „Hinzugefuegt werden" heisst sichtbar
       hinzugefuegt.

       NUR AN DIE EINE PERSON. Ein Rundruf an alle traegt eine Zahl
       durch den Saal, die niemanden sonst etwas angeht -- und
       Filipe hat ausdruecklich keine oeffentliche Rangliste
       gewollt. */
    if (a.changes) {
      stromAn([z.person_id], "dogen", { mille: dogenStand(z.person_id) });
    }
  } catch (fehler) {
    /* EINE FEHLENDE GUTSCHRIFT DARF DIE KARTE NICHT AUFHALTEN. Wer
       gespendet hat, soll seine Karte sehen -- die Punkte lassen
       sich nachtragen, der Augenblick nicht. */
    console.error("[dogen] Gutschrift:", fehler?.message);
  }
}

function angemeldet(req, res, next) {
  const p = sitzungLesen(req);
  if (!p) return res.status(401).json({ fehler: "nicht_angemeldet" });
  req.person = p;
  next();
}

/** Spenden gehoeren zum Team-Dogi-Haus.
 *
 *  Dieselbe Form wie bei der Reaction und beim Notizblock: gefragt
 *  wird, ob es das ANDERE Haus ist -- nicht, ob es Crew ist. Auf
 *  einer Pruefadresse hat niemand ein Haus, und „ist nicht crew"
 *  haette die Tuer dort zugemacht. */
function nurTeamDogi(req, res, next) {
  if (req.person?.haus === "agentur") return res.status(404).end();
  next();
}

function nurGeld(req, res, next) {
  if (!GELD_ROLLEN.has(req.person.rolle)) {
    return res.status(403).json({ fehler: "nur_leitung" });
  }
  next();
}

/** Schuetzt gegen fremde Seiten, die im Namen eines Angemeldeten
 *  schreiben. Dieselbe Pruefung wie im Anruf- und Reaktionsteil. */
function gleicheHerkunft(req, res, next) {
  if (req.method === "GET") return next();
  const woher = req.get("Origin") || "";
  if (!woher) return next();
  try {
    if (new URL(woher).host !== req.get("Host")) {
      return res.status(403).json({ fehler: "fremde_herkunft" });
    }
  } catch { return res.status(403).json({ fehler: "fremde_herkunft" }); }
  next();
}

/* ---------- Wer erfaehrt davon? ---------------------------------------
   Alle, die gerade in der Reaction sitzen, plus der Host. Steht
   gerade keine Sendung, gibt es niemanden -- dann wird die Spende
   eingetragen und beim naechsten Mal gezeigt. Eine Karte, die ins
   Leere laeuft, waere schlimmer als eine, die wartet. */
function empfaenger() {
  try {
    const ids = new Set(
      db().prepare("SELECT person_id FROM reaktion_dabei").all().map((z) => z.person_id));
    const s = db().prepare("SELECT host_id FROM reaktion WHERE id = 1").get();
    if (s?.host_id) ids.add(s.host_id);
    return [...ids];
  } catch { return []; }
}

/** Die PayPal-Adresse, wie sie auf der Unterstuetzen-Seite steht. */
function paypalAdresse() {
  try {
    const w = db().prepare(`SELECT ziel, knopf FROM unterstuetzung_wege
        WHERE schluessel = 'paypal' AND sichtbar = 1`).get();
    return w?.ziel ? { ziel: w.ziel, knopf: w.knopf || "" } : null;
  } catch { return null; }
}

/** Haengt einen Betrag an eine PayPal.me-Adresse.
 *
 *  NUR BEI paypal.me. Bei jeder anderen Adresse wird nichts
 *  angehaengt und es gibt auch keine Betragsknoepfe -- ein Betrag an
 *  einer Adresse, die ihn nicht versteht, fuehrt zu einer Seite, auf
 *  der etwas anderes steht als auf dem Knopf. */
export function mitBetrag(ziel, cent, waehrung = "EUR") {
  if (!ziel || !/^https:\/\/(www\.)?paypal\.me\//i.test(ziel)) return null;
  const sauber = ziel.replace(/\/+$/, "");
  const zahl = (cent % 100 === 0) ? String(cent / 100)
    : (cent / 100).toFixed(2);
  return `${sauber}/${zahl}${waehrung}`;
}

/** Welche Stufe gilt fuer diesen Betrag?
 *
 *  DIE HOECHSTE, DIE NOCH PASST. Ohne diese Regel muesste jede Stufe
 *  eine Ober- UND eine Untergrenze haben, und zwei Grenzen je Stufe
 *  sind die doppelte Gelegenheit, eine Luecke zu lassen -- durch die
 *  faellt dann ausgerechnet der grosse Betrag. */
export function stufeFuer(cent) {
  try {
    return db().prepare(`SELECT * FROM spenden_stufen
        WHERE ab_cent <= ? ORDER BY ab_cent DESC LIMIT 1`).get(cent) || null;
  } catch { return null; }
}

function alsKarte(z) {
  const st = stufeFuer(z.betrag_cent);
  return {
    id: z.id,
    /* ==== HIER ENDET DAS GELD ====================================
       Der Browser bekommt Dogen und sonst nichts. Kein
       `betrag_cent`, keine `waehrung` -- auch nicht „nur im JSON,
       sieht ja keiner". Filipe: „es soll auch nie geld da stehen."
       Was nicht gesendet wird, kann an keiner Stelle
       versehentlich erscheinen, und niemand muss daran denken. */
    dogen_mille: centInMille(z.betrag_cent),
    /* DAS ZEICHEN REIST MIT DER KARTE. Es ist fuer alle dasselbe --
       es als zweiten Wert danebenzulegen hiesse, dass jede Stelle,
       die eine Karte zeigt, an zwei Dinge denken muss. Die Karte
       traegt alles, was sie braucht; genau das verspricht
       spendenkarte.js in ihrem Kopf. */
    zeichen: zeichenAdresse(),
    name: z.name,
    gruss: z.gruss,
    herkunft: z.herkunft,
    stand: z.stand,
    erstellt: z.erstellt,
    stufe: st ? {
      name: st.name, vorlage: st.vorlage, bild: bildAdresse(st.bild),
      farbe: st.farbe, dauer_ms: st.dauer_ms,
      groesse: Number(st.groesse) || 1,
    } : null,
  };
}

/** Aus dem Dateinamen wird eine Adresse -- oder nichts.
 *
 *  Die Adresse zeigt auf den Buehnen-Router und NICHT hierher: Die
 *  Spendentafel in OBS hat keine Anmeldung, und an diesem Router
 *  steht eine Schranke ueber allem. */
function bildAdresse(datei) {
  return datei ? `/workspace/api/buehne/spendenbild/${datei}` : "";
}

/** Das Dogen-Zeichen, wenn eines hochgeladen wurde.
 *
 *  Filipe: „die symbole schick ich dir spaeter."
 *
 *  Bis dahin ist die Antwort leer, und die Oberflaeche zeichnet
 *  selbst eine Muenze. Ein Platzhalterbild, das wie eine kaputte
 *  Datei aussieht, waere schlechter als eine saubere Zeichnung. */
function zeichenAdresse() {
  return bildAdresse(einstellung(ZEICHEN_NAME, ""));
}

/** Wen die Leitung einer Spende zuordnen kann.
 *
 *  NUR DAS EIGENE HAUS, und das ist keine Formalie: Die Reaction
 *  gehoert Team Dogi. Eine Auswahlliste, in der Agenturnamen
 *  stehen, waere genau die Vermischung, die seit dem 24.09. nicht
 *  mehr sein darf.
 *
 *  Und nur AKTIVE: Wer nicht mehr dabei ist, soll nicht mehr
 *  versehentlich Punkte bekommen. */
function personenListe(person) {
  try {
    return db().prepare(`SELECT id, name FROM personen
        WHERE aktiv = 1 ${hausBedingung(person)} ORDER BY name`).all();
  } catch { return []; }
}

/** Eine bestaetigte Spende ins Bild schicken. */
function zeigen(z) {
  /* ERST BUCHEN, DANN ZEIGEN. Andersherum liefe die Karte, und wenn
     dabei etwas schiefginge, stuenden die Dogen nicht im Buch --
     sichtbar gedankt und nicht gutgeschrieben ist der aergerlichere
     der beiden moeglichen Fehler. */
  gutschreiben(z);
  db().prepare("UPDATE spenden SET gezeigt_am = ? WHERE id = ?").run(jetzt(), z.id);
  const daten = { was: "zeigen", karte: alsKarte(z) };
  stromAn(empfaenger(), "spende", daten);
  /* Die Karte gehoert auch auf die Buehne -- sonst laeuft sie in der
     Seite und fehlt ausgerechnet im Stream. */
  buehneMelden("spende", daten);
}

/* ======================================================================
   DIE WEGE
   ====================================================================== */
spendenRouter.use("/workspace/api/spenden", angemeldet, nurTeamDogi, gleicheHerkunft);

/** Was die Seite zum Anzeigen braucht. */
spendenRouter.get("/workspace/api/spenden", (req, res) => {
  try {
    const pp = paypalAdresse();
    const darf = GELD_ROLLEN.has(req.person.rolle);
    /* DER EURO ENTSTEHT ERST IN DER ADRESSE. `mitBetrag` braucht
       ihn, weil PayPal ihn braucht -- an den Browser geht nur die
       fertige Adresse und die Zahl in Dogen. */
    const knoepfe = pp
      ? KNOEPFE_MILLE.map((m) => ({ mille: m, ziel: mitBetrag(pp.ziel, milleInCent(m)) }))
        .filter((k) => k.ziel)
      : [];
    res.json({
      paypal: pp ? { ziel: pp.ziel, knopf: pp.knopf } : null,
      knoepfe,
      /* EINE STELLE LIEST DIE STUFEN. Hier stand dieselbe Abfrage
         ein zweites Mal -- und als die Stufen von Cent auf Dogen
         umgestellt wurden, waere genau diese Kopie die stehen
         gebliebene gewesen. */
      stufen: stufenLesen(),
      /* Das Zeichen, das neben jeder Zahl steht. Leer, solange
         keines hochgeladen ist. */
      zeichen: zeichenAdresse(),
      /* WAS SICH EINSTELLEN LAESST, KOMMT VOM SERVER. Stuenden die
         Vorlagennamen und die Grenzen auch in der Oberflaeche, waeren
         es zwei Listen -- und die eine liefe irgendwann von der
         anderen weg. Dann steht dort ein Knopf, den der Server
         ablehnt. */
      gestaltung: {
        vorlagen: VORLAGEN, stufen_max: STUFEN_MAX,
        dauer_min: DAUER_MS_MIN, dauer_max: DAUER_MS_MAX,
        groesse_min: GROESSE_MIN, groesse_max: GROESSE_MAX,
        bild_max_mb: Math.round(BILD_MAX_BYTES / 1024 / 1024),
      },
      /* Die Grenzen fuer die Felder -- in Dogen und in Zeichen. Sie
         kommen vom Server, damit nicht zwei Zahlen dieselbe Frage
         beantworten und eine davon veraltet. */
      dogen_max_mille: DOGEN_MAX_MILLE,
      gruss_max: GRUSS_MAX,
      name_max: NAME_MAX,
      /* WAS ICH SELBST HABE, SEHE ICH IMMER. Das ist Filipes
         „hinzugefuegt werden": Ohne einen sichtbaren Stand waere es
         eine Zahl in einer Datenbank und kein Grund, wiederzukommen. */
      ich: { darf, dogen_mille: dogenStand(req.person.id) },
      /* Die Staende aller und die Namensliste sieht nur die Leitung.
         Fuer alle anderen waere das eine Rangliste darueber, wer
         wie viel gibt -- und wer wenig gibt, staende jeden Abend
         darin. */
      staende: darf ? dogenStaende(req.person) : null,
      personen: darf ? personenListe(req.person) : null,
      /* Die offenen Meldungen sieht nur, wer sie bestaetigen kann.
         Fuer alle anderen waere es eine Liste fremder Geldbetraege. */
      offen: darf
        ? db().prepare("SELECT * FROM spenden WHERE stand = 'offen' ORDER BY id")
          .all().map(alsKarte)
        : null,
      letzte: darf
        ? db().prepare("SELECT * FROM spenden WHERE stand = 'bestaetigt'"
          + " ORDER BY id DESC LIMIT 20").all().map(alsKarte)
        : null,
    });
  } catch (fehler) {
    console.error("[spenden] Lage:", fehler?.message);
    res.status(503).json({ fehler: "nicht_verfuegbar" });
  }
});

/** „Ich habe gespendet." — landet als OFFEN.
 *
 *  BEWUSST OHNE PRUEFUNG DES BETRAGS GEGEN PAYPAL. Wir koennen ihn
 *  nicht kennen (siehe Kopf). Was hier entsteht, ist eine BEHAUPTUNG,
 *  und sie wird auch so behandelt: Sie steht im Pult und wartet. */
spendenRouter.post("/workspace/api/spenden/melden", express.json({ limit: "4kb" }),
  (req, res) => {
    try {
      const cent = centAusDogen(req.body?.dogen_mille);
      if (cent === null) return res.status(400).json({ fehler: "betrag_unklar" });
      /* EINE MELDUNG JE MINUTE UND PERSON. Nicht gegen Betrug -- die
         Leitung bestaetigt ja -- sondern gegen den Doppelklick und
         gegen eine Liste, die man nicht mehr durchsieht. */
      const kurz = new Date(Date.now() - 60_000).toISOString();
      const schon = db().prepare(`SELECT COUNT(*) AS n FROM spenden
          WHERE person_id = ? AND erstellt > ?`).get(req.person.id, kurz);
      if ((schon?.n || 0) >= 1) return res.status(429).json({ fehler: "zu_schnell" });

      /* ==== DER TEXT KOMMT VON DEM, DER GIBT =====================

         Filipe: „der text der dazu erscheint sollen die leute
         selber schreiben koennen ... es sollen personalisierte
         texte sein von den leuten selbst."

         Bisher schrieb ihn die Leitung ab, wenn ueberhaupt. Jetzt
         steht er da, wo er hingehoert: bei dem, der ihn meint.

         UND ER GEHT TROTZDEM DURCH DIE BESTAETIGUNG. Eine Meldung
         wartet ohnehin auf einen Tipp der Leitung -- der Text laeuft
         damit nie unbesehen ins Bild, und die Leitung kann ihn
         aendern oder leeren, bevor sie bestaetigt. Ohne diese
         Schranke waere ein freies Textfeld, das im Livestream
         erscheint, die offenste Tuer des ganzen Hauses. */
      const name = String(req.body?.name ?? req.person.name).trim().slice(0, NAME_MAX)
        || req.person.name;
      const gruss = String(req.body?.gruss ?? "").trim().slice(0, GRUSS_MAX);
      const { lastInsertRowid } = db().prepare(`INSERT INTO spenden
          (betrag_cent, waehrung, name, gruss, person_id, herkunft, stand, erstellt)
          VALUES (?,?,?,?,?,'gemeldet','offen',?)`)
        .run(cent, "EUR", name, gruss, req.person.id, jetzt());

      const z = db().prepare("SELECT * FROM spenden WHERE id = ?").get(Number(lastInsertRowid));
      /* Die Leitung erfaehrt es sofort -- sonst liegt die Meldung da,
         und der Zuschauer wartet auf eine Karte, die niemand sieht. */
      stromAn(
        db().prepare("SELECT id FROM personen WHERE rolle IN ('admin','hand') AND aktiv = 1")
          .all().map((p) => p.id),
        "spende", { was: "offen", karte: alsKarte(z) },
      );
      res.status(201).json({ ok: true, wartet: true });
    } catch (fehler) {
      console.error("[spenden] Melden:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

/** Die Leitung traegt eine Spende ein — sie gilt sofort. */
spendenRouter.post("/workspace/api/spenden", nurGeld, express.json({ limit: "4kb" }),
  (req, res) => {
    try {
      const cent = centAusDogen(req.body?.dogen_mille);
      if (cent === null) return res.status(400).json({ fehler: "betrag_unklar" });
      const name = String(req.body?.name ?? "").trim().slice(0, NAME_MAX);
      if (!name) return res.status(400).json({ fehler: "name_fehlt" });
      const gruss = String(req.body?.gruss ?? "").trim().slice(0, GRUSS_MAX);

      /* ==== WEM GEHOEREN DIE DOGEN? ==============================

         Freiwillig. Die Leitung traegt eine Spende oft von einem
         Handy-Hinweis ab, auf dem nur ein Vorname steht -- daraus
         eine Person zu RATEN waere schlimmer als keine Punkte zu
         vergeben. Steht niemand da, laeuft die Karte trotzdem.

         Geprueft wird die Person gegen das eigene Haus: Eine
         Kennung aus der Agentur waere eine Gutschrift ueber die
         Hausgrenze hinweg, und genau das darf seit dem 24.09. nicht
         mehr passieren -- auch nicht durch einen Tippfehler in
         einer Zahl. */
      let wem = null;
      if (req.body?.person_id) {
        const p = db().prepare(`SELECT id FROM personen
            WHERE id = ? AND aktiv = 1 ${hausBedingung(req.person)}`)
          .get(Number(req.body.person_id) || 0);
        if (!p) return res.status(400).json({ fehler: "person_unbekannt" });
        wem = p.id;
      }

      const { lastInsertRowid } = db().prepare(`INSERT INTO spenden
          (betrag_cent, waehrung, name, gruss, person_id, herkunft, stand, erstellt,
           bestaetigt_am, bestaetigt_von)
          VALUES (?,?,?,?,?,'hand','bestaetigt',?,?,?)`)
        .run(cent, "EUR", name, gruss, wem, jetzt(), jetzt(), req.person.id);

      const z = db().prepare("SELECT * FROM spenden WHERE id = ?").get(Number(lastInsertRowid));
      protokolliere("spende_hand", {
        personId: req.person.id,
        /* AUCH IM PROTOKOLL KEIN GELD. Es ist eine Liste, die im
           Haus gelesen wird -- und „nie" heisst nie. Die Cent
           stehen ohnehin in der Spendenzeile selbst, dort gehoeren
           sie hin. */
        detail: `${centInMille(cent)} Tausendstel Dogen von ${name}`,
        ip: echteIp(req),
      });
      zeigen(z);
      res.status(201).json(alsKarte(z));
    } catch (fehler) {
      console.error("[spenden] Eintragen:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

/** Eine gemeldete Spende bestaetigen — dann geht sie ins Bild. */
spendenRouter.post("/workspace/api/spenden/:id(\\d+)/bestaetigen", nurGeld,
  express.json({ limit: "4kb" }), (req, res) => {
    try {
      const z = db().prepare("SELECT * FROM spenden WHERE id = ?").get(Number(req.params.id));
      if (!z) return res.status(404).json({ fehler: "nicht_gefunden" });
      /* SCHON BESTAETIGT IST KEIN FEHLER, ABER AUCH KEIN GRUND, ES
         NOCH EINMAL ZU ZEIGEN. Zwei Leute tippen gleichzeitig, und
         die Karte liefe zweimal. */
      if (z.stand === "bestaetigt") return res.json(alsKarte(z));

      /* Beim Bestaetigen darf der Betrag berichtigt werden: Die
         Leitung hat die Zahlungsmeldung vor sich und weiss es
         besser als die Behauptung. */
      let cent = z.betrag_cent;
      if (req.body?.dogen_mille !== undefined) {
        cent = centAusDogen(req.body.dogen_mille);
        if (cent === null) return res.status(400).json({ fehler: "betrag_unklar" });
      }

      /* ==== UND DER TEXT DARF BERICHTIGT WERDEN ==================
         Das ist die Schranke vor dem Stream. Der Gruss kommt jetzt
         von dem, der gibt -- die Leitung sieht ihn hier zum ersten
         Mal und entscheidet, ob er so ins Bild geht. Ohne diese
         Moeglichkeit bliebe nur „ganz ablehnen", und dann faellt
         wegen eines Wortes eine echte Spende unter den Tisch. */
      const name = req.body?.name === undefined
        ? z.name : (String(req.body.name).trim().slice(0, NAME_MAX) || z.name);
      const gruss = req.body?.gruss === undefined
        ? z.gruss : String(req.body.gruss).trim().slice(0, GRUSS_MAX);

      db().prepare(`UPDATE spenden SET stand = 'bestaetigt', betrag_cent = ?,
          name = ?, gruss = ?, bestaetigt_am = ?, bestaetigt_von = ? WHERE id = ?`)
        .run(cent, name, gruss, jetzt(), req.person.id, z.id);
      const neu = db().prepare("SELECT * FROM spenden WHERE id = ?").get(z.id);
      protokolliere("spende_bestaetigt", {
        personId: req.person.id,
        detail: `#${z.id}, ${centInMille(cent)} Tausendstel Dogen`,
        ip: echteIp(req),
      });
      zeigen(neu);
      res.json(alsKarte(neu));
    } catch (fehler) {
      console.error("[spenden] Bestaetigen:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

spendenRouter.post("/workspace/api/spenden/:id(\\d+)/ablehnen", nurGeld, (req, res) => {
  try {
    const n = db().prepare(`UPDATE spenden SET stand = 'abgelehnt',
        bestaetigt_am = ?, bestaetigt_von = ? WHERE id = ? AND stand = 'offen'`)
      .run(jetzt(), req.person.id, Number(req.params.id));
    if (!n.changes) return res.status(409).json({ fehler: "nicht_offen" });
    res.json({ ok: true });
  } catch (fehler) {
    console.error("[spenden] Ablehnen:", fehler?.message);
    res.status(503).json({ fehler: "nicht_verfuegbar" });
  }
});

/** Dieselbe Karte noch einmal zeigen — fuer den Fall, dass sie
 *  jemand verpasst hat oder die Technik im falschen Moment hakte. */
/* ======================================================================
   DIE GESTALTUNG

   Filipe: „mach paar fertige und so dass ich auch hochladen kann.
   auch so dass ich das anders gestalten kann oder die groesse
   veraendern kann. ... auch spezielle sachen bei speziellen spenden."

   DIE GANZE LEITER AUF EINMAL UND NICHT ZEILE FUER ZEILE. Eine
   Stufenleiter ist keine Liste unabhaengiger Zeilen -- sie muss als
   Ganzes stimmen: aufsteigende Grenzen, keine zwei mit demselben
   Betrag, mindestens eine. Wer einzeln speichert, geht durch
   Zwischenzustaende, in denen sie das nicht tut, und waehrend einer
   Sendung faellt dann eine Spende in die falsche Stufe.
   ====================================================================== */
spendenRouter.put("/workspace/api/spenden/stufen", nurGeld,
  express.json({ limit: "16kb" }), (req, res) => {
    try {
      const roh = Array.isArray(req.body?.stufen) ? req.body.stufen : null;
      if (!roh) return res.status(400).json({ fehler: "stufen_fehlen" });
      if (!roh.length) return res.status(400).json({ fehler: "keine_stufe" });
      if (roh.length > STUFEN_MAX) return res.status(400).json({ fehler: "zu_viele_stufen" });

      const sauber = [];
      for (const z of roh) {
        const ab = centAusDogen(z?.ab_mille);
        if (ab === null) return res.status(400).json({ fehler: "stufe_betrag_unklar" });
        const name = String(z?.name ?? "").trim().slice(0, NAME_MAX);
        if (!name) return res.status(400).json({ fehler: "stufe_name_fehlt" });

        const vorlage = String(z?.vorlage ?? "herz");
        if (!VORLAGEN.includes(vorlage)) {
          return res.status(400).json({ fehler: "vorlage_unbekannt" });
        }
        /* NUR ECHTE FARBWERTE. Ein freier Text landete als CSS-Wert
           in der Karte -- das ist genau die Stelle, an der aus einer
           Einstellung eine Einschleusung wird. */
        const farbe = String(z?.farbe ?? "").trim();
        if (!/^#[0-9a-fA-F]{6}$/.test(farbe)) {
          return res.status(400).json({ fehler: "farbe_unklar" });
        }
        const dauer = Math.round(Number(z?.dauer_ms));
        if (!Number.isFinite(dauer) || dauer < DAUER_MS_MIN || dauer > DAUER_MS_MAX) {
          return res.status(400).json({ fehler: "dauer_unklar" });
        }
        const groesse = Number(z?.groesse);
        if (!Number.isFinite(groesse) || groesse < GROESSE_MIN || groesse > GROESSE_MAX) {
          return res.status(400).json({ fehler: "groesse_unklar" });
        }
        sauber.push({ ab, name, vorlage, farbe, dauer, groesse, id: Number(z?.id) || 0 });
      }

      sauber.sort((a, b2) => a.ab - b2.ab);
      for (let i = 1; i < sauber.length; i++) {
        if (sauber[i].ab === sauber[i - 1].ab) {
          return res.status(409).json({ fehler: "stufe_doppelt" });
        }
      }

      /* ==== DIE KENNUNGEN MUESSEN DAS SPEICHERN UEBERLEBEN =======

         Der erste Bau hat hier `DELETE` und dann `INSERT` gemacht.
         Das Ergebnis war richtig -- und trotzdem falsch: Jede Stufe
         bekam dabei eine NEUE Kennung. Gemessen ist das in der
         Pruefung aufgefallen, als ein Bild-Hochladen gegen die eben
         noch gueltige Kennung mit 404 antwortete.

         Im Alltag heisst das: Wer die Leiter speichert und dann auf
         „Bild hochladen" drueckt, ohne dass die Seite dazwischen neu
         gezeichnet wurde, greift ins Leere. Und ein zweiter offener
         Bildschirm greift IMMER ins Leere.

         Also: vorhandene Zeilen AENDERN, neue anlegen, entfernte
         loeschen. Dann bleibt die Kennung, und das Bild bleibt von
         selbst daran haengen -- ohne eine Landkarte, die man pflegen
         muesste. */
      const vorhanden = db().prepare("SELECT id, bild FROM spenden_stufen").all();
      const kenneIch = new Set(vorhanden.map((z) => z.id));
      const behalten = new Set();

      /* EIN SCHREIBVORGANG. `node:sqlite` kennt kein `.transaction()`,
         also von Hand -- ein Abbruch mittendrin haette eine Leiter
         zurueckgelassen, die halb die alte und halb die neue ist. */
      db().exec("BEGIN IMMEDIATE");
      try {
        /* ==== DREI SCHRITTE, UND DIE REIHENFOLGE IST DER PUNKT ====

           `ab_cent` ist EINDEUTIG. Wer die Zeilen einfach der Reihe
           nach umschreibt, stoesst mitten im Vorgang auf sich
           selbst: Die 500er-Stufe auf 100 zu setzen scheitert,
           solange die alte 100er noch dasteht -- obwohl das ERGEBNIS
           voellig in Ordnung waere. Gemessen ist genau das passiert:
           „UNIQUE constraint failed: spenden_stufen.ab_cent", und
           der ganze Vorgang brach ab.

           Also erst alles aus dem Weg raeumen: Was weg soll, wird
           geloescht; was bleibt, wandert kurz auf einen Betrag, den
           niemand sonst hat (eine Milliarde plus die eigene
           Kennung). Danach kann jede Zeile ihren endgueltigen Wert
           bekommen, ohne einer anderen in die Quere zu kommen.

           Das ist nur INNERHALB des Schreibvorgangs sichtbar -- nach
           aussen gibt es diesen Zwischenzustand nie. */
        for (const z of vorhanden) {
          const bleibt = sauber.some((n) => n.id === z.id);
          if (!bleibt) db().prepare("DELETE FROM spenden_stufen WHERE id = ?").run(z.id);
          else {
            db().prepare("UPDATE spenden_stufen SET ab_cent = ? WHERE id = ?")
              .run(1000000000 + z.id, z.id);
          }
        }

        const aendern = db().prepare(`UPDATE spenden_stufen SET
            ab_cent = ?, name = ?, vorlage = ?, farbe = ?, dauer_ms = ?,
            groesse = ?, geaendert = ? WHERE id = ?`);
        const ein = db().prepare(`INSERT INTO spenden_stufen
            (ab_cent, name, vorlage, bild, farbe, dauer_ms, groesse, geaendert)
            VALUES (?,?,?,'',?,?,?,?)`);
        for (const z of sauber) {
          if (z.id && kenneIch.has(z.id)) {
            aendern.run(z.ab, z.name, z.vorlage, z.farbe, z.dauer, z.groesse, jetzt(), z.id);
            behalten.add(z.id);
          } else {
            const { lastInsertRowid } = ein.run(
              z.ab, z.name, z.vorlage, z.farbe, z.dauer, z.groesse, jetzt());
            behalten.add(Number(lastInsertRowid));
          }
        }
        db().exec("COMMIT");
      } catch (f) {
        db().exec("ROLLBACK");
        throw f;
      }

      /* WAS AN BILDERN UEBRIG BLEIBT, WIRD WEGGERAEUMT. Sonst
         sammelt sich bei jeder geloeschten Stufe eine Datei an, die
         niemand mehr findet und niemand mehr loescht. */
      for (const z of vorhanden) {
        if (z.bild && !behalten.has(z.id)) {
          try { unlinkSync(join(BILDER, z.bild)); } catch { /* war schon weg */ }
        }
      }

      protokolliere("spenden_stufen", {
        personId: req.person.id,
        detail: `${sauber.length} Stufen gespeichert`,
        ip: echteIp(req),
      });
      res.json({ ok: true, stufen: stufenLesen() });
    } catch (fehler) {
      console.error("[spenden] Stufen:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

function stufenLesen() {
  return db().prepare("SELECT id, ab_cent, name, vorlage, bild, farbe, dauer_ms,"
    + " groesse FROM spenden_stufen ORDER BY ab_cent").all()
    .map((z) => ({
      id: z.id,
      /* AUCH DIE GRENZE IST EINE ZAHL IN DOGEN. `ab_cent` bleibt der
         Name in der Datenbank -- dort ist es die Ablage, und eine
         Spalte umzubenennen heisst, eine Tabelle neu zu bauen; genau
         dabei sind am 11.09. drei Spalten verlorengegangen. Nach
         aussen geht nur `ab_mille`. */
      ab_mille: centInMille(z.ab_cent),
      name: z.name, vorlage: z.vorlage, bild: bildAdresse(z.bild),
      farbe: z.farbe, dauer_ms: z.dauer_ms,
      groesse: Number(z.groesse) || 1,
    }));
}

/** Woran man ein Bild erkennt -- an seinem Inhalt und nicht an seinem
 *  Namen. Eine Datei „katze.png", die etwas anderes enthaelt, waere
 *  sonst ein Bild, das der Browser als etwas anderes liest. */
function bildart(puffer) {
  if (!puffer || puffer.length < 12) return null;
  if (puffer[0] === 0xff && puffer[1] === 0xd8 && puffer[2] === 0xff) return "jpg";
  if (puffer[0] === 0x89 && puffer[1] === 0x50 && puffer[2] === 0x4e && puffer[3] === 0x47) {
    return "png";
  }
  if (puffer.toString("ascii", 0, 4) === "RIFF" && puffer.toString("ascii", 8, 12) === "WEBP") {
    return "webp";
  }
  return null;
}

/* Ein zu grosses Bild ist kein Serverfehler, sondern eine ganz
   normale Eingabe -- und der Absender soll erfahren, WAS zu tun ist.
   Ohne diese Stelle laeuft der Fehler von express.raw() bis in die
   allgemeine Behandlung durch und kommt als „500 Serverfehler" an. */
function zuGross(fehler, req, res, next) {
  if (fehler?.type === "entity.too.large") {
    return res.status(413).json({ fehler: "bild_zu_gross" });
  }
  return next(fehler);
}

spendenRouter.post("/workspace/api/spenden/stufe/:id(\\d+)/bild", nurGeld,
  express.raw({ type: "*/*", limit: BILD_MAX_BYTES }), zuGross, (req, res) => {
    try {
      const id = Number(req.params.id);
      const stufe = db().prepare("SELECT id, bild FROM spenden_stufen WHERE id = ?").get(id);
      if (!stufe) return res.status(404).json({ fehler: "nicht_gefunden" });

      const endung = bildart(req.body);
      if (!endung) return res.status(400).json({ fehler: "kein_bild" });

      mkdirSync(BILDER, { recursive: true });
      const name = `${randomBytes(16).toString("hex")}.${endung}`;
      writeFileSync(join(BILDER, name), req.body);

      db().prepare("UPDATE spenden_stufen SET bild = ?, geaendert = ? WHERE id = ?")
        .run(name, jetzt(), id);
      /* Das alte wegraeumen -- sonst bleibt bei jedem Wechsel eine
         Datei liegen, die niemand mehr findet. */
      if (stufe.bild && stufe.bild !== name) {
        try { unlinkSync(join(BILDER, stufe.bild)); } catch { /* war schon weg */ }
      }
      protokolliere("spenden_bild", {
        personId: req.person.id,
        detail: `Stufe ${id}, ${Math.round(req.body.length / 1024)} KB`,
        ip: echteIp(req),
      });
      res.json({ ok: true, bild: bildAdresse(name), stufen: stufenLesen() });
    } catch (fehler) {
      console.error("[spenden] Bild:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

/* ======================================================================
   DAS DOGEN-ZEICHEN

   Filipe: „die dogen auch mit dem symbol, die symbole schick ich dir
   spaeter. bereite jetzt alles vor."

   EIN BILD IN DEN EINSTELLUNGEN UND NICHT IM QUELLTEXT. Laege es als
   Datei im Verzeichnis, haenge jedes neue Symbol an einem Deploy --
   also an mir. So laedt Filipe es selbst hoch, und zwar an derselben
   Stelle und mit derselben Pruefung wie die Stufenbilder: Die Art
   wird am INHALT erkannt, nicht am Dateinamen.

   ES LIEGT BEI DEN STUFENBILDERN, und das hat einen Grund: Die
   Spendentafel in OBS hat keine Anmeldung, und der Weg
   `/workspace/api/buehne/spendenbild/…` ist der einzige, der Bilder
   ohne Schranke ausliefert. Ein Zeichen, das nur angemeldet
   sichtbar waere, fehlte ausgerechnet im Stream.
   ====================================================================== */
spendenRouter.post("/workspace/api/spenden/zeichen", nurGeld,
  express.raw({ type: "*/*", limit: BILD_MAX_BYTES }), zuGross, (req, res) => {
    try {
      const endung = bildart(req.body);
      if (!endung) return res.status(400).json({ fehler: "kein_bild" });

      mkdirSync(BILDER, { recursive: true });
      const name = `${randomBytes(16).toString("hex")}.${endung}`;
      writeFileSync(join(BILDER, name), req.body);

      const alt = einstellung(ZEICHEN_NAME, "");
      einstellungSetzen(ZEICHEN_NAME, name, req.person);
      /* Das alte wegraeumen -- sonst bleibt bei jedem Wechsel eine
         Datei liegen, die niemand mehr findet. */
      if (alt && alt !== name) {
        try { unlinkSync(join(BILDER, alt)); } catch { /* war schon weg */ }
      }
      protokolliere("dogen_zeichen", {
        personId: req.person.id,
        detail: `${Math.round(req.body.length / 1024)} KB`,
        ip: echteIp(req),
      });
      res.json({ ok: true, zeichen: zeichenAdresse() });
    } catch (fehler) {
      console.error("[spenden] Zeichen:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

spendenRouter.delete("/workspace/api/spenden/zeichen", nurGeld, (req, res) => {
  try {
    const alt = einstellung(ZEICHEN_NAME, "");
    einstellungSetzen(ZEICHEN_NAME, "", req.person);
    if (alt) { try { unlinkSync(join(BILDER, alt)); } catch { /* war weg */ } }
    res.json({ ok: true, zeichen: "" });
  } catch (fehler) {
    console.error("[spenden] Zeichen loeschen:", fehler?.message);
    res.status(503).json({ fehler: "nicht_verfuegbar" });
  }
});

spendenRouter.delete("/workspace/api/spenden/stufe/:id(\\d+)/bild", nurGeld, (req, res) => {
  try {
    const id = Number(req.params.id);
    const stufe = db().prepare("SELECT id, bild FROM spenden_stufen WHERE id = ?").get(id);
    if (!stufe) return res.status(404).json({ fehler: "nicht_gefunden" });
    db().prepare("UPDATE spenden_stufen SET bild = '', geaendert = ? WHERE id = ?")
      .run(jetzt(), id);
    if (stufe.bild) { try { unlinkSync(join(BILDER, stufe.bild)); } catch { /* war weg */ } }
    res.json({ ok: true, stufen: stufenLesen() });
  } catch (fehler) {
    console.error("[spenden] Bild loeschen:", fehler?.message);
    res.status(503).json({ fehler: "nicht_verfuegbar" });
  }
});

/** Einmal ansehen, wie es aussieht -- OHNE eine Spende anzulegen.
 *
 *  ==== DAS IST DER GANZE PUNKT DIESER ROUTE ==========================
 *
 *  Wer eine Stufe gestaltet, will sehen, was herauskommt. Der
 *  naheliegende Weg waere, eine Spende von Hand einzutragen und
 *  danach zu loeschen -- und genau das ist verboten: In ein laufendes
 *  System kommen keine Testdaten. „Storniert heisst nicht weg"; der
 *  Eintrag stuende trotzdem im Verlauf, in der Summe und in der
 *  Aufbewahrung, und bei Geld ist das nicht nur unordentlich.
 *
 *  Diese Route schreibt deshalb NICHTS. Sie baut eine Karte aus den
 *  aktuellen Stufen und schickt sie los. Und sie geht NUR an den,
 *  der drueckt -- eine Probe, die im ganzen Saal erscheint, waere
 *  eine Spende, die es nicht gab. */
spendenRouter.post("/workspace/api/spenden/probe", nurGeld,
  express.json({ limit: "2kb" }), (req, res) => {
    try {
      const cent = centAusDogen(req.body?.dogen_mille);
      if (cent === null) return res.status(400).json({ fehler: "betrag_unklar" });
      const st = stufeFuer(cent);
      const karte = {
        id: 0,
        dogen_mille: centInMille(cent),
        zeichen: zeichenAdresse(),
        /* KENNTLICH ALS PROBE. Stuende hier ein Name, waere auf dem
           Bildschirmfoto nicht mehr zu unterscheiden, ob jemand
           gespendet hat. */
        name: "Probe",
        gruss: "So sieht es aus",
        herkunft: "hand",
        stand: "probe",
        erstellt: jetzt(),
        stufe: st ? {
          name: st.name, vorlage: st.vorlage, bild: bildAdresse(st.bild),
          farbe: st.farbe, dauer_ms: st.dauer_ms, groesse: Number(st.groesse) || 1,
        } : null,
      };
      stromAn([req.person.id], "spende", { was: "zeigen", karte });
      res.json({ ok: true, karte });
    } catch (fehler) {
      console.error("[spenden] Probe:", fehler?.message);
      res.status(503).json({ fehler: "nicht_verfuegbar" });
    }
  });

spendenRouter.post("/workspace/api/spenden/:id(\\d+)/nochmal", nurGeld, (req, res) => {
  try {
    const z = db().prepare("SELECT * FROM spenden WHERE id = ? AND stand = 'bestaetigt'")
      .get(Number(req.params.id));
    if (!z) return res.status(404).json({ fehler: "nicht_gefunden" });
    zeigen(z);
    res.json({ ok: true });
  } catch (fehler) {
    console.error("[spenden] Nochmal:", fehler?.message);
    res.status(503).json({ fehler: "nicht_verfuegbar" });
  }
});

/** Aufraeumen: alte Spenden fallen aus dem Verlauf. */
export function spendenAufraeumen() {
  try {
    const grenze = new Date(Date.now() - SPENDEN_TAGE * 86400_000).toISOString();
    const a = db().prepare("DELETE FROM spenden WHERE erstellt < ?").run(grenze);
    if (a.changes) console.log(`[spenden] Aufgeraeumt: ${a.changes} Zeilen.`);
  } catch (fehler) {
    console.error("[spenden] Aufraeumen:", fehler?.message);
  }
}