From 9fc0619a2074d352b80a16449bb97d4268aef6c1 Mon Sep 17 00:00:00 2001
From: Dotty Dotter <dotty@Mac.wideopen.space>
Date: Sat, 9 May 2026 12:25:04 +0200
Subject: [PATCH] =?UTF-8?q?docs(adr):=200014=20=E2=80=94=20Tour-System=20m?=
 =?UTF-8?q?it=20ElevenLabs-Voice=20+=20Web-Speech-Fallback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architektur-Dokumentation der heutigen Session:
- Engine-Wahl (eigene Spotlight-Logik statt intro.js/shepherd.js)
- Pro-Page-Stations via window.GWOE_TOUR_STEPS
- Audio-Pipeline: ElevenLabs/Domi mit Server-Cache, Fallback auf
  Web Speech API
- Auto-Play-Block-Workaround (persistentes <audio> + User-Gesture-Unlock)
- CSP-Erweiterung: media-src 'self' data: blob:
- Konsequenzen positiv/negativ und Folge-Iterationen.
---
 .../0014-tour-system-mit-elevenlabs-voice.md  | 183 ++++++++++++++++++
 docs/adr/index.md                             |   1 +
 2 files changed, 184 insertions(+)
 create mode 100644 docs/adr/0014-tour-system-mit-elevenlabs-voice.md

diff --git a/docs/adr/0014-tour-system-mit-elevenlabs-voice.md b/docs/adr/0014-tour-system-mit-elevenlabs-voice.md
new file mode 100644
index 0000000..57220d2
--- /dev/null
+++ b/docs/adr/0014-tour-system-mit-elevenlabs-voice.md
@@ -0,0 +1,183 @@
+# 0014 — Tour-System mit ElevenLabs-Voice + Web-Speech-Fallback
+
+| | |
+|---|---|
+| **Status** | accepted |
+| **Datum** | 2026-05-09 |
+| **Refs** | #185, Commits 1c74cb8 → bf6201e |
+
+## Kontext
+
+Aus Issue #185 ("Bürger:innen-Perspektive: Was überfordert? Profi-Infos
+hinter Klick verstecken") kam die User-Anforderung, den Profi-Modus
+(v3-Antrag-Detail mit GWÖ-Score, Matrix 5×5, Marker-Pillen) für
+Erst-Besucher:innen erklärbar zu machen — **ohne** den Profi-Modus
+selbst zu vereinfachen.
+
+Anforderung wurde im Verlauf konkretisiert:
+
+1. Schaltfläche „Tour" auf jeder Seite außer Administration.
+2. „Du bist neu hier?"-Banner auf der Startseite, einmalig per
+   localStorage dismissable; Topbar-Tour-Link bleibt permanent.
+3. Pro Menüpunkt **eigene Stationen**, die die Funktionalität dieser
+   Page erklären (nicht eine generische Erklärung des Layouts).
+4. Sprachausgabe: weibliche, freundliche, warme, seriöse Stimme.
+   Phase 1: Web Speech API als MVP. Phase 2: ElevenLabs (Domi).
+5. Ermächtigend formulieren, nicht vereinfachend — Bürger:innen sollen
+   das Profi-Tool **lesen können**, nicht eine reduzierte Variante
+   bekommen.
+
+## Optionen
+
+### Option A — Externe Tour-Library (intro.js, shepherd.js, driver.js)
+
+Etabliertes Library-Ökosystem mit Spotlight-Effekt und Tour-Choreografie.
+
+**Vorteile:** weniger eigener Code, vertraute UX-Patterns.
+**Nachteile:** zusätzliche JS-Dependency (~30–80 KB gezippt), keine
+Audio-Integration, kein bürgernahes Wording out of the box, Styling
+anders als das übrige v2/v3-Design.
+
+### Option B — Eigene Spotlight-Engine, page-spezifische Stations
+
+Eine schlanke Tour-Engine in `app/templates/v3/components/tour.html`,
+~250 Zeilen JS + CSS. Stationen pro Page über `window.GWOE_TOUR_STEPS`
+gesetzt. Engine löst Selektoren zur Laufzeit auf und überspringt
+Stations, deren Element nicht im DOM ist (z.B. keine Plenum-Votes auf
+einer bestimmten Drucksache).
+
+**Vorteile:** keine externe Dependency, volle Kontrolle über Wording,
+eigenes Design (pill-shaped Buttons, teal-Farbgebung), enge
+Integration in CSP/Auth-Logik.
+**Nachteile:** Engine-Code muss selbst gepflegt werden.
+
+### Option C — Server-seitig generierte Tour-Texte pro User-Profil
+
+Backend bestimmt anhand des User-Profils (Erst-Visit, Eingeloggt,
+Bundesland-Filter), welche Stationen geladen werden. Mehr Personalisierung.
+
+**Vorteile:** maximale Anpassung.
+**Nachteile:** über-engineered für den Erst-Aufschlag; macht jede
+Tour-Iteration zum Server-Deploy.
+
+## Entscheidung
+
+**Option B** mit folgender Architektur:
+
+### Engine
+
+`app/templates/v3/components/tour.html` enthält UI (Overlay, Spotlight,
+Bubble, Mute-Toggle), Engine-Logik und CSS. Wird global in
+`v2/base.html` per Jinja-`{% include %}` eingebunden, nur ausgeschlossen
+für Administration:
+
+```jinja
+{% if v2_active_nav not in ['admin_stand', 'admin_queue', 'admin_abos',
+                            'freischaltungen', 'queue', 'abos'] %}
+{% include "v3/components/tour.html" ignore missing %}
+{% endif %}
+```
+
+### Stations pro Page
+
+Jedes Page-Template definiert seine Stationen am Anfang des
+`body_scripts`-Blocks:
+
+```html
+<script>
+window.GWOE_TOUR_STEPS = [
+  { selector: '.v3-bewertung',
+    title: 'Die Gemeinwohl-Note',
+    text: '…' },
+  { selector: '.v3-fraktionen',
+    title: 'Programm-Treue pro Fraktion',
+    text: '…' },
+];
+</script>
+```
+
+Selektoren mit Komma-separierter Fallback-Liste; Engine nimmt das erste
+Match und überspringt Stations ohne Match. Damit funktioniert die Tour
+auch, wenn ein Element auf manchen Drucksachen fehlt.
+
+Auth-spezifische Stations via Jinja: z.B. die Startseite hat
+unterschiedliche „Navigation links"-Texte je nach `is_authenticated`,
+weil die Sidebar unterschiedliche Items zeigt.
+
+### Fallback
+
+Pages ohne `window.GWOE_TOUR_STEPS` bekommen drei generische Stations
+(Logo+Konzept, Topbar, Sidebar) — damit der Topbar-Tour-Link überall
+einen Inhalt zeigt.
+
+### Audio: zwei Pfade
+
+**Phase 1** (Web Speech API): Browser-eingebaute TTS via
+`speechSynthesis`. Funktioniert ohne API-Key, klingt mechanisch.
+
+**Phase 2** (ElevenLabs/Domi):
+
+- Backend-Endpoint `GET /api/tour/voice?text=…`, ENV-konfiguriert
+  via `ELEVENLABS_API_KEY` und `ELEVENLABS_VOICE_ID`
+  (Default: Domi `AZnzlk1XvdvUeBnXmlld`).
+- Server-seitiges Caching: `data/tour_audio/<sha256(text|voice|model)>.mp3`.
+  Folgeabrufe gehen aus dem Datei-Cache, kein API-Quota-Verbrauch.
+- Frontend: `speak()` versucht erst den Endpoint. Bei 503 (kein API-Key)
+  oder Fehler Fallback auf Web Speech.
+- **Auto-Play-Block-Workaround**: persistentes `<audio>`-Element wird
+  einmal beim Tour-Start im Click-Handler (synchroner User-Gesture-Frame)
+  mit einer 1×1-silent-WAV als data-URL entsperrt. Spätere src-Updates
+  spielen dann ohne `NotAllowedError`.
+
+### Content-Security-Policy
+
+`media-src 'self' data: blob:;` ergänzt. `data:` für den Unlock-WAV,
+`blob:` für die ElevenLabs-MP3-Blob-URLs. Ohne diesen Eintrag blockt
+der Browser jeden `<audio>.play()`-Versuch.
+
+## Konsequenzen
+
+### Positiv
+
+- Tour-Engine ist auf jeder Page verfügbar (ausgenommen Administration),
+  ohne dass jede Page selbst die Engine einbindet.
+- Stationen pro Page sind deklarativ und page-lokal — pflegbar ohne
+  Backend-Deploy bei reinen Text-Änderungen.
+- Audio-Pipeline ist Cache-basiert und API-Quota-schonend (1 ElevenLabs-
+  Call pro einzigartigem Text-String über alle Sessions).
+- Web-Speech-Fallback macht den Code robust, wenn ElevenLabs ausfällt
+  oder der Key entfernt wird.
+- Mute-Toggle, ESC-Schließen und Pfeiltasten-Navigation sind Standard
+  ohne externe Library.
+
+### Negativ
+
+- Engine-Code wächst mit Features (~250 LOC heute). Bei zukünftigen
+  Tour-Erweiterungen muss eigene Pflege geleistet werden, statt sich
+  auf eine Library zu stützen.
+- ElevenLabs-Voices haben ein Free-Tier-Limit (10 k Zeichen/Monat).
+  Bei breiter Nutzung wäre ein Server-seitiges Rate-Limit zusätzlich
+  zum 30/min-Limit am Endpoint sinnvoll — heute reicht der Cache.
+- CSP-Erweiterung um `data:` und `blob:` für `media-src` erweitert die
+  Angriffsfläche minimal (Audio-Embed via XSS könnte missbraucht
+  werden). Risiko-Bewertung: niedrig, weil unsere Templates keine
+  user-generated Audio-Sources einbetten.
+
+### Folgen für andere ADRs
+
+- ADR 0008 (DDD-Lightweight): Tour-System ist UI-only, kein
+  Domain-Konzept; berührt die Schichten-Architektur nicht.
+- ADR 0012 (Debug-Auth-Token-Bypass): Tour-Tests in Playwright nutzen
+  den Bypass für headless E2E.
+- Methodik-Page (`/methodik`): Tour ist die *bürgernahe* Variante der
+  Methodik-Erklärung, beide bestehen nebeneinander — Methodik
+  ausführlich, Tour als 3-5-Stationen-Quickstart.
+
+## Folge-Iterationen (out of scope dieser ADR)
+
+- Verfeinerung der Tour-Texte pro Page (User-Feedback bei konkreten
+  Stations).
+- Weitere Voice-Settings (stability, similarity, speed) ggf. als
+  Cookie/UI-Toggle.
+- Auf Antrag-Detail eigene Stations je Konfidenz oder vorhandenen
+  Daten (z.B. zusätzliche Station bei vorhandenen Plenum-Votes).
diff --git a/docs/adr/index.md b/docs/adr/index.md
index c8f6229..2a7276d 100644
--- a/docs/adr/index.md
+++ b/docs/adr/index.md
@@ -30,6 +30,7 @@ und Konsequenzen. Format inspiriert von [Michael Nygard](https://cognitect.com/b
 | [0011](0011-aktuelle-themen-pm-generator.md) | Aktuelle-Themen-Dashboard mit PM-Generator (Persona-Prompt + Versionierung) | accepted | 2026-05-06 |
 | [0012](0012-debug-auth-token-bypass.md) | DEBUG_AUTH_TOKEN-Bypass für Diagnose-Sessions auf dev | accepted | 2026-05-06 |
 | [0013](0013-programme-legislaturen-zeitpunktige-bewertung.md) | Programme + Legislaturen mit zeitpunktiger Bewertung | accepted | 2026-05-08 |
+| [0014](0014-tour-system-mit-elevenlabs-voice.md) | Tour-System mit ElevenLabs-Voice + Web-Speech-Fallback | accepted | 2026-05-09 |
 
 ## Wann ADR, wann nicht