99 lines
5.9 KiB
Markdown
99 lines
5.9 KiB
Markdown
# Zauberwald
|
||
|
||
## What This Is
|
||
|
||
Zauberwald ist eine Webapplikation, die einem 7-jährigen Kind das 10-Finger-Tastaturschreiben beibringt. Die App verbindet strukturiertes Tipptraining mit einer dynamisch wachsenden, KI-generierten Waldwelt. Fester Übungsrahmen, überraschende Belohnungen — Neugier statt Leistungsdruck.
|
||
|
||
## Core Value
|
||
|
||
Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt oder Sterne verdient.
|
||
|
||
## Requirements
|
||
|
||
### Validated
|
||
|
||
- [x] Bildschirmtastatur: QWERTZ-Layout (DE/CH), Fingerfarben-Zonen, aktive Taste pulsiert — *Validated in Phase 1*
|
||
- [x] Progressionssystem: Stufen 1–6 definiert und spielbar — *Validated in Phase 1*
|
||
- [x] Kein sichtbarer Leistungsdruck: Keine Scores, Timer, Fehler-Zähler in der Übung — *Validated in Phase 1*
|
||
|
||
### Active
|
||
|
||
- [ ] Mikro-Einheiten: 3 Phasen (Entdecken → Üben → Wörter bauen), je 90–120 Sekunden
|
||
- [ ] Kein sichtbarer Leistungsdruck: Keine Scores, Timer, Fehler-Zähler. Fortschritt nur über wachsenden Wald
|
||
- [ ] Bildschirmtastatur: QWERTZ-Layout (DE/CH), Fingerfarben-Zonen, aktive Taste pulsiert
|
||
- [ ] Progressionssystem: 15 Stufen (Grundreihe → Ober → Unter → Sonderzeichen), Stufen 1–6 im MVP
|
||
- [ ] Begleitfigur: 4 Charaktere (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) mit KI-generierten Dialogen
|
||
- [ ] Waldwelt: KI-generierte Bilder (Gemini) als Belohnung nach jeder Einheit, dauerhaft gecacht
|
||
- [ ] Visuelle Konsistenz: Character Sheets als Referenzbilder, Stil-Referenzbild für alle Generierungen
|
||
- [ ] Adaptives Tempo: Heuristik ±200/500ms, Bereich 1.5–4s, kein sichtbarer Timer
|
||
- [ ] Fehler sind unsichtbar: Falscher Tastendruck → nichts passiert, richtige Taste blinkt sanft
|
||
- [ ] Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
|
||
- [ ] Perfektionismus-Schutz: Nach 2× Wiederholung Ermutigung + Neugier-Trigger
|
||
- [ ] Elternbereich: Ctrl+Shift+E + Code "1234", Fortschrittsstatistik, Export/Import, Einstellungen
|
||
- [ ] Audio: Web Audio API Sounds (Tastendruck, Belohnung, Waldelement), optionale Sprachausgabe via Web Speech API
|
||
- [ ] Pre-Generation: Belohnungsbild wird während Übung im Hintergrund generiert
|
||
- [ ] Fallback-System: Statische Bilder + Texte wenn API nicht verfügbar
|
||
|
||
### Out of Scope
|
||
|
||
- Stufen 7–15 (untere Reihe, Grossbuchstaben, Zahlen, Sonderzeichen) — MVP fokussiert auf Stufen 1–6
|
||
- Ganze Sätze tippen — erst relevant nach allen Buchstaben
|
||
- "Freies Schreiben"-Modus — späterer Milestone
|
||
- Saisonale Wald-Themen — nice-to-have, nicht MVP
|
||
- Begleitfigur reagiert auf längere Abwesenheit — späterer Milestone
|
||
- Druckbare Urkunden — nicht MVP
|
||
- Mobile Support — Desktop-only, Kind nutzt Linux-Laptop
|
||
- OAuth/Social Login — kein Nutzersystem nötig, eine Nutzerin
|
||
- Echtzeit-Chat — irrelevant für Einzelnutzung
|
||
- Video-Inhalte — Storage/Bandwidth, unnötig
|
||
|
||
## Context
|
||
|
||
- **Primäre Nutzerin**: 7 Jahre, 1. Klasse, vermuteter ADHS-Hintergrund (nicht diagnostiziert). Niedrige Frustrationstoleranz, impulsiv, Perfektionismus-Neigung. Max. 5 Min. Übungsdauer. Interessen: Tiere, Feen, Einhörner, Magie, Natur.
|
||
- **Technischer Kontext**: Linux-Laptop, Desktop-Browser, stabile Internetverbindung. Einzige Nutzerin.
|
||
- **Entwicklungsumgebung**: VPS (kein lokaler Rechner). Vite Dev-Server muss auf 0.0.0.0 lauschen, Port 5173. Papa testet via `http://<vps-ip>:5173`.
|
||
- **Pädagogisches Prinzip**: Genauigkeit vor Geschwindigkeit. Kein negatives Feedback jeglicher Art. Neugier als Motor.
|
||
- **Gemini API**: Key in `public/config.json` (nicht in Git). Text: gemini-2.5-flash. Bild: gemini-3.1-flash-image-preview (Nano Banana 2). Character Consistency via Referenzbilder.
|
||
- **Asset-Pipeline**: Character Sheets + Avatare werden vorab per Build-Script generiert und eingecheckt. Kein Onboarding-Warten.
|
||
|
||
## Constraints
|
||
|
||
- **Tech Stack**: Vanilla TypeScript, Vite 6.x, kein Framework. Einzelne main.css mit CSS Custom Properties. Biome für Lint. Vitest für Tests.
|
||
- **API**: Gemini REST via fetch(), kein Google SDK. Key im Frontend akzeptabel (private Nutzung).
|
||
- **Datenhaltung**: IndexedDB (Bilder als Blobs). Kein Backend, kein Server.
|
||
- **Layout**: QWERTZ DE + CH. Unterschiede erst ab Stufe 14+ relevant.
|
||
- **Styling**: Pastellfarben, Aquarell-Stil, Quicksand + Nunito Fonts, min. 16px. Sanfte Animationen.
|
||
- **VPS-Deployment**: `--host 0.0.0.0`, Port 5173 (dev) / 4173 (preview). Kein HTTPS nötig.
|
||
|
||
## Key Decisions
|
||
|
||
| Decision | Rationale | Outcome |
|
||
|----------|-----------|---------|
|
||
| Vanilla TypeScript statt Framework | Minimale Komplexität, kein Framework-Overhead | — Pending |
|
||
| DOM-basierte Waldszene (img über SVG) | Einfachste Lösung für generierte PNGs, kein Canvas/WebGL | — Pending |
|
||
| Raster 4×3 mit ±20px Variation für Bildplatzierung | Vorhersehbar, kein Overlap | — Pending |
|
||
| Gemini 3.1 Flash Image Preview für Bilder | Neuestes Modell, Character Consistency, wird nicht abgeschaltet | — Pending |
|
||
| Web Speech API statt Gemini TTS | Gratis, offline-fähig, kein extra API-Call | — Pending |
|
||
| Vorab-generierte Character Assets | Kein Onboarding-Warten, volle Kontrolle über Qualität | — Pending |
|
||
| Adaptives Tempo Heuristik statt ML | Einfach implementierbar, ausreichend für den Zweck | — Pending |
|
||
|
||
## Evolution
|
||
|
||
This document evolves at phase transitions and milestone boundaries.
|
||
|
||
**After each phase transition** (via `/gsd:transition`):
|
||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||
2. Requirements validated? → Move to Validated with phase reference
|
||
3. New requirements emerged? → Add to Active
|
||
4. Decisions to log? → Add to Key Decisions
|
||
5. "What This Is" still accurate? → Update if drifted
|
||
|
||
**After each milestone** (via `/gsd:complete-milestone`):
|
||
1. Full review of all sections
|
||
2. Core Value check — still the right priority?
|
||
3. Audit Out of Scope — reasons still valid?
|
||
4. Update Context with current state
|
||
|
||
---
|
||
*Last updated: 2026-03-29 after Phase 1 completion — Grundgerüst + Tippmechanik*
|