130 lines
7.7 KiB
Markdown
130 lines
7.7 KiB
Markdown
# Roadmap: Zauberwald
|
||
|
||
## Overview
|
||
|
||
Vier Phasen bauen die App von der spielbaren Kern-Tippmechanik (ohne API) über die Gemini-Integration und das vollständige Spielerlebnis bis hin zum Polish mit Audio. Nach Phase 4 ist die App bereit zum Testen mit dem Kind.
|
||
|
||
## Phases
|
||
|
||
**Phase Numbering:**
|
||
- Integer phases (1, 2, 3): Planned milestone work
|
||
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
||
|
||
Decimal phases appear between their surrounding integers in numeric order.
|
||
|
||
- [ ] **Phase 1: Grundgerüst + Tippmechanik** - Spielbare Tipp-Übung im Browser, komplett ohne API
|
||
- [ ] **Phase 2: Gemini-Integration + Asset-Pipeline** - Gemini-API für Text/Bild, generierte Character Assets eingebunden
|
||
- [ ] **Phase 3: Komplettes Spielerlebnis** - Alle 3 Übungsphasen verbunden, Wald wächst, Stufen 1–6 spielbar
|
||
- [ ] **Phase 4: Polish + Audio** - Animationen, Sounds, Export/Import — bereit fürs Kind
|
||
|
||
## Phase Details
|
||
|
||
### Phase 1: Grundgerüst + Tippmechanik
|
||
**Goal**: Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert
|
||
**Depends on**: Nothing (first phase)
|
||
**Requirements**: FNDN-01, FNDN-02, FNDN-03, FNDN-04, FNDN-05, ONBD-01, ONBD-02, ONBD-03, ONBD-04, KYBD-01, KYBD-02, KYBD-03, KYBD-04, KYBD-05, TYPE-01, TYPE-02, TYPE-03, TYPE-04, LEVL-01, LEVL-02, LEVL-03, FRST-04, FRST-05, PLSH-06
|
||
**Success Criteria** (what must be TRUE):
|
||
1. Die App startet via `npm run dev` und ist von aussen unter `http://<vps-ip>:5173` erreichbar
|
||
2. Begleitfigur und Tastatur-Layout sind wählbar und die Auswahl bleibt nach Browser-Reload erhalten
|
||
3. Stufe 1 (F, J, Leertaste) ist spielbar: Buchstaben erscheinen einzeln, richtiger Tastendruck loest sie auf, falscher Tastendruck tut nichts
|
||
4. Nach 10 richtigen Buchstaben gilt die Uebung als abgeschlossen und Stufe 2 wird freigeschaltet
|
||
5. Die Wald-Uebersicht zeigt den Stufenstatus (locked / current / completed) korrekt an
|
||
**Plans:** 5 plans
|
||
|
||
Plans:
|
||
- [x] 01-01-PLAN.md — Vite scaffold, project structure, CSS palette, TypeScript interfaces, IndexedDB wrapper
|
||
- [x] 01-02-PLAN.md — Screen management, welcome screen, companion/layout selection, onboarding persistence
|
||
- [x] 01-03-PLAN.md — QWERTZ keyboard component with finger colors, level definitions 1-6
|
||
- [x] 01-04-PLAN.md — Typing exercise engine (TDD), adaptive tempo, lesson screen UI
|
||
- [x] 01-05-PLAN.md — Forest overview with level map, full app flow integration, human verification
|
||
|
||
**UI hint**: yes
|
||
|
||
### Phase 2: Gemini-Integration + Asset-Pipeline
|
||
**Goal**: Gemini-API funktioniert fuer Text und Bild, Character Sheets sind generiert und eingebunden
|
||
**Depends on**: Phase 1
|
||
**Requirements**: GAPI-01, GAPI-02, GAPI-03, GAPI-04, GAPI-05, GAPI-06, ASST-01, ASST-02, ASST-03, ASST-04, COMP-01, COMP-02, COMP-03, COMP-04
|
||
**Success Criteria** (what must be TRUE):
|
||
1. `npm run generate-assets` generiert alle Character Sheets und Avatare erfolgreich in `src/assets/generated/`
|
||
2. Der Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter
|
||
3. Ein Begruessungstext der Begleitfigur wird generiert (deutsch, max 25 Woerter) oder ein Fallback-Text erscheint wenn kein API-Key vorhanden ist
|
||
4. Ein Waldelement-Bild kann mit Stil-Referenz generiert werden; bei fehlendem API-Key zeigt die App Fallback-Bilder ohne Absturz
|
||
**Plans:** 5 plans
|
||
|
||
Plans:
|
||
- [x] 02-01-PLAN.md — Config loader, Gemini API client (text + image), retry logic, rate-limiting (TDD)
|
||
- [x] 02-02-PLAN.md — Fallback texts (greetings, forest comments, letter intros) and fallback SVG images
|
||
- [x] 02-03-PLAN.md — IndexedDB store accessors, build script for asset generation, generate all character assets
|
||
- [x] 02-04-PLAN.md — Companion text module (getGreeting, getLetterIntro, getForestComment) with API-first fallback
|
||
- [x] 02-05-PLAN.md — Wire avatars into welcome screen, companion greeting on forest screen, visual verification
|
||
|
||
### Phase 3: Komplettes Spielerlebnis
|
||
**Goal**: Alle 3 Uebungsphasen verbunden, Wald waechst visuell, Stufen 1–6 vollstaendig spielbar
|
||
**Depends on**: Phase 2
|
||
**Requirements**: TYPE-05, TYPE-06, TYPE-07, LEVL-04, LEVL-05, LEVL-06, FRST-01, FRST-02, FRST-03, RWRD-01, RWRD-02, RWRD-03, RWRD-04, PRNT-01, PRNT-02, PRNT-03, PRNT-04
|
||
**Success Criteria** (what must be TRUE):
|
||
1. Eine komplette Uebungseinheit ist spielbar: Entdecken → Ueben → Woerter → Belohnung → zurueck zum Wald
|
||
2. Nach dem Belohnungs-Screen erscheint ein neues Bild im Wald und bleibt nach Reload erhalten
|
||
3. Alle Stufen 1–6 sind spielbar, jede mit passenden Woertern aus gelernten Buchstaben
|
||
4. Der Elternbereich ist erreichbar (Ctrl+Shift+E + "1234") und zeigt aktuelle Stufe, Einheiten, Uebungstage sowie Einstellungen
|
||
5. Review-Einheiten erscheinen jede 3. Uebung; nach 2× derselben Stufe zeigt die Begleitfigur Ermutigung
|
||
**Plans:** 5 plans
|
||
|
||
Plans:
|
||
- [x] 03-01-PLAN.md — Word lists per level, Progress type extension, rate limit update
|
||
- [x] 03-02-PLAN.md — Lesson 3-phase state machine (discover/practice/words), review + repetition logic
|
||
- [x] 03-03-PLAN.md — Forest visual scene (SVG background, 4x3 grid, element rendering from IndexedDB)
|
||
- [x] 03-04-PLAN.md — Reward screen with pre-generation, full flow wiring (lesson -> reward -> forest)
|
||
- [x] 03-05-PLAN.md — Parent area (access gate, stats overview, settings panel)
|
||
|
||
**UI hint**: yes
|
||
|
||
### Phase 4: Polish + Audio
|
||
**Goal**: Visuell und auditiv angenehmes Erlebnis, bereit zum Testen mit dem Kind
|
||
**Depends on**: Phase 3
|
||
**Requirements**: AUDI-01, AUDI-02, AUDI-03, AUDI-04, AUDI-05, PLSH-01, PLSH-02, PLSH-03, PLSH-04, PLSH-05, PRNT-05, PRNT-06, PRNT-07
|
||
**Success Criteria** (what must be TRUE):
|
||
1. Sounds spielen bei richtigem Tastendruck, Belohnung und neuem Waldelement; Mute-Button funktioniert und Zustand bleibt nach Reload
|
||
2. Buchstaben fallen sanft (keine ruckartigen Animationen), Sternenstaub-Animation erscheint bei Erfolg
|
||
3. Sprachausgabe liest Companion-Text vor wenn aktiviert (Web Speech API, Deutsch)
|
||
4. Export und Import funktionieren: Exportieren → Browser-Daten loeschen → Importieren → Fortschritt wiederhergestellt
|
||
5. Keine unbehandelten Exceptions in der Browser-Konsole bei normalem Gebrauch
|
||
**Plans:** 4 plans
|
||
|
||
Plans:
|
||
- [x] 04-01-PLAN.md — Audio system (Web Audio API sounds, Web Speech API speech, mute button)
|
||
- [x] 04-02-PLAN.md — Animation polish (leaf-fall, stardust, companion float), responsive, error handler
|
||
- [x] 04-03-PLAN.md — Export/Import/Reset in parent area
|
||
- [x] 04-04-PLAN.md — Wire audio into all screens, end-to-end human verification
|
||
|
||
**UI hint**: yes
|
||
|
||
### Phase 5: Multi-Wald-System: Wald-Pagination und Navigation zwischen Wäldern
|
||
|
||
**Goal:** Mehrere Waldseiten mit Pagination, damit der Wald unbegrenzt wachsen kann
|
||
**Depends on:** Phase 4
|
||
**Requirements**: MWLD-01, MWLD-02, MWLD-03, MWLD-04, MWLD-05, MWLD-06, MWLD-07
|
||
**Success Criteria** (what must be TRUE):
|
||
1. Bei mehr als 12 Waldelementen erscheinen Navigationspfeile und "Wald X von Y" Anzeige
|
||
2. Pfeiltasten navigieren zwischen Waldseiten mit sanfter Fade-Animation
|
||
3. Die aktuelle Waldseite wird in Progress gespeichert und nach Browser-Reload wiederhergestellt
|
||
4. Nach Lesson-Abschluss zeigt der Wald automatisch die Seite mit dem neuen Element
|
||
**Plans:** 2 plans
|
||
|
||
Plans:
|
||
- [ ] 05-01-PLAN.md — Progress type extension, paginated renderForestScene, navigation DOM and CSS
|
||
- [ ] 05-02-PLAN.md — Navigation handlers, page persistence, reward flow fix, human verification
|
||
|
||
## Progress
|
||
|
||
**Execution Order:**
|
||
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
|
||
|
||
| Phase | Plans Complete | Status | Completed |
|
||
|-------|----------------|--------|-----------|
|
||
| 1. Grundgerüst + Tippmechanik | 5/5 | Complete | - |
|
||
| 2. Gemini-Integration + Asset-Pipeline | 5/5 | Complete | - |
|
||
| 3. Komplettes Spielerlebnis | 5/5 | Complete | - |
|
||
| 4. Polish + Audio | 4/4 | Complete | - |
|
||
| 5. Multi-Wald-System | 0/2 | Planning complete | - |
|