gurix/Zauberwald
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
197ec24aa28fd126771a3100e23c7dca21121679
Zauberwald/.planning/REQUIREMENTS.md
T

9.9 KiB
Raw Blame History

Requirements: Zauberwald

Defined: 2026-03-29 Core Value: Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt.

v1 Requirements

Requirements for initial release (MVP). Each maps to roadmap phases.

Foundation

  • FNDN-01: Vite-Projekt mit vanilla-ts Template, TypeScript strict mode, Biome Lint, Vitest
  • FNDN-02: Projektstruktur gemäss Spec Abschnitt 13 (alle Verzeichnisse + Dateien)
  • FNDN-03: Alle TypeScript-Interfaces definiert (Progress, ForestElement, CompanionAssets, Level, etc.)
  • FNDN-04: IndexedDB-Wrapper mit allen Stores (progress, companionAssets, styleReference, forestElements, settings)
  • FNDN-05: Screen-Management: 5 Screens (welcome, forest, lesson, reward, parent), CSS fade Transitions

Onboarding

  • ONBD-01: Willkommens-Screen mit Begleitfigur-Auswahl (4 Karten mit Avataren)
  • ONBD-02: Tastatur-Layout-Auswahl (DE/CH) im Willkommens-Screen
  • ONBD-03: Auswahl persistiert in IndexedDB, wird nach Reload wiederhergestellt
  • ONBD-04: "Los geht's" führt direkt zur Wald-Übersicht (kein Ladescreen)

Keyboard

  • KYBD-01: Bildschirmtastatur rendert vollständiges QWERTZ-Layout
  • KYBD-02: Tasten zeigen Fingerfarben gemäss Farbpalette (8 Fingerfarben + Daumen)
  • KYBD-03: Aktive Taste pulsiert sanft, gedrückte Taste zeigt Press-Animation
  • KYBD-04: Noch nicht gelernte Tasten sind ausgegraut
  • KYBD-05: Beide Layouts (DE/CH) als Daten hinterlegt und umschaltbar

Typing

  • TYPE-01: Phase "Üben": Buchstaben erscheinen einzeln (CSS-Animation fallend), 8–12 pro Übung
  • TYPE-02: Richtiger Tastendruck löst Buchstaben auf (Sternenstaub-Animation)
  • TYPE-03: Falscher Tastendruck: Nichts passiert, richtige Taste blinkt sanft auf Tastatur
  • TYPE-04: Adaptives Tempo: Start 3s, nach 2× richtig -200ms (min 1.5s), nach Fehler +500ms (max 4s)
  • TYPE-05: Phase "Entdecken": Begleitfigur stellt neuen Buchstaben vor, Taste leuchtet auf
  • TYPE-06: Phase "Wörter bauen": 3–4 Wörter aus gelernten Buchstaben, Buchstabe für Buchstabe tippen
  • TYPE-07: Alle 3 Phasen fliessend verbunden: Entdecken → Üben → Wörter → Belohnung

Levels

  • LEVL-01: Stufen 1–6 definiert gemäss Progressionstabelle (F/J bis E/I)
  • LEVL-02: Stufe gilt als abgeschlossen nach einmaligem Durchspielen (nicht perfekt)
  • LEVL-03: Nächste Stufe sofort freigeschaltet, alle gespielten Stufen wiederholbar
  • LEVL-04: Wortlisten pro Stufe (nur mit bereits gelernten Buchstaben, max 5 Buchstaben)
  • LEVL-05: Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
  • LEVL-06: Wiederholungs-Schutz: Nach 2× gleicher Stufe Ermutigung + Neugier-Trigger

Gemini API

  • GAPI-01: Config-Loader: public/config.json via fetch laden, typisiertes Interface
  • GAPI-02: Text-API-Client: generateText(prompt, systemPrompt) mit Retry und Fehlerbehandlung
  • GAPI-03: Bild-API-Client: generateImage(prompt, referenceImages[]) mit Character Consistency
  • GAPI-04: Fallback-Texte: 10 Begrüssungen, 10 Wald-Kommentare, Buchstaben-Vorstellungen Stufe 1–6
  • GAPI-05: Fallback-Bilder: 5–10 statische SVG/PNG-Bilder als Backup
  • GAPI-06: Rate-Limiting: Max 1 Bild + 1 Text pro Übungseinheit

Assets

  • ASST-01: Build-Script scripts/generate-assets.ts generiert 4 Character Sheets + 4 Avatare + 1 Stil-Referenz
  • ASST-02: Generierte Assets in src/assets/companions/ und src/assets/style-reference/ eingecheckt
  • ASST-03: Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter
  • ASST-04: Companion-Area in Übung zeigt Avatar der gewählten Figur

Forest

  • FRST-01: Waldszene: SVG-Hintergrund + 4×3 Grid für generierte Bilder
  • FRST-02: Neue Elemente mit fade-in + scale-up Animation
  • FRST-03: Alle bisherigen Elemente aus IndexedDB geladen und angezeigt
  • FRST-04: Stufenkarte: Level-Grid mit Status (locked/current/completed)
  • FRST-05: "Weiter üben" Button startet nächste offene Stufe

Companion

  • COMP-01: Begrüssungstext bei App-Start (KI-generiert, tageszeit-abhängig, oder Fallback)
  • COMP-02: Buchstaben-Vorstellungstext (KI-generiert mit Eselsbrücke, oder Fallback)
  • COMP-03: Waldbelohnungs-Kommentar (KI-generiert, Staunen + Freude, oder Fallback)
  • COMP-04: Alle Texte max 25 Wörter, einfache Sprache, kein Leistungslob, kein Englisch

Reward

  • RWRD-01: Belohnungs-Screen nach jeder Einheit: Neues Waldelement-Bild + Companion-Kommentar
  • RWRD-02: Pre-Generation: Bild wird während Übung im Hintergrund generiert
  • RWRD-03: Placeholder bei Wartezeit ("Der Wald denkt nach..." mit animierten Blättern)
  • RWRD-04: "Weiter üben" / "Zurück zum Wald" Buttons

Parent Area

  • PRNT-01: Zugang via Ctrl+Shift+E + Code "1234"
  • PRNT-02: Übersicht: Aktuelle Stufe, abgeschlossene Einheiten, Übungstage (Kalender-Dots)
  • PRNT-03: Statistik: Durchschnittliche Genauigkeit, häufigste Fehlertasten (nur hier sichtbar)
  • PRNT-04: Einstellungen: Layout-Wechsel, Audio an/aus, Begleitfigur wechseln, API-Key
  • PRNT-05: Export: Fortschritt als JSON (ohne Blobs)
  • PRNT-06: Import: JSON hochladen mit Validierung
  • PRNT-07: Reset: Alles löschen mit doppelter Bestätigung

Audio

  • AUDI-01: Richtiger Tastendruck: Kurzer heller Ton (800Hz, 0.1s, Web Audio API)
  • AUDI-02: Belohnung: Aufsteigende Tonfolge (0.8s)
  • AUDI-03: Neues Waldelement: Glitzer-Sound (weisses Rauschen gefiltert, 0.5s)
  • AUDI-04: Mute-Button immer sichtbar, Zustand persistiert
  • AUDI-05: Optionale Sprachausgabe via Web Speech API (Deutsch, Rate 0.9, Pitch 1.1)

Polish

  • PLSH-01: Fallende Buchstaben als sanft schwebende CSS-Animation (wie Blätter)
  • PLSH-02: Erfolg-Animation: Sternenstaub/Glitzer via CSS particles
  • PLSH-03: Begleitfigur-Avatar: Float-Animation (sanftes Schweben)
  • PLSH-04: Responsive bis 700px Breite (Tastatur verkleinert, Fonts skalieren)
  • PLSH-05: Globaler Error-Handler: Kindgerechte Fehlermeldung, kein Crash
  • PLSH-06: CSS-Palette + Typografie vollständig gemäss Spec (Custom Properties, Quicksand, Nunito)

v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

Extended Levels

  • ELVL-01: Stufen 7–15 (untere Reihe, Grossbuchstaben, Zahlen, Sonderzeichen)
  • ELVL-02: Ganze Sätze tippen

Extended Features

  • EXTF-01: "Freies Schreiben"-Modus (Brief an Begleitfigur)
  • EXTF-02: Saisonale Wald-Themen
  • EXTF-03: Begleitfigur reagiert auf längere Abwesenheit
  • EXTF-04: Druckbare Urkunden

Out of Scope

Feature Reason
Mobile Support Desktop-only, Kind nutzt Linux-Laptop
OAuth/Social Login Einzelnutzerin, kein Nutzersystem
Backend/Server Rein clientseitig, IndexedDB für Persistenz
Echtzeit-Chat Irrelevant für Einzelnutzung
Video-Inhalte Storage/Bandwidth, unnötig
Canvas/WebGL Rendering DOM-basiert einfacher für generierte PNGs
CSS Framework (Tailwind etc.) Einzelne main.css ausreichend
Google SDK Eigener typisierter REST-Client via fetch

Traceability

Which phases cover which requirements. Updated during roadmap creation.

Requirement Phase Status
FNDN-01 Phase 1 Complete
FNDN-02 Phase 1 Complete
FNDN-03 Phase 1 Complete
FNDN-04 Phase 1 Complete
FNDN-05 Phase 1 Complete
ONBD-01 Phase 1 Complete
ONBD-02 Phase 1 Complete
ONBD-03 Phase 1 Complete
ONBD-04 Phase 1 Complete
KYBD-01 Phase 1 Complete
KYBD-02 Phase 1 Complete
KYBD-03 Phase 1 Complete
KYBD-04 Phase 1 Complete
KYBD-05 Phase 1 Complete
TYPE-01 Phase 1 Complete
TYPE-02 Phase 1 Complete
TYPE-03 Phase 1 Complete
TYPE-04 Phase 1 Complete
LEVL-01 Phase 1 Complete
LEVL-02 Phase 1 Complete
LEVL-03 Phase 1 Complete
FRST-04 Phase 1 Complete
FRST-05 Phase 1 Complete
PLSH-06 Phase 1 Complete
GAPI-01 Phase 2 Pending
GAPI-02 Phase 2 Pending
GAPI-03 Phase 2 Pending
GAPI-04 Phase 2 Complete
GAPI-05 Phase 2 Complete
GAPI-06 Phase 2 Pending
ASST-01 Phase 2 Pending
ASST-02 Phase 2 Pending
ASST-03 Phase 2 Pending
ASST-04 Phase 2 Pending
COMP-01 Phase 2 Pending
COMP-02 Phase 2 Pending
COMP-03 Phase 2 Pending
COMP-04 Phase 2 Pending
TYPE-05 Phase 3 Pending
TYPE-06 Phase 3 Pending
TYPE-07 Phase 3 Pending
LEVL-04 Phase 3 Pending
LEVL-05 Phase 3 Pending
LEVL-06 Phase 3 Pending
FRST-01 Phase 3 Pending
FRST-02 Phase 3 Pending
FRST-03 Phase 3 Pending
RWRD-01 Phase 3 Pending
RWRD-02 Phase 3 Pending
RWRD-03 Phase 3 Pending
RWRD-04 Phase 3 Pending
PRNT-01 Phase 3 Pending
PRNT-02 Phase 3 Pending
PRNT-03 Phase 3 Pending
PRNT-04 Phase 3 Pending
AUDI-01 Phase 4 Pending
AUDI-02 Phase 4 Pending
AUDI-03 Phase 4 Pending
AUDI-04 Phase 4 Pending
AUDI-05 Phase 4 Pending
PLSH-01 Phase 4 Pending
PLSH-02 Phase 4 Pending
PLSH-03 Phase 4 Pending
PLSH-04 Phase 4 Pending
PLSH-05 Phase 4 Pending
PRNT-05 Phase 4 Pending
PRNT-06 Phase 4 Pending
PRNT-07 Phase 4 Pending

Coverage:

  • v1 requirements: 68 total
  • Mapped to phases: 68
  • Unmapped: 0 ✓

Requirements defined: 2026-03-29 Last updated: 2026-03-29 after roadmap creation (coverage confirmed: 68/68)

Reference in New Issue View Git Blame Copy Permalink