Skip to content

Documentation

Jump to bottom
Matchelou38 edited this page Feb 19, 2026 · 1 revision

Documentation Technique : K3 Typing

K3 Typing est une application Android native développée en Kotlin, conçue pour l'entraînement à la dactylographie. Elle intègre un moteur de synthèse vocale (TTS) pour assister l'utilisateur et un système de suivi des performances (vitesse et précision).

1. Architecture Logicielle

L'application suit les principes de l'architecture MVVM (Model-View-ViewModel) recommandée par Google, garantissant une séparation stricte des responsabilités et une meilleure testabilité.

  • View (UI) : Développée intégralement avec Jetpack Compose. Elle est réactive et observe les états exposés par le ViewModel.
  • ViewModel : Agit comme médiateur. Il gère la logique métier, l'initialisation du moteur Text-To-Speech et la communication avec la base de données via des Coroutines.
  • Model : Géré par la bibliothèque Room, assurant la persistance des données localement dans une base SQLite.

2. Couche de Données (Model)

L'application utilise une base de données relationnelle locale pour stocker les textes d'entraînement et les résultats des utilisateurs.

2.1 Entités (Schéma de base de données)

TextEntity

Représente un texte disponible pour l'entraînement.

  • idText (Long) : Clé primaire auto-générée.
  • title (String) : Titre de l'exercice.
  • content (String) : Corps du texte à saisir.
  • category (String) : Classification (phrases, histoires, textes personnalisées).
  • difficulty (Int) : Niveau de difficulté (1 à 5).

SessionEntity

Enregistre les performances d'une session de test.

  • textId (Long) : Clé étrangère liée à TextEntity.
  • Contrainte : ON DELETE CASCADE (si un texte est supprimé, ses statistiques le sont aussi).
  • wpm (Double) : Mots par minute.
  • accuracy (Double) : Précision en pourcentage.
  • duration (Long) : Temps total en millisecondes.
  • timeStamp (Long) : Date de la session.

2.2 Data Access Object (TypingDao)

L'interface TypingDao définit les interactions SQL :

  • insertText / insertSession : Insertion de données.
  • getTextsByCategory : Filtrage dynamique des textes.
  • getAllSessions : Récupération de l'historique trié par date décroissante.

2.3 Initialisation (AppDatabase)

La base de données est implémentée via un Singleton thread-safe. Un RoomDatabase.Callback est utilisé pour pré-peupler la base lors du premier lancement avec des exemples de textes (Contes, phrases simples, etc.).

3. Logique Métier (ViewModel)

Le MainViewModel centralise les opérations lourdes et maintient l'état de l'interface.

3.1 Gestion de la Synthèse Vocale (TTS)

L'application implémente TextToSpeech.OnInitListener.

  • Vitesse de lecture : Fixée à $0.65f$ pour une élocution claire et adaptée à la saisie.
  • Transcription de la ponctuation : Avant la lecture, les symboles sont convertis en mots (ex: . devient "point", ? devient "point d'interrogation") pour guider précisément l'utilisateur.

3.2 Flux de Données (Reactive Streams)

Le ViewModel utilise StateFlow pour exposer les données :

  • texts : Liste des textes filtrés par la catégorie active.
  • sessions : Liste exhaustive des performances passées. Toutes les opérations de base de données sont lancées dans le viewModelScope pour éviter de bloquer le thread principal (UI).

4. Interface Utilisateur (View)

L'UI est découpée en modules fonctionnels dans MainActivity.kt.

4.1 Écran de Sélection (CategorySelectionScreen)

Permet la navigation et le choix de l'exercice :

  • Système de puces (FilterChip) : Filtre en temps réel les textes par catégorie.
  • Cartes interactives : Affiche un aperçu du texte et son titre.
  • Navigation : Accès direct vers l'ajout de texte personnalisé ou l'écran des statistiques.

4.2 Moteur de Test (TypingTest)

C'est le composant central gérant la logique de saisie :

  • Segmentation intelligente : Le texte est découpé en phrases via une expression régulière ((?<=[.!?])\s+). L'utilisateur progresse phrase par phrase.
  • Normalisation des caractères : Une fonction de nettoyage convertit les caractères spéciaux (apostrophes courbes, ligatures comme œ) en caractères standards pour éviter les erreurs de frappe injustifiées.
  • Validation visuelle : Le champ de saisie (OutlinedTextField) utilise l'état isError pour devenir rouge instantanément en cas de faute.
  • Calcul des scores : À la fin de l'exercice, la vitesse est calculée comme suit : $$WPM = \frac{(\text{Nombre de mots})}{\text{Durée en minutes}}$$

4.3 Ajout de Texte (AddTextScreen)

Un formulaire simple permettant d'étendre la bibliothèque de l'application. Les textes sont automatiquement classés dans la catégorie "textes personnalisées" et persistent en base de données.

4.4 Statistiques (StatsScreen)

Affiche l'historique des sessions sous forme de liste chronologique. Chaque session affiche la vitesse (WPM), la précision et l'identifiant du texte lié.

5. Spécifications Techniques

  • Langage : Kotlin
  • UI Framework : Jetpack Compose (Material 3)
  • Base de données : Room SQLite
  • Gestion des Threads : Kotlin Coroutines & Flow
  • SDK Minimum : API 21+ (Android 5.0)

Clone this wiki locally