# Révision Sprint Plateforme scolaire d’entraînement Brevet/Bac avec annales QCM, fiches express, score automatique, historique et progression persistés via GenMB KV. ## Masterplan - Aider les élèves de 3e, Première et Terminale à s’entraîner vite sur des annales courtes par matière, chapitre, année et difficulté. - Proposer deux modes : **entraînement** avec feedback/correction immédiats et **examen** avec correction détaillée seulement à la fin. - Motiver la progression avec score %, note sur 20, moyenne, meilleur score, historique, espace élève et recommandations simples. - Persister les résultats par utilisateur GenMB Auth ; utiliser le propriétaire `guest` si l’élève n’est pas connecté. - Garder une SPA statique : catalogue local en JS, pas d’API applicative ni usage actuel de la base relationnelle. ## Tech Stack & Architecture - **Runtime** : application statique, sans bundler ni transpilation. - **React** : `react@19.2.0` et `react-dom@19.2.0/client` importés depuis `https://esm.sh`. - **Templates** : `htm` via `src/jsx.js`. Tous les composants rendent avec ``html`...` `` ; ne pas introduire de JSX brut. - **Routing** : `react-router-dom@7.13.0` avec `HashRouter` dans `src/mainProviders.js`. - `#/` - `#/matieres` - `#/matiere/:subjectId` - `#/exercice/:exerciseId?mode=train|exam` - `#/fiches` - `#/espace` - `#/historique` - **Providers** : `src/main.js` rend ``. `Providers` enveloppe `HashRouter > ThemeProvider > ToastProvider > AuthProvider`. - **State global** : Zustand `5.0.0` dans `src/store/useTrainingStore.js`, limité à `ownerId`, `results`, `totalSessions`, `loading`, `error`. - **Auth** : `AuthProvider` dans `src/mainProviders.js` utilise `window.genmb.auth` injecté par `index.html`. - Méthodes utilisées : `ready()`, `getUser()`, `signIn()`, `signOut()`, `onAuthStateChange(cb)`. - Le changement d’utilisateur déclenche dans `src/App.js` un `setOwner(user.id || 'guest')` puis `loadResults(ownerId)`. - **Persistence KV** : `src/store/useTrainingStore.js` utilise `window.genmb.kv`. - Résultat : `result:{ownerId}:{result.id}` - Compteur sessions : `stats:{ownerId}:attempts` - `ownerId` vaut `user.id` ou `guest`. - `clearResults()` supprime seulement les résultats du propriétaire courant. - **Données métier** : `src/data/exercises.js` exporte `subjects`, `exercises`, `courseSheets`. Le catalogue est local et consommé directement par les pages. - **UI** : Tailwind CDN dans `index.html` avec `darkMode: 'class'`, styles/tokens dans `styles/main.css`, icônes `lucide-react` depuis `esm.sh`. - **Gotchas** - En local hors GenMB, `window.genmb.kv` peut être absent : le store échouera lors de `loadResults`, `addResult`, `clearResults`. Ajouter un mock ou une garde avant tests locaux. - Ne pas remplacer les SDK GenMB injectés dans `index.html` par des packages npm. - Les tables relationnelles existent comme cible produit future, mais le code actuel n’utilise pas `window.genmb.db`. - Les imports CDN sont sensibles aux versions et au paramètre `?deps=react@19.2.0`; conserver cette cohérence. ## File Structure ```txt index.html Entrée HTML, Tailwind CDN, styles globaux, SDK GenMB Auth/KV, #root. styles/main.css Tokens clair/sombre HSL, surfaces, ombres, hero, animations, safe-area mobile. src/main.js Crée le root React et rend Providers + App. src/jsx.js Lie htm à React.createElement ; obligatoire pour tout rendu component. src/mainProviders.js HashRouter, ThemeProvider, ToastProvider, AuthProvider et hooks useToast/useTheme/useAuth. src/App.js Déclare les routes et recharge l’historique KV selon user.id ou guest. src/data/exercises.js Catalogue statique : matières Brevet/Bac, exercices QCM, corrections, fiches express. src/store/useTrainingStore.js Store Zustand + persistance KV des résultats et compteur de sessions. src/components/Layout.js Header sticky, navigation desktop/mobile, thème, auth, Outlet. src/components/Button.js Bouton partagé avec variants primary/secondary/destructive/ghost et loader. src/components/StatsCard.js Carte métrique utilisée par dashboard, historique et espace élève. src/pages/Dashboard.js Accueil, CTA, exercice aléatoire, stats globales et aperçu progression. src/pages/Subjects.js Liste des matières Brevet/Bac depuis subjects. src/pages/SubjectDetail.js Détail matière et exercices associés avec accès train/exam. src/pages/ExercisePage.js Session QCM, modes entraînement/examen, scoring, corrections, sauvegarde résultat. src/pages/CourseSheets.js Fiches express et liens vers quiz associé en entraînement/examen. src/pages/HistoryPage.js Historique des résultats et actions liées, dont suppression via store. src/pages/StudentSpace.js Espace élève, synthèse progression, recommandations/badges côté client. src/pages/NotFound.js 404 avec retour accueil. CLAUDE.md Documentation projet précédente ; maintenir alignée avec ce document. ``` ## Key Features - **Catalogue matières** - Source : `subjects` dans `src/data/exercises.js`. - Couvre Brevet : Mathématiques, Français, Histoire-Géo, EMC, Sciences. - Couvre Bac : Maths, Physique-Chimie, SVT, Histoire-Géo, Philosophie, Français Première, SES, NSI, HGGSP, LLCE, options. - Champs utilisés : `id`, `label`, `exam`, `level`, `accent`. - **Exercices QCM** - Source : `exercises` dans `src/data/exercises.js`. - Modèle actuel : - `id`, `subjectId`, `title`, `duration`, `difficulty`, `chapter`, `year`, `type`, `statement` - `questions[]` avec `id`, `prompt`, `choices[]`, `correct` index, `explanation`. - Les corrections détaillées sont intégrées à chaque question via `explanation`. - **Modes d’exercice** - URL : `#/exercice/:exerciseId?mode=train|exam`. - **Mode entraînement** : la correction doit être affichée au fil de l’eau après réponse. - **Mode examen** : pas de correction immédiate ; score et corrections à la fin. - Le calcul attendu est un pourcentage de bonnes réponses et une note sur 20 (`score / 5`, arrondie selon logique existante). - **Résultats et progression** - `useTrainingStore.addResult(result)` enrichit avec `ownerId`, persiste en KV, incrémente `stats:{ownerId}:attempts`, puis préfixe le résultat dans `results`. - Les pages calculent les statistiques côté client depuis `results` : moyenne, meilleur score, dernière session, agrégats par matière, niveau indicatif. - `Dashboard.js` utilise `results[0]` comme session la plus récente ; `loadResults()` trie par `createdAt` décroissant. - **Fiches express** - Source : `courseSheets` dans `src/data/exercises.js`. - `src/pages/CourseSheets.js` affiche durée, examen, matière, chapitre, points clés et deux liens : - `/exercice/${sheet.exerciseId}?mode=train` - `/exercice/${sheet.exerciseId}?mode=exam` - **Authentification** - Header dans `src/components/Layout.js` propose connexion/déconnexion GenMB. - Les résultats invités restent sous `guest`; ils ne sont pas automatiquement fusionnés après connexion. - **Backend / API** - Pas d’API métier propre. - Surface externe réellement utilisée : - `window.genmb.auth.ready(): Promise` - `window.genmb.auth.getUser(): User|null` - `window.genmb.auth.signIn(): Promise` - `window.genmb.auth.signOut(): Promise` - `window.genmb.auth.onAuthStateChange(cb): unsubscribe` - `window.genmb.kv.list(prefix): Promise<{data: Array<{key,value}>}>` - `window.genmb.kv.get(key)` - `window.genmb.kv.set(key, value)` - `window.genmb.kv.increment(key, amount)` - `window.genmb.kv.delete(key)` ## Design Guidelines - **Style général** : moderne, scolaire premium, motivant, avec cartes arrondies, surfaces douces, ombres légères et micro-transitions. - **Couleurs** : utiliser exclusivement les tokens HSL CSS de `styles/main.css` via Tailwind arbitrary values : - `--background`, `--foreground`, `--card`, `--popover` - `--primary`, `--secondary`, `--accent` - `--success`, `--warning`, `--info`, `--destructive` - `--muted`, `--border`, `--ring` - **Dark mode** : piloté par classe `dark` sur `` dans `ThemeProvider`; préférence stockée dans `localStorage` clé `revision-theme`. - **Typographie** : police système via CSS/Tailwind, titres en `font-semibold`/`font-bold` avec `tracking-tight`. - **Layout responsive** - Conteneur principal : `max-w-7xl`, padding `px-4 sm:px-6 lg:px-8`. - Header desktop avec nav complète dès `lg`. - Bottom nav mobile fixe dans `Layout.js`, visible sous `md`, avec `safe-bottom`. - Prévoir assez de padding bas dans les pages à cause de la navigation mobile. - **Interactions** - Boutons primaires : `Button.js` ou classes équivalentes avec focus ring accessible. - Animations légères : hover translate/ombre, loaders `Loader2`, barres de progression. ## App Flow - **Démarrage** 1. `index.html` charge CDN, CSS, SDK GenMB et `src/main.js`. 2. `main.js` monte `Providers` et `App`. 3. `AuthProvider` attend `window.genmb.auth.ready()`. 4. `App.js` charge les résultats KV pour `user.id` ou `guest`. - **Parcours principal** 1. Accueil `Dashboard.js`. 2. CTA vers `/matieres` ou exercice aléatoire en `mode=exam`. 3. Choix d’une matière dans `Subjects.js`. 4. Détail dans `SubjectDetail.js`. 5. Lancement d’un exercice en entraînement ou examen. 6. Fin de session : score, note sur 20, corrections détaillées, sauvegarde KV. 7. Consultation dans `/historique` ou `/espace`. - **Parcours fiches** 1. `/fiches` liste les fiches express. 2. L’élève lit les points clés. 3. Il lance le quiz associé en mode entraînement ou examen via `sheet.exerciseId`. - **Edge cases** - Exercice inconnu : `ExercisePage.js` doit rediriger ou afficher un état introuvable plutôt que crasher. - Aucun résultat : dashboard/espace/historique doivent afficher des états vides motivants. - KV indisponible : afficher toast d’erreur via `useToast()` ; ne pas bloquer la navigation statique. - Utilisateur non connecté : expérience complète possible, mais historique isolé sous `guest`. - Changement de compte : recharger `results` pour le nouvel `ownerId`, ne pas mélanger avec l’ancien état. ## Conventions - **Rendu** - Toujours importer `html` depuis `src/jsx.js`. - Syntaxe composant : `html`<${Component} prop=${value} />``. - Ne pas utiliser de JSX, de build step, ni d’imports npm locaux. - **Imports CDN** - React : `https://esm.sh/react@19.2.0` - React Router : `https://esm.sh/react-router-dom@7.13.0?deps=react@19.2.0` - Zustand : `https://esm.sh/zustand@5.0.0?deps=react@19.2.0` - Lucide : `https://esm.sh/lucide-react?deps=react@19.2.0` - **Données** - Ajouter une matière dans `subjects`, puis des exercices avec `subjectId` identique. - Ajouter une fiche dans `courseSheets` avec un `exerciseId` existant. - Les `id` sont des slugs stables utilisés dans les URLs et résultats ; ne pas les renommer sans migration KV. - **Résultats** - Un résultat doit inclure au minimum : `id`, `exerciseId`, `title`, `subject`, `score`, `note20`, `mode`, `createdAt`. - `createdAt` doit être numérique ou comparable pour le tri décroissant. - **Styles** - Privilégier les classes Tailwind avec tokens `hsl(var(--...))`. - Pour un motif réutilisable, créer un petit composant dans `src/components/` plutôt que dupliquer un gros bloc. - Utiliser `Button.js` pour les actions standard ; garder les liens stylés localement quand ils naviguent. - **Ajouter une page** 1. Créer `src/pages/NouvellePage.js`. 2. Exporter une fonction composant utilisant `html`. 3. Importer dans `src/App.js` et ajouter une ``. 4. Ajouter l’entrée à `navItems` dans `src/components/Layout.js` seulement si elle fait partie de la navigation principale. 5. Vérifier mobile : bottom nav ne contient volontairement que Accueil, Matières, Résultats, Espace. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.