From 7f387882fb7ad017f04830c9105ace7f4e92be3e Mon Sep 17 00:00:00 2001 From: jamulix Date: Tue, 28 Oct 2025 12:39:53 +0100 Subject: [PATCH] Dokumentation auf v0.3.0 aktualisiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: Neue Features, Changelog und Formeln aktualisiert - HILFE.md: PrĂ€zisions-Anzeige, max_bpm_speed, Version - CLAUDE.md: Settings-Persistierung, UI-Design, Metronom-Timing - MIGRATIONS.md: Migration 5fcbe91de50b dokumentiert đŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 17 ++++++++++++++--- HILFE.md | 8 +++++--- MIGRATIONS.md | 12 ++++++++++++ README.md | 23 +++++++++++++++++++---- 4 files changed, 50 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4c5565d..383494e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -136,15 +136,23 @@ curl http://localhost:5000/debug - Target accuracy: 96% (configurable) - Tracks last 50 keystrokes to calculate rolling accuracy - Speed increases when accuracy is high, decreases when low +- Maximum speed configurable (default: 100 BPM) to prevent overwhelming users +- Runs independently with precise timing (Web Audio API, not setTimeout) - Implementiert in `metronome.js` mit zwei Klassen: - - `AdaptiveMetronome`: Geschwindigkeitsanpassungslogik - - `MetronomePlayer`: Audio-Wiedergabe und Timing + - `AdaptiveMetronome`: Geschwindigkeitsanpassungslogik mit `maxSpeed` option + - `MetronomePlayer`: Audio-Wiedergabe und prĂ€zises Timing **Visual Feedback**: - Green highlighting for correct characters - Red highlighting with orange overlay for incorrect characters - Blinking cursor shows current typing position +**UI Design (v0.3.0)**: +- Minimalistic statistics display without colorful badges +- Right-aligned values with consistent spacing +- Precision display (100 - error_rate) instead of error rate for positive feedback +- Uniform button colors: Blue (primary actions), Green (continue), Red (end) + ### Data Storage **Lessons**: `data/lessons.json` @@ -191,15 +199,18 @@ Time measurement starts with the first keystroke and runs continuously. All keys ## Configuration & Settings -**Metronome Settings** (stored in Flask session): +**Metronome Settings** (stored persistently in UserSettings database table): - `metronome_enabled`: Boolean for on/off - `metronome_bpm`: Beats per minute - `metronome_sound`: Sound type ('beep') - `metronome_mode`: 'automatic' or manual - `metronome_speed`: Base speed setting - `target_error_rate`: Target error percentage (default: 5%) +- `max_bpm_speed`: Maximum speed for adaptive metronome (default: 100 BPM) - prevents overwhelming users - `speed_display`: 'zpm' or 'wpm' for display preference +**Version Display**: Version number from VERSION file is displayed in the header using `APP_VERSION` template variable. + **Secret Key**: Update `app.secret_key` in `app.py:10` for production use. ## Database Schema Changes diff --git a/HILFE.md b/HILFE.md index 32b955a..c26f37f 100644 --- a/HILFE.md +++ b/HILFE.md @@ -139,7 +139,8 @@ Das Metronom reagiert so: ### Grenzen - **Minimum**: 40 BPM (Beats pro Minute) -- **Maximum**: 200 BPM +- **Maximum**: Konfigurierbar (Standard: 100 BPM, absolute Obergrenze: 200 BPM) +- **Einstellbar**: In den Einstellungen als "Maximale Metronom-Geschwindigkeit" --- @@ -153,7 +154,7 @@ Das Metronom reagiert so: | **Falsche Zeichen** | Fehler und Korrekturen | ZĂ€hler | | **TastaturanschlĂ€ge** | Alle Tasten inkl. Backspace | Gesamt | | **ZPM** | Zeichen pro Minute | (Korrekte Zeichen / Zeit) × 60 | -| **Fehler in %** | Fehlerrate | (Falsche / Gesamt) × 100 | +| **PrĂ€zision in %** | Genauigkeit der Eingabe | 100 - (Falsche / Gesamt) × 100 | | **WPM** | Wörter pro Minute | (Korrekte / 5) / (Zeit / 60) | ### Historische Statistiken @@ -314,6 +315,7 @@ Der Text scrollt **automatisch**, sodass: ### Metronom-Einstellungen - **Modus**: Automatisch / Manuell - **Geschwindigkeit**: BPM-Wert (bei Manuell) +- **Maximale Geschwindigkeit**: 40-200 BPM (Standard: 100) - verhindert Stress bei fehlerfreiem Tippen - **Sound**: Beep / Klick - **Ziel-Fehlerrate**: Anpassungsschwelle @@ -422,4 +424,4 @@ Der Text scrollt **automatisch**, sodass: --- -*Typewriter Trainer v0.2.0 - Mit ❀ entwickelt fĂŒr effektives Tipptraining* +*Typewriter Trainer v0.3.0 - Mit ❀ entwickelt fĂŒr effektives Tipptraining* diff --git a/MIGRATIONS.md b/MIGRATIONS.md index 4ca20be..3c4574a 100644 --- a/MIGRATIONS.md +++ b/MIGRATIONS.md @@ -79,6 +79,18 @@ alembic history --verbose alembic upgrade head ``` +## Migration History + +### 5fcbe91de50b - Add max_bpm_speed to UserSettings (v0.3.0) +- **Datum**: 2025-10-28 +- **Beschreibung**: FĂŒgt `max_bpm_speed` Spalte zur `user_settings` Tabelle hinzu +- **Typ**: Column Addition +- **Default**: 100 (BPM) +- **Zweck**: Ermöglicht Konfiguration der maximalen Metronom-Geschwindigkeit + +### 8f83d622eb4b - Initial migration +- **Beschreibung**: Initiale Datenbank-Struktur + ## Best Practices - Immer vor einer Migration ein Backup der Datenbank erstellen diff --git a/README.md b/README.md index 674d8c5..8f353e7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # đŸŽč Typewriter Tutor - Adaptiver Tipptrainer -**Version:** v0.2.0 _(siehe [VERSION](VERSION) Datei)_ +**Version:** v0.3.0 _(siehe [VERSION](VERSION) Datei)_ Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreichen Statistiken. Das Programm passt sich automatisch Ihrer Tippgeschwindigkeit an und hilft Ihnen, das Zehnfingerschreiben systematisch zu erlernen. @@ -12,13 +12,16 @@ Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreic - **Automatische Geschwindigkeitsanpassung**: Das Metronom passt sich dynamisch Ihrer Tippgeschwindigkeit an - **5 intelligente Anpassungsregeln**: Beschleunigt bei hoher Genauigkeit, bremst bei Fehlern - **Zielgenauigkeit**: HĂ€lt Sie im optimalen Bereich von 91-95% Genauigkeit +- **Konfigurierbare Obergrenze**: Maximale Geschwindigkeit einstellbar (Standard: 100 BPM) +- **PrĂ€zises Timing**: LĂ€uft unabhĂ€ngig von Tastatureingaben mit Web Audio API - **Zwei Modi**: - **Automatisch**: Adaptives Metronom (empfohlen) - **Explizit**: Feste Geschwindigkeit (40-200 BPM) - **Streak-Bonus**: Belohnt fehlerfreies Tippen mit höherer Geschwindigkeit ### 📊 **Umfangreiche Statistiken** -- **Echtzeit-Metriken**: ZPM (Zeichen/Minute), WPM (Wörter/Minute), Fehlerrate +- **Echtzeit-Metriken**: ZPM (Zeichen/Minute), WPM (Wörter/Minute), PrĂ€zision in % +- **Positive Darstellung**: PrĂ€zisions-Anzeige statt Fehlerrate fĂŒr motivierendes Feedback - **Detaillierte Diagramme**: Visualisierung Ihrer Fortschritte mit Chart.js - **Lektionsbasierte Auswertung**: Separate Statistiken fĂŒr jede Lektion - **Historische Daten**: Verfolgen Sie Ihre Entwicklung ĂŒber die Zeit @@ -30,6 +33,8 @@ Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreic - ✅ GrĂŒn fĂŒr korrekte Zeichen - ❌ Rot fĂŒr Fehler mit orangefarbener Anzeige des falsch eingegebenen Zeichens - 📍 Blinkender Cursor zeigt Ihre Position +- **Dezentes Design**: Schlichte, ablenkungsfreie Statistik-Anzeige ohne bunte Badges +- **Versionsnummer**: Im Header sichtbar fĂŒr bessere Nachvollziehbarkeit - **Dark/Light Mode**: Komfortable Arbeit bei Tag und Nacht - **Responsive Design**: Funktioniert auf Desktop und mobilen GerĂ€ten - **Hilfe-System**: Integrierte Hilfe mit detaillierten ErklĂ€rungen @@ -165,6 +170,7 @@ typewriter/ - **Modus**: Automatisch (adaptiv) oder Explizit (feste Geschwindigkeit) - **Geschwindigkeit**: 40-200 ZPM (nur im Explizit-Modus) - **Ziel-Fehlerrate**: 1-20% (nur im Automatik-Modus) +- **Maximale Geschwindigkeit**: 40-200 BPM (Standard: 100) - verhindert Überforderung bei fehlerfreiem Tippen **Statistik-Anzeige:** - **ZPM** (Zeichen pro Minute) oder **WPM** (Wörter pro Minute) @@ -180,7 +186,7 @@ Wörter pro Minute (WPM) = (Korrekte Zeichen / 5) / (Zeit in Minuten) Fehlerrate (%) = (Falsche TastenanschlĂ€ge / Gesamte TastenanschlĂ€ge) × 100 -Genauigkeit (%) = 100 - Fehlerrate +PrĂ€zision (%) = 100 - Fehlerrate ``` ### Statistik-Seite @@ -363,7 +369,16 @@ Contributions sind willkommen! Bitte: > **Hinweis:** Die aktuelle Versionsnummer wird zentral in der [VERSION](VERSION) Datei verwaltet. -### Version 0.2.0 (Aktuell) +### Version 0.3.0 (Aktuell) +- ✅ **Maximale Metronom-Geschwindigkeit**: Konfigurierbar (Standard: 100 BPM) zur Vermeidung von Überforderung +- ✅ **PrĂ€zisions-Anzeige**: Positive Darstellung (PrĂ€zision statt Fehlerrate) fĂŒr motivierendes Feedback +- ✅ **Persistente Settings**: Einstellungen werden in Datenbank gespeichert (nicht nur Session) +- ✅ **Metronom-Timing**: Web Audio API fĂŒr prĂ€zises, unterbrechungsfreies Timing +- ✅ **UI-Verbesserungen**: Dezente Statistik-Anzeige ohne bunte Badges, einheitliches Button-Design +- ✅ **Versionsnummer**: Im Header sichtbar +- ✅ **Alembic-Migration**: `max_bpm_speed` zur UserSettings-Tabelle hinzugefĂŒgt + +### Version 0.2.0 - ✅ **Streak-Statistik**: 30-Tage Balkendiagramm mit tĂ€glicher Übungszeit - ✅ **Persistente Einstellungen**: Alle Einstellungen und Lektion werden gespeichert - ✅ **Session-Ende**: Übersichtsseite mit Statistiken beim Beenden