# TimeCredit Quiz — Brief de portage Android

*À coller au démarrage d'un fil Claude Code dédié, dans le projet Android. Ce
document est autoportant, mais **l'app iOS est la source de vérité** : pour tout
détail de comportement, lis le fichier Swift correspondant (chemins ci-dessous).*

---

## 0. Règle d'or

- **Reproduire l'app iOS à l'identique** (écrans, structure, mécaniques, textes),
  mais avec des **contrôles Material 3 natifs** (Jetpack Compose recommandé).
- Ne dévier que si Android **ne peut pas** faire comme iOS, ou le fait **mieux**
  nativement. **Consigner chaque écart** dans `code/Android/ANDROID_DIFFERENCES.md`
  (2 sections : « Android peut ce que iOS ne peut pas » / « Android ne peut pas →
  contournement »).
- Build Android : **pas de Java système** → compiler via le **JBR embarqué
  d'Android Studio** (voir mémoire projet).

## 1. Ce que c'est

TC Quiz = app enfant de quiz de culture générale, **module séparé** de l'app
TimeCredit. L'enfant progresse par **ceintures** (façon arts martiaux), **par
matière**. Deux modes : **Entraînement** et **Passage de ceinture**. Confidentialité
forte (public enfant, RGPD/COPPA), **pas de compte**, progression **locale**.

Cahier des charges de référence : `quiz/docs/TC_Quiz_App_iOS_Specs.md` (à lire).

Réf. iOS : `/Users/em/SitesWeb/TimeCredit/quiz/code/iOS/TimeCredit Quiz/TimeCredit Quiz/`
(ci-après **[iOS]**). Le projet Android va dans `quiz/code/Android/`.

---

## 2. CE QUI EST DÉJÀ PARTAGÉ — ne rien recréer

Le **contenu et l'i18n sont agnostiques de plateforme**. Android lit **les mêmes
fichiers** que iOS (les copier dans les assets Android, ou pointer dessus) :

| Fichier | Rôle |
|---|---|
| `[iOS]/Content/curriculum.json` | squelette : niveaux, familles (types), domaines, matières, tranches |
| `[iOS]/Content/packs/pack_*.json` (57) | une tranche (domaine×matière×niveau) = questions + chapitres |
| `[iOS]/Content/vocabulaire.json` | **i18n interface, 19 langues** (122+ clés) |
| `[iOS]/Assets.xcassets/belt_*.imageset/ceinture_*.svg` | **8 ceintures + violette** (SVG auto-suffisants, contours bakés) |

Le **pipeline d'export** (DB MySQL `tc_quiz_local` → ces JSON) est un script Python
partagé : `scratchpad/gen_from_db.py` (côté iOS session). **Le même contenu sert les
deux apps.** Quand le serveur existera, il produira ces JSON (spec §4/§15).

> Android : place ces JSON + SVG dans `assets/` et lis-les tels quels. Pour les SVG,
> `androidx.core:core` / Coil-SVG, ou convertis en Vector Drawables.

---

## 3. Architecture à reproduire (voir [iOS] pour l'exact)

- **Couche contenu abstraite** : `ContentProvider` (protocole) → `BundledContentProvider`
  (lit les JSON embarqués). Un futur `RemoteContentProvider` (téléchargement par
  tranche + chiffrement au repos, spec §4) se branchera derrière la même interface.
  → [iOS] `Content/ContentProvider.swift`, `Content/ContentStore.swift`.
- **i18n = dictionnaire runtime** (PAS de strings.xml en dur, au-delà d'un fallback) :
  un service `Vocab` charge `vocabulaire.json`, expose `tr(key)` et `tr(key, args…)`
  avec **placeholders `{0}`,`{1}`**. Langue = système ou override réglages ; fallback FR ;
  gérer **RTL** (ar, he). → [iOS] `Localization/Vocab.swift`.
- **Stockage local** (JSON/DataStore/Room) : progression, historique, signalements,
  agrégats stats. → [iOS] `Stores/*`.
- **Réglage d'orientation** (système / portrait / paysage), appliqué à l'app.
  → [iOS] `AppOrientation.swift`.

---

## 4. Modèle de données (schémas JSON exacts)

**curriculum.json** : `{ content_version, country, language, levels[{id,label}],
families[{code,label,order,icon}], domains[{code,label,family,order,icon,
subjects[{code,label,icon,order,levels[{id,question_count,pack}]}]}] }`.
- `families` = les **3 types** (`scolaire`,`general`,`linguistique`) ; une famille
  sans domaine s'affiche « Aucune donnée ».
- `levels` = 7 niveaux I…VII (la seule constante de conception).

**pack_*.json** : `{ pack_id, content_version, country, language, domain, subject,
level, chapters[{code,name,order}], questions[…], checksum }`.

**question** : `{ code, type("qcm"|"numeric"), difficulty(1|2|3), stem, choices[{id,text,correct}],
explanation, chapter(code), media[] }` ; numeric : `answer{value,tolerance,unit}` au lieu de `choices`.
- **QCM = 6 propositions** ; la bonne est identifiée **uniquement** par `correct`.
- → [iOS] `Model/ContentModels.swift`.

**Ceintures** (8) : blanche→jaune→orange→verte→bleue→marron→noire→**rouge**.
Couleur = **niveau en cours** de la matière ; rouge = VII validé (maîtrise).
Assets `belt_white`…`belt_red`. → [iOS] `Model/Belt.swift`.

---

## 5. Mécaniques (valeurs EXACTES — spec §6-8)

**Progression par matière** (local) — [iOS] `Stores/ProgressionStore.swift` :
- Départ : niveau I, ceinture **blanche**.
- **Sas examen** : il faut **3 entraînements ≥ 9/10** au niveau courant pour
  débloquer le passage de ceinture ; **après un échec d'examen, 1 seul** suffit à
  re-débloquer.
- **Examen ≥ 18/20** → niveau validé, on monte d'un niveau (nouvelle couleur) ;
  VII validé → **rouge**. Échec (<18/20) → re-valider un entraînement ≥ 9/10.

**Entraînement** — [iOS] `Views/TrainingView.swift`, `Engine/QuizEngine.swift` :
- **10 questions**, composition **3 faciles / 4 normales / 3 difficiles** (tirage
  aléatoire dans chaque difficulté ; si une difficulté manque, compléter au plus proche).
- **Présentées dans l'ordre facile → normale → difficile** (décidé récemment).
- **Pas de chrono.** Feedback **immédiat** (bon/mauvais) + **explication** après chaque réponse.
- **Score /10** à la fin ; chaque série est **enregistrée** (historique).
- Lancé **par chapitre** depuis l'écran Entraînement (voir §6) : les 10 questions
  sont tirées **dans le chapitre choisi**.

**Passage de ceinture (examen)** — [iOS] `Views/ExamView.swift`, `Engine/QuizSessions.swift` :
- **20 questions uniques** tirées dans la tranche (matière×niveau courant).
- **7 s / question**, barre/anneau visible ; à 0 → réponse manquée = fausse, on enchaîne.
- **Aucun retour pendant** ; **correction des 20 à la fin** + résultat.
- Le **chrono ne démarre qu'après le média** éventuel (préchargé).

**Mélange des réponses** : Fisher-Yates **à chaque affichage** (bonne réponse
équiprobable sur les 6 positions). Vaut pour entraînement ET examen.
**Numérique** : champ nombre ; correct si `|saisie−valeur| ≤ tolérance` ; afficher l'unité.

---

## 6. Écrans (état actuel EXACT — reproduire)

Bandeau commun : **rangée des 8 ceintures pinée EN HAUT DE TOUTES LES PAGES**
(groupe compact centré). Sur les écrans secondaires, taper la rangée = retour accueil.
→ [iOS] `Views/Components.swift` (`BeltHeaderRow`, `beltHeaderBar`).

1. **Accueil** — [iOS] `Views/RootView.swift` :
   - Barre de nav masquée ; rangée ceintures en haut.
   - **Héros** : une **carte** = titre « TimeCredit Quiz » + **une ligne par type**
     (scolaire/général/langues) = picto famille + **ligne des ceintures**. Tap → écran **Progression**.
   - **Boutons style TC** (fond `thinMaterial`/surfaceVariant, coins 16, texte
     semi-gras centré + icône colorée à droite) dans l'ordre :
     **Entraînement · Passage de ceinture · (espace) · Réglages · (espace) · Statistiques · À propos**.
     Le bouton Passage de ceinture a pour picto la **ceinture violette** (`belt_purple`).
     → [iOS] `Theme/TCTheme.swift` (`TCMenuButton`).
2. **Ligne des ceintures** (composant clé) — [iOS] `Views/Components.swift` (`BeltLineView`) :
   **8 positions** horizontales blanc→rouge (`o──o──…`). Positions vides = anneaux ;
   les ceintures marquées (min & max d'un ensemble, ou la ceinture unique d'une matière)
   affichent leur **picto** ; **entre min et max = points dorés**.
3. **Progression** (ouvert depuis le héros) — [iOS] `Views/ProgressionDetailView.swift` :
   collapsibles imbriqués **grand domaine (type) → domaine → matière**, chacun avec sa
   ligne de ceintures ; vides = « Aucune donnée ».
4. **Entraînement** — [iOS] `Views/TrainingBrowseView.swift` :
   collapsibles **type → matière → chapitres** ; tap chapitre → série de 10 (§5).
5. **Passage de ceinture** — [iOS] `Views/SubjectPicker.swift` : liste des matières,
   sélectionnable seulement si l'examen est débloqué → lance l'examen.
6. **Quiz (question)** — [iOS] `Views/QuestionViews.swift` : réponses en **grille de
   tuiles rectangulaires arrondies** — **2 colonnes portrait / 3 colonnes paysage**
   (détection orientation par géométrie). États : neutre / sélection (or) / correct
   (vert) / faux (rouge). Picto de difficulté en entraînement.
7. **Statistiques** — [iOS] `Views/StatsView.swift` : historique (date, mode, matière,
   niveau, score) + taux de réussite par matière.
8. **Réglages** — [iOS] `Views/SettingsView.swift` : **Langue** (système + 19),
   **Thème**, **Orientation** (système/portrait/paysage), switches opt-in **OFF par
   défaut** (partage stats §10, sauvegarde §4.5), version contenu, **réinitialiser la
   progression**.
9. **À propos** — [iOS] `Views/AboutView.swift` : versions, légende ceintures, RGPD/COPPA.
10. **Signaler un problème** — [iOS] `Views/ReportProblemView.swift` : sur chaque
    question, motif + commentaire, **mis en file localement** (POST vers
    `/quiz/app/signaler.php` quand l'endpoint existera, spec §9). Aucune donnée perso.

---

## 7. Design / identité

- **Charte TimeCredit** : accent **doré** `#D9A621` (RGB 0.85/0.65/0.13), neutres
  système, cartes arrondies, ton ludique/bienveillant. → [iOS] `Theme/TCTheme.swift`.
- **Ceintures** : SVG auto-suffisants (contours bakés) ; l'app **ne dessine aucun
  contour** par-dessus. Repli sur un glyphe dessiné si l'asset manque.
- **Pictos** : SF Symbols côté iOS → **Material Symbols** équivalents côté Android
  (mapping indexé par CODE, jamais par libellé ; **fallback en cascade** matière→domaine→générique, spec §11). Correspondances principales :
  scolaire `graduationcap.fill`→`school` · général `building.columns.fill`→`account_balance` ·
  langues `translate`→`translate` · Entraînement `figure.run`→`directions_run` ·
  Réglages `settings` · Stats `bar_chart` · À propos `info` · difficulté
  `circle/triangle/diamond`→`circle/change_history/diamond`.
- **Accessibilité** : TalkBack (légende média comme alt), Dynamic Type, cibles ≥ 48dp,
  info jamais par la seule couleur (ceintures aussi par libellé).
- **Haptique/son doux** à la réponse et à l'obtention d'une ceinture.

---

## 8. Décisions déjà prises (ne pas rouvrir — spec §14)

- Format **JSON** (curriculum + packs) — tranché. **6 propositions/QCM** (pas 5).
- i18n interface = **base/dictionnaire de données** livré avec le contenu (pas de
  strings en dur, hors fallback).
- **Pas de compte**, progression **locale** + sauvegarde anonyme optionnelle (opt-in, OFF).
- **1 seul profil enfant** en v1.
- **Contenu actuel = TOUTES les questions courantes** de `tc_quiz_local` (3370, dont
  ~3298 brouillons non relus) — choix utilisateur. Basculable sur `statut='validated'`.
- Serveur/paywall/chiffrement au repos (SQLCipher) : plus tard, derrière `ContentProvider`.

---

## 9. À NE PAS reproduire / pièges

- **Bloc TEMP** dans [iOS] `RootView.familyMarks` (aperçu forcé blanc/bleu, jaune/orange,
  vert/noir sur le héros) : **c'est provisoire**, ne pas porter — utiliser les vraies
  données (`min/max` des ceintures des matières de la famille).
- iOS `SubjectSheet.swift` : **écran mort** (non utilisé), ignorer.
- Le pipeline JSON évoluera (serveur) : garder Android **découplé** via `ContentProvider`.

---

## 10. Démarrage suggéré (Android)

1. Créer `quiz/code/Android` (Compose, minSdk ~26, Material 3), `ANDROID_DIFFERENCES.md`.
2. Copier `curriculum.json`, `packs/`, `vocabulaire.json`, les SVG ceintures dans `assets/`.
3. Modèles + `ContentProvider`/`ContentStore` (parser les JSON du §4).
4. `Vocab` (§3) + thème doré (§7).
5. Stores progression/historique + `QuizEngine` (§5).
6. Écrans dans l'ordre : Accueil → Entraînement (arbre) → écran question (grille) →
   résultats → Passage de ceinture → Progression → Réglages/Stats/À propos → Signalement.
7. À chaque écran, **ouvrir le .swift iOS correspondant** pour l'exact.

*Fin du brief. Pour toute ambiguïté, l'app iOS tranche.*
