115 lines
7.2 KiB
Markdown
115 lines
7.2 KiB
Markdown
# Phase 3: Komplettes Spielerlebnis - Context
|
||
|
||
**Gathered:** 2026-03-29 (assumptions mode)
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
Alle 3 Übungsphasen verbunden (Entdecken → Üben → Wörter → Belohnung), Wald wächst visuell mit KI-generierten Bildern, Stufen 1–6 vollständig spielbar mit Wortlisten, Elternbereich mit Statistik und Einstellungen. Kein Audio (Phase 4), keine erweiterten Animationen (Phase 4), kein Export/Import (Phase 4).
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Lesson Flow Architecture
|
||
- **D-01:** Sub-Phasen (Entdecken, Üben, Wörter) als interne State-Machine innerhalb `initLessonScreen`. DOM-Content wird im bestehenden `screen-lesson` Container getauscht. Kein neuer Screen — `ScreenName` bleibt bei 5 Einträgen. Lesson-State: `"discover" | "practice" | "words"`, Transitions via DOM-Swap im `letter-area` / `lesson-keyboard` Bereich.
|
||
- **D-02:** "Entdecken" Phase: Companion stellt neuen Buchstaben vor (via `getLetterIntro`), Taste leuchtet auf der Tastatur auf. Kind muss die Taste einmal drücken um fortzufahren. ~30 Sekunden.
|
||
- **D-03:** "Wörter bauen" Phase: Erweitert bestehende Typing-Engine mit mode "words". `createExerciseState` bekommt mode-Parameter und Wortliste. Wort wird ganz angezeigt, aktiver Buchstabe hervorgehoben. 3-4 Wörter pro Übung.
|
||
|
||
### Word Lists
|
||
- **D-04:** Statische Wortlisten pro Stufe in `src/game/words.ts`. Nur Buchstaben die bis zu dieser Stufe gelernt wurden, max 5 Zeichen. Mindestens 8-10 Wörter pro Stufe damit Variation möglich.
|
||
|
||
### Review Mechanic
|
||
- **D-05:** Jede 3. Übungseinheit ist automatisch ein Review: gemischte Buchstaben aus den letzten 2-3 Stufen. `totalSessions % 3 === 0` als Trigger. Review-Einheiten generieren auch Wald-Belohnungen.
|
||
- **D-06:** Wiederholungs-Schutz: Nach 2× derselben Stufe hintereinander zeigt Companion Ermutigung + Neugier-Trigger ("Magst du sehen, was als Nächstes kommt?"). Tracking via neues Feld `lastPlayedLevels: number[]` in Progress (letzte 3 gespielten Stufen).
|
||
|
||
### Forest Scene
|
||
- **D-07:** SVG-Hintergrund (statische Waldlandschaft) mit HTML-Overlay-Grid darüber. 4×3 CSS-Grid (12 Slots). Waldbilder als `<img>` mit Object URLs aus IndexedDB Blobs. Jedes neue Element bekommt nächsten freien Slot ± 10-20px Zufalls-Offset.
|
||
- **D-08:** Fade-in + Scale-up CSS-Animation für neue Elemente. Bestehende Elemente laden aus IndexedDB beim Forest-Screen-Init.
|
||
- **D-09:** Stufenkarte (Level-Map) bleibt erhalten, wird unter/neben dem Wald platziert.
|
||
|
||
### Reward Flow
|
||
- **D-10:** Flow nach Lesson: Üben-Ende → Reward-Screen → Forest. Nicht direkt zurück zum Forest.
|
||
- **D-11:** Pre-Generation: Bild-Generierung startet bei Lesson-Start (`startLessonFromForest`). Promise wird in Variable gespeichert. Reward-Screen awaited das Promise. Platzhalter "Der Wald denkt nach..." mit animierten Blättern wenn Bild noch nicht fertig.
|
||
- **D-12:** Reward-Screen zeigt: neues Waldelement-Bild + Companion-Kommentar (via `getForestComment`) + "Weiter üben" / "Zurück zum Wald" Buttons. Bei API-Fehler: Fallback-SVG als Waldelement.
|
||
|
||
### Rate Limiting
|
||
- **D-13:** Rate-Limit anpassen: Max 10 Text-Calls + 5 Bild-Calls pro Tag (statt je 1). Eine Übungseinheit braucht ~2 Text-Calls (Buchstaben-Vorstellung + Wald-Kommentar) + 1 Bild-Call. Kind macht max 2-3 Einheiten pro Tag.
|
||
|
||
### Parent Area
|
||
- **D-14:** Zugang: Ctrl+Shift+E öffnet Code-Eingabe, Code "1234" schaltet frei. Eigener Screen `screen-parent` (existiert als leere Section).
|
||
- **D-15:** Progress-Interface erweitern mit: `totalCorrect: number`, `totalErrors: number`, `errorKeyCounts: Record<string, number>`, `lastPlayedLevels: number[]`. Kein DB-Version-Bump nötig.
|
||
- **D-16:** `handleLessonComplete` muss Exercise-State (Genauigkeit, Fehler-Tasten) zusammen mit completedLevel übergeben, damit Stats persistiert werden.
|
||
- **D-17:** Elternbereich zeigt: aktuelle Stufe, abgeschlossene Einheiten (totalSessions), Übungstage (sessionDates als Kalender-Dots), durchschnittliche Genauigkeit, häufigste Fehlertasten.
|
||
- **D-18:** Einstellungen im Elternbereich: Layout-Wechsel (DE/CH), Audio an/aus (Platzhalter für Phase 4), Begleitfigur wechseln, API-Key Eingabe (Fallback wenn config.json fehlt).
|
||
|
||
### Claude's Discretion
|
||
- SVG-Waldlandschaft Design (Farben, Elemente, Stil)
|
||
- Exact CSS-Grid Layout für Forest-Elemente (Gap, Padding)
|
||
- Platzhalter-Animation ("Der Wald denkt nach...")
|
||
- Kalender-Dots Visualisierung im Elternbereich
|
||
- Word-Display UI (wie Wörter und aktiver Buchstabe dargestellt werden)
|
||
</decisions>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
- `SPEC.md` — Full specification, THE authoritative source
|
||
- `SPEC.md` section 3.1 — Mikro-Einheiten: 3 Phasen (Entdecken, Üben, Wörter)
|
||
- `SPEC.md` section 3.2 — Frustrations- und Perfektionismus-Handling
|
||
- `SPEC.md` section 4 — Progressionssystem, Freischaltung, Review-Mechanik
|
||
- `SPEC.md` section 5 — Waldwelt: visuelles Wachstum, Bild-Platzierung, Konsistenz
|
||
- `SPEC.md` section 7.1 — Screen-Struktur (Elternbereich Details)
|
||
- `src/game/typing.ts` — Typing engine (extend for word mode)
|
||
- `src/ui/screens.ts` — Lesson screen (extend for 3 sub-phases)
|
||
- `src/app.ts` — App flow (extend lesson-complete → reward → forest)
|
||
- `src/forest/scene.ts` — Forest screen (add visual grid)
|
||
- `src/companion/companion.ts` — Companion text functions
|
||
- `src/api/gemini.ts` — Image/text generation + rate limiting
|
||
- `src/storage/db.ts` — IndexedDB accessors
|
||
- `src/types.ts` — TypeScript interfaces (extend Progress)
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `src/game/typing.ts`: TypingExerciseState with letters array, currentLetterIndex, adaptive tempo — extend for word mode
|
||
- `src/api/gemini.ts`: generateText(), generateImage() with retry + rate-limiting — ready to use
|
||
- `src/companion/companion.ts`: getGreeting(), getLetterIntro(), getForestComment() — ready to use
|
||
- `src/companion/fallbacks.ts`: 10 greetings, 10 forest comments, 13 letter intros, getRandomFallbackImage()
|
||
- `src/storage/db.ts`: saveForestElement(), getForestElements(), saveStyleReference(), getStyleReference() — ready
|
||
- `src/assets/fallback-images/`: 7 SVG fallback images (blume, pilz, vogel, schmetterling, reh, baum, bach)
|
||
- `src/assets/style-reference/initial-forest-scene.png`: Style reference for image generation
|
||
|
||
### Established Patterns
|
||
- Screen toggling via showScreen() + CSS classes
|
||
- IndexedDB Promise wrappers with typed results
|
||
- Companion text: API-first + fallback pattern
|
||
- BEM CSS naming, pastel color palette via custom properties
|
||
|
||
### Integration Points
|
||
- `app.ts` handleLessonComplete — change flow: lesson → reward → forest, pass exercise stats
|
||
- `app.ts` startLessonFromForest — add pre-generation trigger
|
||
- `screens.ts` initLessonScreen — extend with sub-phase state machine
|
||
- `scene.ts` initForestScreen — add visual forest grid alongside level map
|
||
- `index.html` screen-reward — currently empty, needs content
|
||
- `index.html` screen-parent — currently empty, needs content
|
||
- `types.ts` Progress — add stats fields
|
||
</code_context>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
No specific requirements — open to standard approaches
|
||
</specifics>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
None — analysis stayed within phase scope
|
||
</deferred>
|