docs(adr): 0014 — Tour-System mit ElevenLabs-Voice + Web-Speech-Fallback
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.
This commit is contained in:
Dotty Dotter
parent
bf6201eb00
commit
9fc0619a20
183
docs/adr/0014-tour-system-mit-elevenlabs-voice.md
Normal file
183
docs/adr/0014-tour-system-mit-elevenlabs-voice.md
Normal file
@ -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).
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user