Webklar-Kundenbereich/docs/superpowers/plans/2026-10-02-terminplaner-tp1-kern.md

# Terminplaner TP1 Kern – Umsetzungsplan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Gäste buchen auf der Website eines Betriebs Termine (Person oder Platz, sofort oder als Anfrage, Bestätigung per E-Mail-Link, Absagen/Verschieben/Widerrufen per Link); der Betrieb verwaltet alles im Portal; Pilot mit dem Kunden „test“.

**Architecture:** Neue Funktion `termine` im Kundenportal (Express, Appwrite, vanilla JS). Reine Bausteine in `server/services/termine/` (Zeit, Feiertage, Einstellungen, Slots, Zellen gegen Doppelbuchung, ICS, Mails, Warteschlange, Ablauf, Jobs), dazu eine öffentliche, versionierte Schnittstelle `/api/public/termine/v1`, eine Kunden-Schnittstelle `/api/termine`, ein Einbau-Skript `embed/termine.js`, Gästeseiten `termin.html` und die Portal-Ansicht `#termine`. WOMS bekommt Aktivieren/Abschalten je Funktion.

**Tech Stack:** Node 20 (Produktion) / 24 (Host-Tests), Express 4, Appwrite 1.8.1 REST, nodemailer 9, `feiertagejs` 1.5.1 (neu), Playwright (`/root/.npm/_npx/db89d7302a373f10/node_modules/playwright-core/index.mjs`, Chromium `~/.cache/ms-playwright/chromium-1234`), React 18 (WOMS).

**Spec:** `docs/superpowers/specs/2026-10-02-terminplaner-design.md` (Abschnitte „TP1 Kern“ 1–14). Recherche: `/root/reports/terminplaner-2026-10-02/`.

**Worktrees:** Portal `/home/webklar/apps/kundenbereich.webklar.com/dev-termine` (Branch `feature/terminplaner` von `origin/main` ff7fe35, eigenes `node_modules` per `npm ci`, Basis 1463 Tests grün). WOMS siehe V3 und Task 22.

## Global Constraints

- Funktionsschlüssel `termine`; Schalter `TERMINE_ENABLED` = `off` (Vorgabe) | `pilot` | `on`; `TERMINE_PILOT_EMAILS` Komma-Liste (klein, getrimmt, `*` = alle). TP1: `on` = `pilot` ohne E-Mail-Filter; kein Bestellen. Bei `off` laufen keine Termine-Jobs und keine Termine-Abfragen.
- `config.termine` wird bei **jedem** Aufruf gelesen (Tests ändern `config.termine.*` zur Laufzeit). Werte: `mode`, `pilotEmails`, `holdMinutes: 30`, `zelleMin: 5`, `mailsProStunde: 200`, `formMinSekunden: 3` (Env `TERMINE_FORM_MIN_SECONDS`).
- Neue Dateien unter `server/services/termine/`; nie `server/services/appointments.js` (Test `adminPanelGone`).
- Einstellungs-Attribut heißt **`einstellung`** (nie `data`: `appwriteAdmin.formatRequestBody` hält Bodies mit `data` für fertig verpackt).
- Zeit: Wanduhr `Europe/Berlin`, gespeichert UTC (`toISOString()`); Appwrite liefert `+00:00` ⇒ Datumswerte immer mit `new Date()` lesen. Nicht existierende Wanduhrzeiten (März) auslassen, doppelte (Oktober) = erstes Vorkommen. Alle `HH:MM` in Plänen, Sonderöffnungen, Abwesenheiten und Sperren sind Vielfache von 5 Minuten. `deadlines.berlinTime` nicht verwenden.
- Zellen à **5 Minuten**, Zell-ID `c_` + 34 Hex von `sha1(featureId|ressourceId|zelleIso)`, Feld `bis` = `blockEndsAt` der Buchung (nie Haltezeit). Alle neuen Zellen einer Buchung in **einem** Bulk-Create (≤ 100 ⇒ jede Belegung ≤ 500 Minuten, auch Sperren und manuelle Termine). Ob eine Zelle noch gilt, entscheidet allein ihre Buchung (fehlt ⇒ frei; Status nicht belegend ⇒ frei; `gehalten` mit `heldUntil ≤ now` ⇒ frei).
- Status: `gehalten`, `angefragt`, `bestaetigt`, `erledigt`, `nichterschienen`, `abgesagt`, `abgelehnt`, `verfallen`. Belegend: `gehalten` (solange `heldUntil > now`), `angefragt`, `bestaetigt`.
- Tokens: **Bestätigungstoken** = 32 Zufallsbytes base64url, gespeichert nur `verifyHash` (SHA-256-Hex), wirksam einmal bis `heldUntil`. **Verwaltungstoken** = base64url(HMAC-SHA256(Schlüssel aus `config.sessionSecret` + `'termine-manage'`, bookingId)), gespeichert nur `manageHash`, jederzeit neu berechenbar, gültig bis Terminende + 1 Tag. Zustandsänderungen nur per POST. Vertragsschluss `vertragAt` = `bestaetigtAt` (sofort) bzw. `angenommenAt` (Anfrage).
- Knopftexte exakt: verbindlich + Preis ⇒ „Zahlungspflichtig buchen“ (Bestätigungsseite „Zahlungspflichtig bestätigen“); verbindlich ohne Preis ⇒ „Termin buchen“ („Termin bestätigen“); Anfrage ⇒ „Termin anfragen“ („Anfrage absenden“).
- Zustimmungstexte exakt (Sie-Form, auch bei Du-Betrieben, weil Rechtstext): vorzeitiger Beginn (Pflicht bei verbindlich + Preis + Verbraucher + Terminbeginn ≤ Ende der Widerrufsfrist = deadlines.withdrawalDeadline(jetzt + Haltezeit).endsAt; bei bepreisten Verbraucher-Anfragen immer — Ruling R31): „Ich verlange ausdrücklich, dass {Betrieb} mit der Leistung vor Ablauf der Widerrufsfrist beginnt. Mir ist bekannt, dass mein Widerrufsrecht mit der vollständigen Erbringung der Leistung erlischt (§ 356 Abs. 5 Nr. 2 BGB). Widerrufe ich vor der vollständigen Erbringung, schulde ich einen angemessenen Betrag für die bis dahin erbrachte Leistung (§ 357a Abs. 2 BGB).“ · Storno: „Ich habe die Stornobedingungen gelesen.“ · Erinnerung (nie vorangekreuzt): „Ich möchte {n} Stunden vor dem Termin eine Erinnerung per E-Mail erhalten.“ · über Freitext: „Bitte keine Gesundheitsangaben.“
- Verbraucher-Buchung ⇔ `recht.gaesteSind !== 'unternehmer' && !recht.freizeit` (beim Halten in `verbraucher` gespeichert). Widerruf möglich ⇔ verbindlich, `verbraucher`, Status `bestaetigt`, `now <= deadlines.withdrawalDeadline(vertragAt).endsAt` (§§ 187/188/193 BGB, Ruling R29), Termin noch nicht begonnen.
- Öffentliche Antworten: nie `customerId`, `projectId`, `featureId`, `$id`, Ticket-/Stripe-IDs; nur Leistungs-/Ressourcen-IDs der Einstellung und die Buchungsnummer (8 Zeichen). Fehlerform immer `{ fehler: { <feld|_>: text }, code? }`. Unbekannter, inaktiver, abgeschalteter siteKey oder Modus `off` ⇒ `200 { aktiv: false }` (GET und POST unter `/:siteKey`); `/termin/*` (Token) bleibt für `disabled` nutzbar (Absagen, Widerruf).
- Schutz: Router-eigener Parser 16 KB + Router-Fehlermiddleware (413/400/503, nie `err.message`); `content-length` > 16 384 ⇒ 413 vorab; Honeypot-Feld `kontakt_url`; Formular-Token HMAC, `zu_schnell` (< `formMinSekunden`) oder Honeypot ⇒ gleiche Erfolgsantwort ohne Speichern/Mail, `abgelaufen` (> 2 h) ⇒ 400 „Bitte laden Sie die Seite neu.“; Grenzen (Modul `limits.js`, Speicher-Maps mit Obergrenze 10 000 Schlüssel, `resetTermineLimitsForTests()`): je IP (IPv6 je /64) 120 GET/min und 10 Buchungen/10 min; je siteKey 600 GET/min und 60 Haltungen/h; je E-Mail+Funktion `regeln.maxOffeneJeEmail` (Vorgabe 3) offene Termine und 5 G01/Tag; Widerruf 10/h je IP, 3 G08/Tag je Empfängeradresse, 20 G08/h je Funktion, 10 K21 „nicht zugeordnet“/h je Funktion. Grenze „offene Termine“ ⇒ dieselbe 201-Antwort, statt der Bestätigung geht G01-Block `zu_viele` an die Adresse (kein Orakel für Dritte). E-Mail-Adressen: genau ein Postfach (kein `,;<>"`, ≤ 254), getrimmt und klein.
- Mails: Gast `from: { name: betrieb.name, address: SMTP_FROM }`, `replyTo` = Betriebs-E-Mail; K20/K21 `from: { name: 'WEBklar', address }` an die Betriebs-E-Mail; **nie BCC**, kein Tracking. Betreff = Platzhalter `{{betreff}}` (je Anrede/Fall vom Server). G01 und G08 ohne Text, den der Gast eingegeben hat. Alles über `termineOutbox`: einziger Sendepfad `sendeEintrag` prüft Pause und Stundenbudget (200/h); `EAUTH`/535 ⇒ 15 min Pause für alle, Eintrag bleibt `wartet`; Verbindungsfehler/4xx ⇒ erneut nach 1, 5, 30 min, dann `fehler`; 5xx (außer 535) ⇒ sofort `fehler`; nach `gesendet` werden `an`, `html`, `text`, `ics` geleert; Einträge 7 Tage nach `gesendet` bzw. 48 h nach `fehler` gelöscht.
- Löschfristen: `verfallen` 48 h nach `heldUntil`; `abgesagt`/`abgelehnt` 30 Tage; `erledigt`/`nichterschienen` `aufbewahrungTage` (Vorgabe 90, 14–365) nach Terminende; `angefragt` mit Beginn in der Vergangenheit ⇒ `abgelehnt` (System); Funktion `disabled` ⇒ alles 30 Tage nach `disabledAt`.
- Tests: Termine-Tests starten den Nachbau mit `startAppwriteMock({ schema, datetimes, defaultLimit: 25 })` (Task 2); feste `now` per Parameter; Mails mit `mailSink()` + `warteAufVersand()` prüfen; Kalenderdaten stehen im Sink als `icalEvent` (nicht als Anhang). Schwere Läufe (Playwright, `vite build`, Docker-Node-20) nacheinander, vorher `free -m`, mit `nice`.
- Portaltexte Du-Form, kein `confirm()`; Gästetexte Sie/Du nach `anrede`. Kundentext nur über `textContent`/`esc()`; `href` nur für geprüfte `https:`-URLs, mit `rel="noopener noreferrer"`.
- Nichts pushen, nichts in Produktion schreiben (Ausnahme Vorab-Spike mit Freigabe). Nie `git add -A`.

## Review Focus

1. Gast-Browser in anderer Zeitzone (New York) sieht dieselben Daten und Uhrzeiten wie in Berlin; das Widget rechnet nie mit Browser-Datum. → Task 19 (Playwright `timezoneId`, statischer Test)
2. E-Mail mit Großbuchstaben/Leerzeichen (`  Max@GMail.com `) zählt als dieselbe Adresse für Grenzen und Widerruf. → Task 12 (`email_normalisiert`)
3. Betrieb löscht Leistung/Ressource mit künftigen Terminen ⇒ abgelehnt mit Anzahl; Deaktivieren erlaubt, Termine bleiben. → Task 4 + 18
4. Bestätigungsklick genau während der Minutenjob die Haltung verfallen lässt ⇒ genau ein Endzustand. → Task 15 (`verfall_und_bestaetigung_gleichzeitig`)
5. Zwei Widgets auf einer Seite (`data-leistung`) stören sich nicht (IDs, Stile einmal). → Task 19

---

## Vorab (Controller, kein Subagent)

- [ ] **V1 Spike Bulk-Create** (Nutzer-Freigabe einholen): im Container (`docker exec -w /app webklar-kundenbereich-server node …`, Skript im Scratchpad) Wegwerf-Collection `termineSpike` (`bookingId` string 64), 50 parallele `POST …/collections/termineSpike/documents` mit `{ documents: [{ $id, bookingId }, …] }` (je 20 Zellen, Überlappungen) ⇒ je überlappender Gruppe genau ein 201, Rest 409 `document_already_exists`, keine Teil-Schreibungen; Collection löschen. Negativ ⇒ Task 2 baut `createDocuments` über die Transactions-API (`POST /databases/transactions`, Operationen, `PATCH {commit:true}`, 409 `transaction_conflict`).
- [ ] **V2 Gesetzestexte:** Anlage 1 und 2 zu Art. 246a § 1 EGBGB von `https://www.gesetze-im-internet.de/bgbeg/anlage_1.html` und `…/anlage_2.html` wörtlich nach `docs/rechtliches/quellen/anlage-1.txt` und `anlage-2.txt` (Kopfzeile mit Abrufdatum).
- [ ] **V3 WOMS-Worktree:** `git -C /home/webklar/apps/ticket.webklar.com/build worktree add -b feature/terminplaner ../dev-termine origin/test`, dort `git ls-files -z node_modules | xargs -0 git update-index --skip-worktree` und `npm install` (nie `git add -A`).

---

## Portal: Grundlagen

### Task 1: Schalter, Konfiguration, Schema
**Files:** Modify `server/config.js`, `test/support/schema.js`; Create `server/services/termine/schalter.js`, `server/services/termine/schema.js`, `scripts/termine-setup.mjs`, `test/termineSetup.test.js`, `test/termineSchalter.test.js`.
**Produces:**
- `config.collections.termineConfig|termineBookings|termineClaims|termineOutbox` (Env `APPWRITE_COLLECTION_TERMINE_CONFIG|…_BOOKINGS|…_CLAIMS|…_OUTBOX`); `config.termine` laut Global Constraints.
- `schalter.js`: `termineModus()`, `termineFuerKunde(email) ⇒ boolean`, `termineAus() ⇒ boolean`.
- `schema.js` (reine Daten, **kein** Import von `config.js`): `TERMINE_COLLECTIONS = { termineConfig: { attributes, indexes }, … }` exakt nach Spec 2 (mit `einstellung` statt `data`; `termineOutbox.icsMethod`); Attributtypen `string` (Größe), `integer`, `boolean`, `datetime`; Indizes `{ key, type: 'key', attributes }`; `TERMINE_DATETIMES = { collection: [keys] }`.
- `scripts/termine-setup.mjs` (Muster `analyse-setup.mjs`, `createAppwriteClient` von dort wiederverwenden; `createAttribute` nutzt `/attributes/<type>` für alle Typen): `main({ check, client, log })`, legt Fehlendes an, Indizes nur bei neuen Collections, `--check` ⇒ Exit 1 bei Fehlendem.
- `test/support/schema.js`: `schemaKeys(collection)` kennt auch `TERMINE_COLLECTIONS` (statischer Import aus `server/services/termine/schema.js`).
- [ ] Tests: Modus (leer/unbekannt ⇒ off; pilot + `KENSO.gri@gmail.com ` ⇒ true; `*`; Laufzeitänderung von `config.termine.mode` wirkt); Setup mit Fake-Client: 4 Collections + Attribute + Indizes, zweiter Lauf legt nichts an, `--check` legt nichts an; `schemaKeys('termineConfig')` enthält `einstellung`, nicht `data`; **Rundreise**: Nachbau mit `schemaKeys('termineConfig')`, `createDocument` + `updateDocument` mit `einstellung`/`version`/`updatedBy` und Zurücklesen.
- [ ] FAIL → implementieren → PASS (`node --test test/termineSetup.test.js test/termineSchalter.test.js`, dann `npm test`) → Commit „Terminplaner: Schalter, Konfiguration, Schema“

### Task 2: Appwrite-Wrapper und Nachbau
**Files:** Modify `server/services/appwriteAdmin.js`, `test/support/appwriteMock.js`, `test/support/testApp.js` (exportiert zusätzlich `send(method, path, opts)` = bisheriges privates `request`); Test `test/appwriteBulk.test.js`.
**Produces:**
- `Query.between`, `Query.greaterThanEqual`, `Query.lessThanEqual`, `Query.cursorAfter(id)`.
- `createDocuments(collectionId, documents: Array<{ $id, ...felder }>) ⇒ docs` (roher Body `{ documents }` über neue `adminFetch`-Option `raw: true`; 409 bei Duplikat; Spike-Ergebnis V1).
- `listAllDocuments(collectionId, queries, { pageSize = 500, max = 20000 }) ⇒ docs` (`Query.limit(pageSize)`, `orderAsc('$id')`, `cursorAfter`, bis Seite < pageSize; über `max` ⇒ Fehler).
- Nachbau: `startAppwriteMock({ schema, datetimes = {}, defaultLimit = null })` – Bulk alles-oder-nichts (Duplikat ⇒ 409, unbekanntes Attribut je Dokument ⇒ 400, nichts geschrieben); neue Abfragen inkl. `cursorAfter`; Vergleich als Zeitpunkt nur, wenn beide Werte `^\d{4}-\d\d-\d\dT` sind; `datetimes`-Felder werden beim Schreiben auf `…+00:00` normalisiert, `''` ⇒ 400; `defaultLimit` (Termine-Tests: 25) gilt ohne `limit`-Abfrage wie Appwrite.
- [ ] Tests: Bulk 3 Dokumente; Bulk mit vorhandener ID ⇒ 409 und unverändert; `between` inklusiv; `listAllDocuments` über 3 Seiten; `defaultLimit` 25 liefert 25 von 30; Datum `…Z` kommt als `+00:00` zurück; alle bisherigen Tests grün.
- [ ] FAIL → implementieren → PASS → Commit „Appwrite: Bulk-Create, Bereichsabfragen, seitenweises Laden, genauerer Nachbau“

### Task 3: Zeit und Feiertage
**Files:** Create `server/services/termine/zeit.js`, `server/services/termine/feiertage.js`, `test/termineZeit.test.js`; Modify `package.json`/`package-lock.json` (`npm install feiertagejs@1.5.1 --save-exact`).
**Produces:** `zeit.js` (nur `Intl`; `/root/reports/terminplaner-2026-10-02/spike-code/tz.mjs` nur als Vorlage für `offsetMs`): `TZ`; `zuUtc(tag, 'HH:MM') ⇒ Date | null` (null, wenn `ausUtc(Ergebnis)` nicht dieselbe Wanduhrzeit ergibt; `'24:00'` = Folgetag 00:00); `ausUtc(date) ⇒ { tag, uhrzeit }`; `wochentag(tag) ⇒ 1..7`; `plusTage(tag, n)`; `heute(now) ⇒ tag`; `monatInfo('YYYY-MM') ⇒ { label: 'Oktober 2026', ersterWochentag, anzahlTage, vorher, nachher }`; `datumLang(date) ⇒ 'Montag, 12.10.2026'`, `datumKurz(date) ⇒ '12.10.2026'`, `uhrzeit(date) ⇒ '10:30'`. `feiertage.js`: `BUNDESLAENDER` (16 Kürzel), `istFeiertag(tag, land)`.
- [ ] Tests: `zuUtc('2026-03-29','02:30') === null`; `zuUtc('2026-03-29','03:00')` = `01:00Z`; `zuUtc('2026-10-25','02:30')` = `00:30Z`; `ausUtc` rückwärts; `wochentag('2026-10-05') === 1`; `plusTage('2026-10-25', 1)`; `monatInfo('2026-02')` (28 Tage, So=7 als erster); Feiertage RP 2026-06-04 ja, BE 2026-06-04 nein, BE 2026-03-08 ja, SN 2026-11-18 ja, alle 2026-12-25 ja. Zusätzlich `docker run --rm -v "$PWD":/w:ro -w /w node:20-alpine node --test test/termineZeit.test.js`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Zeit (Berlin, Umstellung) und Feiertage“

### Task 4: Einstellungen und Branchen-Vorlagen
**Files:** Create `server/services/termine/einstellungen.js`, `server/services/termine/vorlagen.js`, `test/termineEinstellungen.test.js`.
**Interfaces** (Datenform = Spec 2 `termineConfig.einstellung` + `betrieb.kleinunternehmer: boolean`, `betrieb.websiteUrl`):
- `neueId('r'|'s'|'a') ⇒ 'r_' + 8 [a-z0-9]`.
- `normalisiereEinstellung(eingabe, { bisher = null, kuenftigeTermine = { leistungen: {}, ressourcen: {} }, now }) ⇒ { einstellung } | { fehler: { [pfad]: text } }`: Vorgaben auffüllen; Steuerzeichen entfernen; Längen kürzen; Pflicht `betrieb.name` (1–80), `betrieb.email` (ein Postfach); URLs (`impressumUrl`, `datenschutzUrl`, `agbUrl`, `websiteUrl`) nur `https:`, ≤ 300, ohne Zugangsdaten; `farbe` `^#[0-9a-f]{6}$`; `anrede` sie|du; `bundesland` ∈ BUNDESLAENDER; IDs `^[rsa]_[a-z0-9]{8}$`, je Liste eindeutig, neue Einträge ohne ID ⇒ `neueId`; Obergrenzen 20 Ressourcen, 50 Leistungen, 100 Abwesenheiten, 200 Sonderöffnungen, `JSON.stringify ≤ 200 000`; Fenster `HH:MM` auf 5 min, aufsteigend, ohne Überlappung, Ende > Beginn (24:00 erlaubt); `dauer` 5–480, `pufferNach` 0–120 (je Vielfache von 5), `dauer + pufferNach ≤ 500`; `preisArt` fest|ab|keiner, `preisCent` 0–1 000 000; `buchungsart` sofort|anfrage; aktive Leistung braucht ≥ 1 aktive Ressource; `regeln.raster` ∈ {5,10,15,20,30,60}, `vorlaufMin` 0–20160, `horizontTage` 1–365, `absageBisStd` 0–336, `maxOffeneJeEmail` 1–10; `gastFelder` aus|optional|pflicht, Zusatzfelder max. 5 (`{ key: ^[a-z0-9_]{1,20}$, label, typ: text|auswahl, optionen ≤ 10, pflicht }`); `erinnerung.stundenVorher` ∈ {2,12,24,48}; `zahlung.modus` nur `vorort` (sonst Fehler „Online-Zahlung kommt bald“), `vorOrtArten` ⊆ bar|ec|kreditkarte|ueberweisung|paypal; `aufbewahrungTage` 14–365; Abwesenheiten `von ≤ bis`. Entfernen einer ID mit künftigen Terminen ⇒ Fehler „Für diese Leistung gibt es noch {n} künftige Termine. Deaktiviere sie stattdessen.“ (Ressource entsprechend); `storno.version` bei geändertem Text `YYYY-MM-DD-n` (aus `now`); `feedToken` nur aus `bisher` übernehmen, neue Ressourcen bekommen eines (32 Byte base64url), Eingabewerte werden ignoriert.
- `oeffentlicheEinstellung(einstellung, now) ⇒` Felder von `GET /config` außer `aktiv`, `hinweis`, `texte`, `formToken` (Form Task 16).
- `knopfText(leistung, { bestaetigen })`; `istVerbraucher(einstellung)`; `brauchtZustimmungVorzeitig(einstellung, leistung, start, now)`; `preisText(leistung) ⇒ '45,00 €' | 'ab 45,00 €' | ''`; `preisHinweis(einstellung) ⇒ 'inkl. USt' | 'kein Ausweis der USt nach § 19 UStG'`; `zahlungText(einstellung) ⇒ 'Bezahlung vor Ort: bar, EC-Karte, Kreditkarte'`.
- `vorlagen.js`: `VORLAGEN` (`salon, kosmetik, beratung, werkstatt, handwerk, tattoo, fotograf, hundesalon, sonstiges`; je 2–5 Leistungen, Plan, `buchungsart` anfrage bei tattoo/handwerk/fotograf, werkstatt mit 2 Plätzen, Stornotext Variante 1 aus `recherche-recht-zahlung.md` 7.3 F), `vorlagenListe()`, `ausVorlage(key, betrieb, now) ⇒ einstellung` (valide).
- [ ] Tests: alle Vorlagen valide; Pflichtfelder; `javascript:alert(1)` als `impressumUrl` ⇒ Fehler am Pfad `betrieb.impressumUrl`; Fenster 09:07 ⇒ Fehler; Überlappung ⇒ Fehler am Pfad `ressourcen.0.plan.1`; Leistung ohne aktive Ressource; Löschen mit künftigen Terminen ⇒ Fehler mit Anzahl; Client-`feedToken` wird ignoriert; `online` ⇒ Fehler; Knopftexte; Zustimmung vorzeitig (3 Tage ⇒ true, 20 Tage ⇒ false, Unternehmer/kein Preis ⇒ false); `oeffentlicheEinstellung` ohne `feedToken`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Einstellungen und Branchen-Vorlagen“

### Task 5: Verfügbarkeit
**Files:** Create `server/services/termine/slots.js`, `test/termineSlots.test.js`.
**Produces:** `belegungAus(buchungen, now, { ohneBuchung = null }) ⇒ [{ ressourceId, start, ende }]` (belegende Status, `ende` = `blockEndsAt`, ohne die genannte Buchung); `freieZeiten({ einstellung, leistungId, ressourceId /* id|'egal' */, tag, belegung, now, ohneRegeln = false }) ⇒ [{ uhrzeit, start, ressourceIds }]` (Sonderöffnung > Abwesenheit > Feiertag > Plan; Raster ab Fensterbeginn; `start + dauer + pufferNach` im Fenster; frei; `start ≥ now + vorlaufMin` und `tag ≤ heute + horizontTage` außer `ohneRegeln`; nie Vergangenheit); `freieTage({ …, monat }) ⇒ ['YYYY-MM-DD']`; `waehleRessource(ids, buchungenAmTag, einstellung)`; `blockEnde(start, leistung)`.
- [ ] Tests: Pause; Puffer am Pausenrand; Vorlauf; Horizont; Abwesenheit Ressource und Betrieb; Feiertag vs. Sonderöffnung; abgelaufene Haltung blockiert nicht; `egal` mit zwei Personen; `ohneBuchung` gibt die eigene Zeit frei; 2026-03-29 ohne `02:xx`; 2026-10-25 60-min-Termin um 02:00 dauert real 60 min; letzter Termin endet genau am Fensterende; Belegung, die am Vortag 22:00 beginnt und bis 06:00 läuft, blockiert 05:30.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Verfuegbarkeit“

### Task 6: Zellen, Tokens, Buchungsspeicher
**Files:** Create `server/services/termine/zellen.js`, `server/services/termine/token.js`, `server/services/termine/buchungen.js`, `test/termineZellen.test.js`.
**Consumes:** Task 2. **Produces:**
- `token.js`: `neuesToken() ⇒ { token, hash }`; `hashToken(t)`; `verwaltungsToken(bookingId) ⇒ token`; `buchungsNummer(bookingId) ⇒ 8 [A-Z0-9]`; `formToken(siteKey, now)`, `pruefeFormToken(siteKey, token, now) ⇒ 'ok'|'zu_schnell'|'abgelaufen'|'ungueltig'` (Mindestalter `config.termine.formMinSekunden`).
- `zellen.js` (`spike-code/claims.mjs` nur als Vorlage für den Hash-Ansatz; Zellgröße/ID/Puffer wie hier): `zellenFuer(start, blockEnde) ⇒ Date[]`; `zellenId(featureId, ressourceId, zelle)`; `belegeZellen({ featureId, ressourceId, bookingId, start, blockEnde, now, ausser = null }) ⇒ void` (Sperre `termine-res:<featureId>:<ressourceId>`, `waitMs 5000`; mit `ausser` zählen Zellen dieser Buchung als eigene: angelegt wird nur Neu − Eigen; bei 409 blockierende Zellen per ID lesen, Gültigkeit nach Global Constraints prüfen, ungültige löschen, genau ein zweiter Versuch, sonst Fehler `{ status: 409, code: 'SLOT_VERGEBEN' }`); `gibZellenFrei(bookingId, { behalte = [] })` (über `listAllDocuments`, behält die genannten Zellzeiten); `verwaisteZellen(now) ⇒ ids` (`bis < now − 1 Tag` oder Buchung nicht belegend).
- `buchungen.js` (nur Datenzugriff): `legeAn`, `hole`, `aendere` (setzt `updatedAt`), `imZeitraum(featureId, von, bis)` (`lessThan(startsAt, bis)` + `greaterThan(blockEndsAt, von)` + `featureId`, `listAllDocuments`), `perHash(feld, hash)`, `offeneFuerEmail(featureId, email, now)`, `perEmailUndNummer(featureId, email, nummer)`, `zaehleKuenftige(featureId, now) ⇒ { leistungen, ressourcen }`, `abgelaufeneHaltungen(now)`, `erinnerungsKandidaten(now)`, `zuErledigen(now)`, `vergangeneAnfragen(now)`, `loeschKandidaten(status, vor)`, `zaehleAnfragen(featureId)`.
- [ ] Tests (Nachbau, `defaultLimit 25`): zweite Buchung derselben Zeit ⇒ `SLOT_VERGEBEN`; 10 parallel ⇒ genau eine; abgelaufene Haltung und fehlende Buchung blockieren nicht; Verschieben 10:00→10:30 mit `ausser` gelingt, Fremdbuchung im neuen Bereich ⇒ `SLOT_VERGEBEN` und alte Zellen unverändert; `gibZellenFrei` löscht 40 Zellen (über 25er-Seiten); `imZeitraum` findet die Belegung vom Vortag; Verwaltungstoken stabil; Formular-Token zu jung/alt/gefälscht.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Zellen gegen Doppelbuchung, Tokens, Buchungsspeicher“

### Task 7: Rechtstext-Bausteine für Gäste
**Files:** Create `docs/rechtliches/termine-widerrufsbelehrung-muster.md`, `docs/rechtliches/termine-datenschutz-absatz.md`, `docs/rechtliches/termine-hinweise.md`, `docs/rechtliches/termine-datenschutz-6c-entwurf.md`, `server/services/termine/rechtstexte.js`, `test/termineRechtstexte.test.js`.
**Consumes:** V2. **Produces:** Belehrung + Muster-Widerrufsformular für Dienstleistungen aus `docs/rechtliches/quellen/anlage-1.txt`/`anlage-2.txt` (Gestaltungshinweise angewendet: Dienstleistung, Betriebsdaten, Hinweis auf die Widerrufsfunktion), immer Sie-Form; Datenschutz-Absatz (Sie/Du) und Formular-Hinweis nach `recherche-recht.md` 11.1/11.2 mit den Löschfristen der Global Constraints; 6c-Entwurf (nicht einbauen). Alle Dateien mit Kopf „ENTWURF – nur Pilot, vor Einsatz bei fremden Betrieben prüfen“. `rechtstexte.js`: `RECHTSTEXTE_VERSION = '2026-10-02'`, `widerrufsbelehrung(betrieb) ⇒ string` (Text mit Zeilenumbrüchen), `formularHinweis(einstellung) ⇒ string`, `ZUSTIMMUNG_VORZEITIG(name)`, `ZUSTIMMUNG_STORNO`, `ZUSTIMMUNG_ERINNERUNG(stunden)`, `GESUNDHEIT_HINWEIS`.
- [ ] Tests: Belehrung enthält „Vertrag widerrufen“, die Betriebsanschrift, keinen offenen Platzhalter und die unveränderten Kernsätze der Quelle (Absätze aus `anlage-1.txt` wörtlich enthalten); Zustimmungstexte wortgleich zu den Global Constraints.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Rechtstext-Bausteine fuer Gaeste (Entwurf)“

### Task 8: Kalenderdatei, Gästeversand, Vorlagen-Engine
**Files:** Create `server/services/termine/ics.js`, `test/termineIcs.test.js`; Modify `server/services/mailTemplates.js` (`[GKT]\d{2}` in `templateIds` und im Kopfkommentar-Regex), `server/services/mailer.js`, `test/mailTemplates.test.js` (Ordner-Test-Regex `[GKT]`; Logo-Prüfung nur K/T; G-Vorlagen: kein `webklar-logo.png`).
**Produces:** `ics.js`: `icsTermin({ uid, sequenz, methode: 'REQUEST'|'CANCEL'|'PUBLISH', start, ende, titel, ort, beschreibung, organisator: { name, email }, teilnehmer: { name, email } | null, jetzt }) ⇒ string` (CRLF, Faltung 75 Oktette, Escaping `\ ; , \n`, CR/LF in Texten entfernt, `CN="…"` ohne `"` und Steuerzeichen, UTC, `RSVP=FALSE`, CANCEL mit `STATUS:CANCELLED`); `icsKalender(termine, { name, jetzt })` (`METHOD:PUBLISH`, `X-WR-CALNAME`, `X-PUBLISHED-TTL:PT15M`). `mailer.sendGuestMail({ to, fromName, replyTo = null, subject, html, text, ics = null, icsMethod = 'REQUEST' }) ⇒ info` (wirft; `from: { name, address }`; `icalEvent: { method, filename: 'termin.ics', content }` nur mit `ics`; nie `bcc`).
- [ ] Tests: ICS-Zeilenlänge, `UID`/`SEQUENCE`, Escaping, CANCEL; `sendGuestMail` über `mailSink`: kein `bcc`, `replyTo`, From-Name = Betrieb, `sent[0].icalEvent.method === 'REQUEST'` und `content` enthält `BEGIN:VCALENDAR`, ohne `ics` kein `icalEvent`; bestehende Vorlagen-Tests grün (noch ohne neue Vorlagen).
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Kalenderdatei, Gaesteversand, Vorlagen-Engine fuer G-Vorlagen“

### Task 9: Mailvorlagen G01–G08, K20, K21
**Files:** Create `server/mail-templates/G01 Termin bestaetigen.html`, `G02 Termin bestaetigt.html`, `G03 Anfrage eingegangen.html`, `G04 Anfrage abgelehnt.html`, `G05 Erinnerung.html`, `G06 Termin abgesagt.html`, `G07 Termin verschoben.html`, `G08 Eingang Widerruf.html`, `K20 Neue Buchung.html`, `K21 Termin geaendert.html`; Modify `test/mailTemplates.test.js` (`EXPECTED` sortiert: G01–G08, K01–K21, T01–T18; Kommentar).
- Gerüst wie die vorhandenen Vorlagen: Kopfkommentar (`G01 · …`, `Betreff: {{betreff}}`, Platzhalter-, Block-Liste), `<title>{{betreff}}</title>`, `<!--[if mso]>`-Block, sonst keine Kommentare, jeder Platzhalter/Block deklariert und benutzt.
- G-Layout neutral: Kopfbalken in `{{farbe}}` mit `{{betrieb_name}}`, kein Logo; Fuß `{{betrieb_name}}`, `{{betrieb_adresse}}`, `{{betrieb_telefon}}`, `{{betrieb_email}}`, `{{impressum_url}}`, `{{datenschutz_url}}`, Satz „Diese E-Mail wurde im Auftrag von {{betrieb_name}} über den Terminplaner von WEBklar versendet.“; Blöcke `sie`/`du` für jeden Anredetext.
- Platzhalter: G01 `leistung, datum, zeit, link` + Block `zu_viele` (Text: höchstmögliche Zahl offener Termine, absagen oder anrufen `{{betrieb_telefon}}`) – **kein** `gast_name`; G02 `gast_name, leistung, person, datum, zeit, dauer, preis, zahlung, nummer, link, ort` + Blöcke `preis`, `person`, `storno` (`{{storno_text}}`), `widerruf` (`{{widerrufsbelehrung}}`, `{{widerruf_link}}`), `anfrage_angenommen`; G03 `gast_name, leistung, datum, zeit, link`; G04 `gast_name, leistung, datum, zeit` + Block `nachricht` (`{{nachricht}}`); G05 `gast_name, leistung, person, datum, zeit, link` + Block `person`; G06 `gast_name, leistung, datum, zeit, absage_von, grund` + Block `nachricht`; G07 `gast_name, leistung, alt_datum, alt_zeit, datum, zeit, link`; G08 `eingang, nummer` + Blöcke `zugeordnet`, `nach_frist` – **kein** `gast_name`. K20 (Du-Form, WEBklar-Layout mit Logo): `kunde_name, leistung, person, datum, zeit, gast_name, gast_email, gast_telefon, gast_nachricht, portal_link` + Block `anfrage`; K21: wie K20 + `alt_datum, alt_zeit, eingang` + Blöcke `abgesagt`, `verschoben`, `widerrufen`, `nicht_zugeordnet`, `nach_frist`.
- [ ] Tests: Vorlagen-Suite grün inkl. neuer IDs (Titel = Betreff, ein Kommentar, keine Reste, Text ohne Tags); `renderMail('G02', …, { du: true })` enthält im Text kein „ Sie “/„Ihr “; G01/G08 haben keinen Platzhalter `gast_name`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Mailvorlagen G01–G08, K20, K21“

### Task 10: Mail-Warteschlange
**Files:** Create `server/services/termine/outbox.js`, `test/termineOutbox.test.js`.
**Consumes:** Task 8. **Produces:** `einreihen({ featureId, bookingId, art, an, fromName, replyTo, template, values, blocks, ics, icsMethod }) ⇒ doc` (rendert sofort, speichert `wartet`, ruft `sendeEintrag(id)` ohne zu warten); `sendeEintrag(id)` (einziger Sendepfad: Pause/Budget prüfen, Sperre `termine-mail:<id>`, Fehlerklassen laut Global Constraints, nach Erfolg Inhalt leeren); `verarbeite(now)`; `warteAufVersand()` (für Tests: wartet auf laufende Sendeversuche); `zustellFehler(bookingIds) ⇒ Set`; `raeumeAuf(now)`; `pausiertBis()`.
- [ ] Tests: Budget 2/h ⇒ dritter wartet; 4xx ⇒ 1/5/30 min, dann `fehler`; 550 ⇒ sofort `fehler`; EAUTH ⇒ Pause, während der Pause **keine** Sendeversuche (Fake-Transport zählt), danach weiter; zwei `verarbeite` parallel ⇒ eine Mail; nach Erfolg sind `an/html/text/ics` leer; Aufräumen 7 Tage / 48 h.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Mail-Warteschlange mit Stundenbudget“

## Portal: Ablauf

### Task 11: Kontext, Einstellungs-Speicher, Mail-Werte
**Files:** Create `server/services/termine/kontext.js`, `server/services/termine/mails.js`, `test/termineKontext.test.js`.
**Consumes:** Tasks 4, 6, 7, 9, 10. **Produces:**
- `kontext.js`: `kontextPerSiteKey(siteKey) ⇒ ctx|null` (Funktion `termine`, `active`, Modus ≠ off; eigene Abfrage bis Task 17, dann `findActiveBySiteKey(siteKey, 'termine')`; 30 s Speicher-Cache je siteKey); `kontextPerFeature(featureId) ⇒ ctx|null` (auch `disabled`); `ctx = { feature, project, einstellung, version }`; `ladeEinstellung(featureId)`; `speichereEinstellung(feature, einstellung, { version, by }) ⇒ { einstellung, version }` (Sperre `termine-cfg:<featureId>`, Dokument-ID = featureId, 409 bei Versionskonflikt, Cache leeren); `websiteUrl(ctx)` (`einstellung.betrieb.websiteUrl` oder `https://` + erster Host aus `analyseHosts(project)`).
- `mails.js`: `BETREFFE` (Tabelle je Vorlage × Anrede × Fall, Sie/Du, G05 „Erinnerung: Ihr Termin am {datum} um {zeit}“); `werteFuer(art, ctx, buchung, extra) ⇒ { values, blocks }` (Links `${config.publicBaseUrl}/termin.html#v=<token>` bzw. `#m=<verwaltungsToken>`; `widerruf_link` = Verwaltungslink); `anGast(art, ctx, buchung, extra)`, `anBetrieb(art, ctx, buchung, { block, extra })` über `einreihen` (ICS: G02/G07 REQUEST, G06 CANCEL, K20 PUBLISH).
- [ ] Tests: Speichern/Laden mit Version, Konflikt ⇒ 409; Cache wird beim Speichern geleert; Betreff je Anrede (Du ohne „Sie“); G02-Werte mit Widerrufsblock nur bei Verbraucher; Links zeigen auf `config.publicBaseUrl`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Kontext, Einstellungs-Speicher, Mail-Werte“

### Task 12: Gast: halten, Vorschau, bestätigen
**Files:** Create `server/services/termine/ablauf.js`, `test/termineAblaufGast.test.js`.
**Consumes:** Tasks 5, 6, 11. **Produces** (jede Zustandsänderung unter `withLocks(['termine-buchung:'+id])` mit frischem Lesen):
- `halte(ctx, eingabe, now) ⇒ { status: 'gehalten'|'zu_viele', email }` – Eingabe `{ leistung, ressource, tag, zeit, name, email, telefon, nachricht, zusatz, erinnerung, zustimmungen: { storno, vorzeitig } }`; Feldfehler (400, `err.fehler`); Slot neu berechnen; Ressource bei `egal` wählen; **erst** Buchung `gehalten` anlegen (`heldUntil = now + holdMinutes`, `nachweis` = Fassungen/Hashes der Texte, Zeitpunkte, Knopftext, Anrede; `verbraucher`, `preisCent`, `preisArt`, `buchungsart`, `zahlart 'vorort'`, `zahlStatus 'keine'`, `icsSequenz 0`, `verifyHash`), **dann** Zellen; `SLOT_VERGEBEN` ⇒ Buchung `verfallen`, Fehler 409 Feld `zeit`; G01; Grenze offene Termine ⇒ nichts anlegen, G01-Block `zu_viele`, Ergebnis `zu_viele`.
- `vorschau(token, now) ⇒ { art: 'bestaetigen'|'verwalten', status, termin: { nummer, leistung, person, datum, zeit, dauer, preis, zahlung, ort }, betrieb: { name, telefon, adresse, impressumUrl, datenschutzUrl, websiteUrl }, gast: { name, email }, anrede, farbe, knopf, aktionen: { bestaetigen, absagen, verschieben, widerrufen }, hinweis }` (Token zuerst als Bestätigungs-, dann als Verwaltungstoken suchen; unbekannt/abgelaufen ⇒ 404).
- `bestaetige(token, now) ⇒ { status, schon? }` – `gehalten` + `heldUntil > now` ⇒ `sofort`: `bestaetigt` + `bestaetigtAt` + `manageHash` + G02 + K20; `anfrage`: `angefragt` + `manageHash` + G03 + K20-Block `anfrage`; schon bestätigt ⇒ `{ status, schon: true }`; abgelaufen ⇒ 410 `{ code: 'abgelaufen', betrieb: { name, telefon, websiteUrl } }`.
- [ ] Tests (Nachbau `defaultLimit 25`, `mailSink`, `warteAufVersand`): Halten ⇒ G01 ohne Gastname, Zellen; Bestätigen ⇒ G02 mit `icalEvent` und `#m=`-Link + K20 an den Betrieb, kein BCC; Anfrage ⇒ G03/K20-Block; zweiter Klick ⇒ `schon`; nach 31 min ⇒ 410; `email_normalisiert` (`'  Max@GMail.com '` zählt gegen dieselbe Grenze); vierte offene Buchung ⇒ `zu_viele`, keine Buchung, G01-Block; Slot weg ⇒ 409, Buchung `verfallen`, keine Zellen; Zustimmung vorzeitig fehlt ⇒ 400 Feld `vorzeitig`; `vorschau` mit Verwaltungstoken liefert `gast`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Buchung halten und bestaetigen“

### Task 13: Gast: absagen, verschieben, widerrufen
**Files:** Modify `server/services/termine/ablauf.js`; Test `test/termineAblaufVerwalten.test.js`.
**Produces:** `sageAbGast(token, now)` (bis `absageBisStd` vor Beginn, sonst 409 Feld `_` „Absage nur telefonisch: {telefon}“; Zellen frei, G06 CANCEL, K21 `abgesagt`); `verschiebeGast(token, { tag, zeit }, now)` (gleiche Frist; Belegung `ohneBuchung`; `belegeZellen({ …, ausser: id })`, dann `gibZellenFrei(id, { behalte: neueZellen })`; `icsSequenz+1`; G07 + K21 `verschoben`); `zeitenFuerToken(token, { tag | monat }, now)` (für die Gästeseite, `ohneBuchung`); `widerrufeGast(token, { name }, now) ⇒ { eingang: { datum, uhrzeit } }` und `widerrufeOhneLink(ctx, { name, email, nummer }, now) ⇒ { eingang }` (Treffer mit Widerrufsrecht ⇒ `widerrufenAt`, `abgesagt` von `gast`, Zellen frei, G08 `zugeordnet`, K21 `widerrufen`; Treffer nach Frist ⇒ nur speichern + G08 `nach_frist` + K21 `nach_frist`; kein Treffer ⇒ G08 + K21 `nicht_zugeordnet`; Grenzen aus Global Constraints; Antwort immer gleich, Eingang in Berliner Zeit als Strings).
- [ ] Tests: Absage vor/nach Frist; Verschieben 10:00→10:30 (überlappend) gelingt, ICS Sequenz 1; Verschieben auf belegte Zeit ⇒ 409, alte Zellen unverändert; Widerruf 2 h vor Termin trotz abgelaufener Stornofrist; Widerruf ohne Treffer = gleiche Antwort + K21 `nicht_zugeordnet`; vierter G08 an dieselbe Adresse am Tag wird nicht gesendet; nicht angenommene Anfrage ⇒ kein Widerruf, nur Absage.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Absagen, Verschieben, Widerruf durch Gaeste“

### Task 14: Betrieb: Aktionen, manuelle Termine, Sperren
**Files:** Modify `server/services/termine/ablauf.js`; Test `test/termineAblaufBetrieb.test.js`.
**Produces:** `aktion(ctx, bookingId, { aktion: 'annehmen'|'ablehnen'|'absagen'|'verschieben'|'nichterschienen'|'anonymisieren', grund, nachricht, tag, zeit }, now)` (annehmen ⇒ `bestaetigt`, `angenommenAt`, G02 Block `anfrage_angenommen`; ablehnen ⇒ `abgelehnt`, G04, Zellen frei; absagen ⇒ G06 mit `absage_von` = Betriebsname; verschieben ⇒ wie Gast, ohne Frist, `ohneRegeln`; nichterschienen nur nach Beginn; anonymisieren ⇒ Gastfelder leeren, Status bleibt); `manuell(ctx, eingabe, now)` (`quelle 'manuell'`, `bestaetigt`, `verbraucher false`, Länge ≤ 500 min, G02 nur mit `bestaetigungSenden`); `sperre(ctx, { ressource, tag, von, bis, titel }, now)` (`quelle 'sperre'`, `bestaetigt`, `leistungName` = Titel, Länge ≤ 500 min sonst 400 Feld `bis` „Eine Sperre kann höchstens 8 Stunden 20 Minuten dauern. Für ganze Tage nutze Abwesenheiten.“); `entsperre(ctx, bookingId)`.
- [ ] Tests: annehmen ⇒ G02 mit Verwaltungslink (gleicher Link wie in G03); ablehnen ⇒ Zellen frei; manuell ohne Haken ⇒ keine Gastmail; Sperre 09:00–17:30 ⇒ 400; Sperre 09:00–13:00 blockiert Slots; anonymisieren; `nichterschienen` vor Beginn ⇒ 409.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Aktionen des Betriebs, manuelle Termine, Sperren“

### Task 15: Hintergrund-Jobs
**Files:** Create `server/services/termine/jobs.js`, `test/termineJobs.test.js`; Modify `server/index.js`.
**Produces:** jeder Job kehrt bei `termineAus()` sofort zurück (keine Abfrage); `collection_not_found` (404) ⇒ höchstens eine Warnung je Stunde. `minutenJob(now)` (abgelaufene Haltungen ⇒ `verfallen`, Zellen frei; `outbox.verarbeite`); `fuenfMinutenJob(now)` (Erinnerungen nach Spec 4: Marker zuerst, dann G05; `erledigt`; vergangene Anfragen ⇒ `abgelehnt`); `taeglicherJob(now)` (Löschfristen, Outbox aufräumen, verwaiste Zellen, `disabled`-Funktionen > 30 Tage: Buchungen, Zellen, Einstellung). In `server/index.js` wie die vorhandenen Jobs (`setTimeout(…).unref()` + `setInterval(…).unref()`, eigene Fehlerbehandlung): 60 s, 5 min, täglich (+180 s).
- [ ] Tests: Modus off ⇒ keine Appwrite-Anfrage; Verfall; Erinnerung genau einmal (zwei Läufe), nicht bei Buchung kürzer als `stundenVorher` vor Beginn, nachgeholt nach 20 min Jobausfall; `erledigt`; vergangene Anfrage ⇒ `abgelehnt`, Zellen frei; Löschfristen je Status; `verfall_und_bestaetigung_gleichzeitig` (Job und `bestaetige` parallel ⇒ ein Endzustand, keine G02 nach `verfallen`); fehlende Collection ⇒ eine Warnung.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Hintergrund-Jobs“

## Portal: Schnittstellen

### Task 16: Öffentliche Schnittstelle
**Files:** Create `server/services/termine/limits.js`, `server/routes/publicTermine.js`, `test/publicTermine.test.js`, `test/publicTermineRohling.test.js`; Modify `server/index.js` (nach `kundenansichtGuard`, vor dem globalen `express.json`), `server/middleware/kundenansichtGuard.js` (`PASS_PREFIXES` + `'/api/public/'`), `test/kundenansichtGuard.test.js`.
**Consumes:** Tasks 11–14, `analyseDomains(project)` aus `server/services/analyse.js`.
**Routen** (`/api/public/termine/v1`; feste Pfade vor `/:siteKey`):
- `GET /:siteKey/config` ⇒ `{ aktiv: true, heute, betrieb: { name, telefon, adresse, impressumUrl, datenschutzUrl }, anrede, farbe, leistungen: [{ id, name, beschreibung, dauer, preis, preisArt, buchungsart, knopf, verbraucher, ressourcen }], ressourcen: [{ id, name, typ }], personWaehlbar, regeln: { horizontTage, absageBisStd }, zahlung: { modus: 'vorort', text }, preisHinweis, storno: { text, version } | null, widerruf, erinnerung: { anbieten, stundenVorher }, gastFelder, hinweis, texte: { storno, erinnerung, vorzeitig, gesundheit }, formToken }` (`public, max-age=60`, ohne ETag).
- `GET /:siteKey/tage?leistung&ressource&monat` ⇒ `{ tage, monat: monatInfo }` (`max-age=15`); `GET /:siteKey/zeiten?leistung&ressource&tag` ⇒ `{ zeiten: ['09:00'], datumLang, vorzeitigNoetig }` (`no-store`; `vorzeitigNoetig` serverseitig für diesen Tag).
- `POST /:siteKey/buchungen` (Eingabe von `halte` + `formToken`, `kontakt_url`) ⇒ 201 `{ ok: true, email: 'm***@gmail.com', minuten: 30 }`.
- `POST /:siteKey/widerruf` `{ name, email, nummer }` ⇒ `{ ok: true, eingang: { datum, uhrzeit } }`.
- `POST /termin/vorschau|bestaetigen|absagen` `{ token }`, `POST /termin/verschieben` `{ token, tag, zeit }`, `POST /termin/widerruf` `{ token, name }`, `POST /termin/tage` `{ token, monat }`, `POST /termin/zeiten` `{ token, tag }`.
- `GET /kalender/:siteKey/:feedToken.ics` (konstantzeitiger Vergleich mit den `feedToken` der Ressourcen; falsch ⇒ 404 ohne Hinweis; `text/calendar; charset=utf-8`, `max-age=300`; bestätigte Termine + Sperren der Ressource, −7 bis +90 Tage).
- CORS: GET `*`; POST/OPTIONS erlaubt, wenn Origin-Host ∈ `analyseDomains(project)` ∪ {Host von `config.publicBaseUrl`} oder `new URL(origin).host === req.get('host')` (gleiche Herkunft); für `/termin/*` nur die beiden letzten; dann `Access-Control-Allow-Origin: <origin>`, `Vary: Origin`; sonst 403 `{ fehler: { _: 'Nicht erlaubt' } }`; Preflight 204 (`GET, POST, OPTIONS`, `Content-Type`, `Max-Age 86400`). Router-Parser + Fehlermiddleware laut Global Constraints; `/tage` und `/zeiten` 10 s Speicher-Cache je (siteKey, Parameter).
- [ ] `publicTermine.test.js` (startTestApp + Nachbau + `mailSink`; Origin/`X-Forwarded-For` je Test, `resetTermineLimitsForTests()`, `config.termine.formMinSekunden = 0`): rekursiv keine verbotenen IDs; unbekannt/off/disabled ⇒ `{aktiv:false}` (GET und POST); fremde Origin ⇒ 403, gleiche Herkunft und `liveDomain`-Origin erlaubt; Preflight (`send('OPTIONS', …)`); Honeypot und `zu_schnell` (mit `formMinSekunden = 3`) ⇒ 201 ohne Buchung; `abgelaufen` ⇒ 400; 11. Buchung je IP ⇒ 429, IPv6 /64 geteilt; Knopf je Fall in `config`; Ablauf halten → vorschau → bestätigen → verschieben → absagen über HTTP; Widerruf mit/ohne Treffer gleiche Antwort; Kalender mit falschem Token 404, richtigem enthält den bestätigten, nicht den gehaltenen Termin; `failNext` ⇒ 503 ohne Rohtext; Kundenansicht-Cookie stört öffentliche POSTs nicht.
- [ ] `publicTermineRohling.test.js` (nacktes `express()` nur mit dem Router): 20 KB ohne `content-length` (chunked) ⇒ 413; kaputtes JSON ⇒ 400; Antwort ohne Parser-Rohtext. Reihenfolge-Test: in `server/index.js` steht `app.use(kundenansichtGuard)` vor `'/api/public/termine/v1'` vor `app.use(express.json(`.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: oeffentliche Schnittstelle v1 mit Missbrauchsschutz“

### Task 17: Funktionen verallgemeinern, Team-Route, Kundenansicht
**Files:** Modify `server/services/siteFeatures.js`, `server/routes/admin/funktionenAdmin.js`, `server/routes/funktionen.js`, `server/middleware/kundenansichtGuard.js`, `server/services/customerViewLog.js`, `server/services/customerAdmin.js`, `server/services/termine/kontext.js`; Tests `test/funktionenRoutes.test.js`, `test/siteFeatures.test.js`, `test/kundenansichtGuard.test.js` (Erlaubnisliste exakt; `MOUNTS` + `/api/termine` erst in Task 18), `test/customerViewLog.test.js` (zehn Aktionen), neu `test/funktionenTermine.test.js`.
**Produces:** `FEATURE_KEYS = ['news','termine']`; `FEATURE_LABELS = { news: { name: 'News-Pinnwand', keine: 'keine News-Pinnwand' }, termine: { name: 'Terminplaner', keine: 'keinen Terminplaner' } }`; `findActiveBySiteKey(siteKey, featureKey = 'news')`; `activateClosedTickets` unverändert (TP2). Team: `POST /api/team/funktionen/:customerId/:key` (`key` ∉ FEATURE_KEYS ⇒ 404; Meldung „Für dieses Projekt gibt es noch {keine}“); `adminView` lädt die Funktionsdokumente des Kunden einmal. `GET /api/funktionen` + `termine: { verfuegbar: termineFuerKunde(req.session.email) }`. `KUNDENANSICHT_ALLOWED` + `['POST', /^\/api\/termine\/.+$/]`, `['PATCH', /^\/api\/termine\/einstellungen\/?$/]`, `['DELETE', /^\/api\/termine\/buchungen\/[^/]+\/?$/]`; `VIEW_ACTIONS` + `termin_einstellungen`, `termin_aktion`, `termin_manuell`. `deleteCustomerWithPortalAccess` schaltet Terminplaner-Funktionen des Kunden ab (Notiz „Kunde gelöscht“). `kontext.js` nutzt nun `findActiveBySiteKey(…, 'termine')`.
- [ ] Tests: Team aktiviert `termine` für Projekt von c1, News unverändert; `/:customerId/kalender` ⇒ 404; Meldungen grammatisch; `GET /api/funktionen` mit/ohne Pilot-E-Mail; Erlaubnisliste exakt (inkl. Negativfall `POST /api/termineX`); Kunde löschen ⇒ `disabled`; bisherige Tests grün.
- [ ] FAIL → implementieren → PASS → Commit „Funktionen: Terminplaner als zweite Funktion (Team-Route, Kundenansicht)“

### Task 18: Kunden-Schnittstelle `/api/termine`
**Files:** Create `server/routes/termine.js`, `test/termineRoutes.test.js`; Modify `server/index.js` (`app.use('/api/termine', termineRoutes)`), `test/kundenansichtGuard.test.js` (`MOUNTS` + `['/api/termine', termineRoutes]`).
**Consumes:** Tasks 4, 6, 11–14, 17. Alle Routen: `requireSession`; `projectId` (Query/Body); `assertOwnProject`; `termineFuerKunde(session.email)` sonst 409 „Der Terminplaner ist noch nicht verfügbar.“; Funktion `off`/fehlt ⇒ 409 „Der Terminplaner ist für diese Website nicht aktiv.“; `disabled` ⇒ nur Lesen + Export; Schreiblimit 120/h je Kunde; Protokoll: PATCH einstellungen, POST vorlage, POST feed ⇒ `termin_einstellungen`; POST aktion, DELETE ⇒ `termin_aktion`; POST buchungen ⇒ `termin_manuell`.
**Routen:** `GET /einstellungen?projectId` ⇒ `{ state, aktivSeit, einstellung | null, version, vorlagen, feeds: { [ressourceId]: url }, siteKey, einbau: { snippet }, anfragenOffen }`; `POST /einstellungen/vorlage` `{ projectId, vorlage }` (nur ohne Einstellung, sonst 409; Betrieb vorbefüllt aus `analysePrivacyData(customer)` (Name/Firma, Anschrift, E-Mail) + `phone`); `PATCH /einstellungen` `{ projectId, version, einstellung }` ⇒ `{ einstellung, version }` | 400 `{ fehler }` | 409; `GET /buchungen?projectId&von&bis&status=a,b` (Zeitraum ≤ 62 Tage) ⇒ `{ buchungen: [{ id, nummer, status, quelle, startsAt, endsAt, datum, zeit, leistungId, leistung, dauer, titel, person, ressourceId, gastName, gastEmail, gastTelefon, gastNachricht, erinnerung, zustellFehler, angenommenAt, widerrufenAt, abgesagtVon, absageGrund }] }`; `GET /zeiten?projectId&leistung&ressource&tag[&ohne=bookingId]` (`ohneRegeln`); `POST /buchungen` `{ projectId, art: 'manuell'|'sperre', … }` ⇒ 201; `POST /buchungen/:id/aktion`; `DELETE /buchungen/:id?projectId` (nur Sperren); `POST /ressourcen/:id/feed` ⇒ `{ url }`; `GET /export.csv?projectId` (`text/csv; charset=utf-8`, BOM, `;`, Kopf `Nummer;Status;Datum;Uhrzeit;Leistung;Person/Platz;Name;E-Mail;Telefon;Nachricht`, Zellen mit `= + - @` am Anfang ⇒ `'` voran).
- [ ] Tests (`send` für PATCH/DELETE): fremdes Projekt 403; ohne Pilot 409; Vorlage zweimal ⇒ 409; PATCH alte Version ⇒ 409; Löschen mit künftigem Termin ⇒ 400 mit Anzahl; Aktion annehmen ⇒ G02; Kundenansicht darf PATCH/DELETE (mit Header) und es wird protokolliert; Guard-Schleife „jede Schreib-Route außerhalb der Liste ⇒ 403“ grün mit dem neuen Router; `disabled` ⇒ PATCH 409, Export 200; CSV entschärft.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Kunden-Schnittstelle“

## Portal: Oberflächen

**UI-Testserver (Tasks 19–21):** `startAppwriteMock({ schema, datetimes, defaultLimit: 25 })` + `startFakeStripe()` + `useTestEnv({ appwriteUrl, stripeUrl })`, dann dynamische Imports; `startTestApp({ '/api/public/termine/v1': publicTermineRoutes, '/api/termine': termineRoutes, '/api/funktionen': funktionenRoutes, '/': express.static('public') })`; danach `config.publicBaseUrl = app.url`, `config.termine.mode = 'pilot'`, `config.termine.pilotEmails = ['*']`, `config.termine.formMinSekunden = 0`; Seed: Projekt + aktive Funktion + Einstellung aus Vorlage `salon` mit Plan Mo–So 00:00–24:00, `feiertageGeschlossen false`, `vorlaufMin 0`, `maxOffeneJeEmail 10`; `mailSink`. Screenshots nach `/root/reports/terminplaner-ui/`.

### Task 19: Einbau-Skript, Demo, Einbauanleitung
**Files:** Create `public/embed/termine.js`, `public/embed/termine-demo.html`, `docs/funktionen/termine-einbau.md`, `test/ui/termine-widget.ui.mjs`, `test/termineEmbedStatic.test.js`.
**Consumes:** Task 16 (Antwortformen). **Produces:** Einbau nach Spec 7 (`data-webklar-termine`, `data-api`, `data-modus inline|knopf`, `data-knopf`, `data-leistung`); Klassen `wkt-*`; `<style id="wkt-style">` einmal, `@layer wkt`; CSS-Variablen `--wkt-akzent, --wkt-akzent-text, --wkt-hintergrund, --wkt-text, --wkt-rand, --wkt-radius, --wkt-schrift, --wkt-schrift-titel`; Schritte Spec 4; Monatsraster aus `monat` (APG: Pfeile, Pos1/Ende, Bild↑/↓, `aria-selected`, `aria-disabled`), Zeiten als Knöpfe; `aria-live="polite"`; Texte Sie/Du nach `anrede`, Haken-Texte aus `texte`, Knopf aus `leistungen[].knopf`; Honeypot `kontakt_url` (unsichtbar, `autocomplete="off"`, `tabindex="-1"`, `aria-hidden`); `config` neu laden, wenn älter als 100 min; Fuß „Vertrag widerrufen“ (Formular → `POST /widerruf`), „Datenschutz“, „Terminbuchung über WEBklar“; Knopfmodus lädt beim Klick; Fehler ⇒ Ausweichtext bzw. „Gerade nicht erreichbar. Bitte rufen Sie an: {telefon}“. Einbauanleitung: Snippet, Variablen, drei Stilbeispiele, Datenschutz-Absatz (Task 7), Abnahme-Checkliste, API-Kurzreferenz.
- [ ] `termineEmbedStatic.test.js`: Quelltext ohne `localStorage`, `sessionStorage`, `document.cookie`, `Date`, `getDay`, `toLocale`, `Intl.`; `innerHTML` nur mit Konstanten.
- [ ] Playwright (UI-Testserver): inline bis „Fast geschafft“ + G01 im Sink; Knopfmodus mit `<dialog>`; nur Tastatur; 390 px; `timezoneId: 'America/New_York'` zeigt dieselben Uhrzeiten; Anrede Du; zwei Widgets; Server gestoppt ⇒ Ausweichtext.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Einbau-Skript, Demo und Einbauanleitung“

### Task 20: Gästeseiten
**Files:** Create `public/termin.html`, `public/termin.js`, `public/termin.css`, `test/ui/termin-seiten.ui.mjs`.
**Produces:** liest `#v=`/`#m=`, entfernt den Hash per `history.replaceState`, ruft `/termin/vorschau`; Ansichten Bestätigen (Zusammenfassung + `knopf`), Bestätigt/Angefragt, Abgelaufen (Link `websiteUrl`, Telefon), Verwalten (Absagen mit Rückfrage in der Seite, Verschieben über `/termin/tage|zeiten`, „Vertrag widerrufen“ → Formular nach § 356a mit vorbefülltem Namen/Buchungsnummer/E-Mail, Knopf „Widerruf bestätigen“, Eingang mit `eingang.datum`/`uhrzeit`); Kopf in `farbe`; Fuß: Impressum/Datenschutz des Betriebs + „Impressum WEBklar“ (`/impressum.html`); `noindex`; keine Cookies; Sie/Du.
- [ ] Playwright: G01-Link aus dem Sink öffnen ⇒ bestätigen ⇒ G02 im Sink; zweiter Aufruf „bereits bestätigt“; abgelaufen; absagen; verschieben; widerrufen (`timezoneId: 'America/New_York'` zeigt Berliner Eingangszeit); 390 px.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Gaesteseiten Bestaetigen, Verwalten, Widerrufen“

### Task 21a: Portal-Ansicht – Gerüst, Kachel, Termine
**Files:** Create `public/termine.js`, `public/termine.css`, `public/termine-view.js`, `test/termineView.test.js`, `test/ui/termine-portal.ui.mjs`; Modify `public/funktionen.js`, `public/app.js` (`VIEW_HASHES.termine = 'termine'`, `viewRefreshers.termine`, `APP_PARENT.termine = 'funktionen'`, `FEATURE_LABELS.termine = 'Terminplaner'`), `public/dashboard.html` (`<section class="kb-view" id="view-termine"><header class="kb-head"><h1>Terminplaner</h1><p>…</p></header><div id="termine-body">…`, Stylesheet), `test/funktionenTiles.test.js`.
**Produces:** Kachel (`termine?.verfuegbar` fehlt/false ⇒ „Kommt bald“; `project.features?.termine || { state: 'off' }`; *Aus* „Wir schalten den Terminplaner für dich frei.“ + Chat / *Aktiv* „Termine öffnen“ + „{n} Anfragen warten“ aus `anfragenOffen` / *Abgeschaltet*); `termine-view.js` (rein): `fensterParsen('09:00–12:30, 13:30–18:00')`, `fensterText`, `statusLabel`, `wocheVon(tag)`, `gruppiereNachTag(buchungen)`; `termine.js` `initTermine(root, { projectId })`: Projektauswahl, Vorlagenauswahl ohne Einstellung, Reiter-Gerüst, Reiter **Termine** (Tag/Woche/Monat mit `von/bis`, Filter → Statuslisten, Aktionen mit Rückfragen in der Seite, „+ Termin eintragen“, „Zeit sperren“ mit 500-Minuten-Hinweis, Hinweis „Bestätigung nicht zugestellt“), `disabled` ⇒ nur Lesen.
- [ ] Tests reine Helfer; Kachelzustände; Playwright (Fixture `page.route` und ein Lauf gegen den UI-Testserver): Vorlage wählen, Liste mit allen Status, Anfrage annehmen, App-Ansicht 390 px als Unterseite von Funktionen (Titel „Terminplaner“).
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Portal-Ansicht, Kachel, Termine“

### Task 21b: Portal-Ansicht – Leistungen, Team & Plätze, Einstellungen
**Files:** Modify `public/termine.js`, `public/termine.css`, `test/ui/termine-portal.ui.mjs`.
**Produces:** Reiter **Leistungen** (Liste, Reihenfolge, Felder Task 4, Gesundheits-Hinweis), **Team & Plätze** (Wochenplan je Tag mit `fensterParsen`, Leistungszuordnung, Abwesenheiten, Bundesland, Sonderöffnungen, Kalender-Abo-Link kopieren/neu), **Einstellungen** (Spec 9 Punkt 4; Zahlung „online“ ausgegraut „kommt bald“; Hinweis Widerruf schlägt Stornofrist; Stornotext-Muster gekennzeichnet; Export-Link); Speichern mit `version`, Konflikt ⇒ „Die Einstellungen wurden inzwischen geändert. Bitte neu laden.“; Feldfehler am Feld.
- [ ] Playwright: Leistung anlegen, Wochenplan ändern, Speichern, Konflikt (zweiter Tab), Feldfehler (`javascript:`-URL), Feed-Link neu erzeugen.
- [ ] FAIL → implementieren → PASS → Commit „Terminplaner: Portal-Ansicht Leistungen, Team, Einstellungen“

## WOMS

### Task 22: Funktionen-Reiter für mehrere Funktionen
**Repo:** `/home/webklar/apps/ticket.webklar.com/dev-termine` (aus V3; existiert er nicht, Schritte aus V3 zuerst ausführen).
**Files:** Create `src/lib/funktionenView.js`, `tests/unit/funktionenView.test.mjs`; Modify `src/lib/teamApi.js` (`setFeature(customerId, key, { projectId, action, note })`; `setNewsFeature` als Wrapper), `src/components/customer/CustomerFunktionen.jsx`, `src/lib/viewLog.js` (+ `termin_einstellungen: 'Terminplaner-Einstellungen geändert'`, `termin_aktion: 'Termin bearbeitet'`, `termin_manuell: 'Termin eingetragen'`), `tests/unit/viewLog.test.mjs`.
**Produces:** `FUNKTIONEN = [{ key: 'news', label: 'News', bestaetigen: { activate: 'News ohne Zahlung aktivieren?', disable: 'News abschalten? Die Website zeigt dann keine Beiträge mehr.' } }, { key: 'termine', label: 'Terminplaner', bestaetigen: { activate: 'Terminplaner ohne Zahlung aktivieren?', disable: 'Terminplaner abschalten? Auf der Website sind dann keine Buchungen mehr möglich.' } }]`, `ZUSTAND` (bisheriges `STATE`), `funktionOf(project, key)`, `aktionen(state)`, `mergeFunktion(projects, projectId, key, aktualisiert)`; Reiter zeigt je Projekt eine Zeile je Funktion, Ticketnummer als Link `/tickets?woid=`, Antwort übernimmt nur `features[key]`.
- [ ] Tests (Register, Aktionen, Merge überschreibt die andere Funktion nicht); `npm test`; `nice npx vite build` (vorher `free -m`).
- [ ] FAIL → implementieren → PASS → Commit „Funktionen-Reiter: News und Terminplaner je Projekt“

---

## Abschluss

- [ ] Gesamt-Review des Branches (Portal + WOMS) gegen Spec TP1 und Global Constraints; Critical/Important beheben.
- [ ] `npm test` (Node 24); reine Termine-Tests unter Node 20 (`docker run --rm -v "$PWD":/w:ro -w /w node:20-alpine node --test test/termineZeit.test.js test/termineSlots.test.js test/termineEinstellungen.test.js test/termineIcs.test.js`).
- [ ] Ledger nach `/root/reports/terminplaner-tp1/`.

## Livegang (je Schritt Freigabe des Nutzers; der Nutzer pusht `main`)

1. **L1 Portal:** auf aktuelles `origin/main` rebasen, `npm test`, Push `feature/terminplaner:main` (Deploy installiert `feiertagejs`). Schalter `off` ⇒ keine Jobs, nichts sichtbar. Prüfen: `/api/public/termine/v1/aaaaaaaaaaaaaaaa/config` ⇒ `{"aktiv":false}`, `/api/termine/einstellungen` ohne Login 401, Log ohne Fehler.
2. **L2 Schema:** `docker exec -w /app webklar-kundenbereich-server node scripts/termine-setup.mjs --check`, dann ohne `--check`; erneut `--check` ⇒ nichts fehlt.
3. **L3 Schalter:** Compose (`kundenbereich-server`): `TERMINE_ENABLED=${TERMINE_ENABLED:-off}`, `TERMINE_PILOT_EMAILS=${TERMINE_PILOT_EMAILS:-}`; `/home/webklar/apps/.env` (Sicherung `.bak-termine`): `TERMINE_ENABLED=pilot`, `TERMINE_PILOT_EMAILS=kenso.gri@gmail.com`; `docker compose -f /home/webklar/apps/docker-compose.yml up -d --no-deps kundenbereich-server` (nie `preview-portal`).
4. **L4 WOMS:** Push `feature/terminplaner:test`; Bundle enthält „Terminplaner“.
5. **L5 Pilot:** WOMS Kunde „test“ → Funktionen → Terminplaner für „Test-Website“ aktivieren; Portal (Login des Testkunden): Vorlage, Leistungen, Zeiten, Betriebs-E-Mail kenso.gri@gmail.com; `WEBklar/test-website`: Seite „Termin buchen“ mit Widget + Datenschutz-Absatz-Entwurf, Push ⇒ Deploy; Testbuchungen: bestätigen, Anfrage annehmen/ablehnen, Erinnerung (Termin knapp über der Erinnerungszeit), absagen, verschieben, widerrufen, Kalender-Abo in Google.
6. **L6:** Nutzertest; Testbuchungen nach Wunsch löschen.