Z5 — ChapterRevision — Identité Item & héritage Mastery
Re-upload · Clé d'identité · Héritage state · Conflits OCR
Le versioning de chapitre protège l'historique de maîtrise lors d'un re-upload. La clé d'identité d'un Item détermine si on hérite ou recrée un Mastery state — une erreur ici remet à zéro silencieusement tout le travail de l'élève.
Z5-AC01 — Clé d'identité d'un Item (définition canonique)
|
|
| Lot 0 |
P1 |
| GIVEN |
Deux items provenant de révisions différentes du même chapitre. |
| WHEN |
Le système évalue si ces deux items sont le même item logique. |
| THEN |
Deux items sont considérés identiques si et seulement si : normalized(item.term) == normalized(item2.term) ET item.pack_id == item2.pack_id ET item.type == item2.type. La normalisation inclut : lowercase, trim, suppression des accents. Aucun autre champ (confidence, tags, revision_id) n'entre dans la clé. |
NOTE : La clé volontairement simple évite les faux négatifs dus à l'OCR. Un terme légèrement différent (ex. 'IDH' vs 'I.D.H.') doit être géré par la normalisation, pas en créant un doublon.
Z5-AC02 — Héritage Mastery sur re-upload (item identique retrouvé)
|
|
| Lot 0 |
— |
| GIVEN |
L'item IDH (pack HG-INEG, type KNOWLEDGE) est en état SOLID dans la révision R1. L'élève uploade de nouvelles pages (révision R2). L'item IDH est re-détecté dans R2 avec une clé identique. |
| WHEN |
La révision R2 est finalisée. |
| THEN |
L'item IDH dans R2 hérite du Mastery state SOLID de R1. next_due_at, consecutive_successes et last_review_at sont copiés. L'item R1 est archivé (archived = true) mais non supprimé. |
Z5-AC03 — Conflit OCR : terme ambigu entre révisions
|
|
| Lot 0 |
— |
| GIVEN |
L'item vassal est en état FRAGILE dans R1. Dans R2, l'OCR produit vassalle (erreur d'OCR). Après normalisation : vassal ≠ vassalle → clés différentes. |
| WHEN |
La révision R2 est finalisée. |
| THEN |
L'item vassalle est créé comme NOUVEL item avec state UNKNOWN. L'item vassal de R1 est archivé. Une ValidationTask est créée automatiquement pour vassalle (clé non trouvée dans lexique pack → suspect). |
NOTE : Ce cas illustre pourquoi la ValidationTask pour les termes hors-lexique est critique. Le lexique pack sert de filet de sécurité contre les erreurs OCR sur les concepts clés.
Z5-AC04 — Révision courante unique par chapitre
|
|
| Lot 0 |
P1 |
| GIVEN |
Un chapitre avec deux révisions R1 et R2 créées. |
| WHEN |
L'élève ouvre la carte de leçon du chapitre. |
| THEN |
Seuls les items de la révision current_revision_id (R2) sont affichés. Les items archivés de R1 ne sont pas visibles dans la carte. Les Mastery states hérités sont bien ceux affichés dans le dashboard. |
Z5-AC05 — Sessions en cours non affectées par une nouvelle révision
|
|
| Lot 0 |
— |
| GIVEN |
L'élève a une session S1 active (IN_PROGRESS) avec des questions issues de R1. Il uploade de nouvelles pages → création de R2. |
| WHEN |
R2 est finalisée et current_revision_id est mis à jour. |
| THEN |
La session S1 continue avec les questions de R1 jusqu'à sa fin. Les Mastery updates de S1 sont appliqués normalement. La prochaine session sera composée avec les items de R2. |
Z5-AC06 — Items de R1 archivés non proposés en session
|
|
| Lot 0 |
P1 |
| GIVEN |
Un item I1 archivé de R1 a un Mastery state FRAGILE. La révision courante est R2 (I1 non re-détecté dans R2). |
| WHEN |
Une session est composée. |
| THEN |
L'item I1 archivé n'est PAS inclus dans la sélection de session. archived = true l'exclut de toutes les requêtes de composition. Le dashboard affiche uniquement les items de la révision courante. |
Z5-AC07 — Normalisation insensible à la ponctuation et aux abréviations
|
|
| Lot 0 |
— |
| GIVEN |
L'item I.D.H. existe dans R1 (état OK). Dans R2, l'OCR produit IDH (sans points). |
| WHEN |
La normalisation de clé d'identité est appliquée (cf. Z5-AC01). |
| THEN |
La normalisation supprime les points (.), tirets (-), barres obliques (/), espaces multiples et apostrophes typographiques avant comparaison. normalized("I.D.H.") == normalized("IDH") == "idh". L'héritage Mastery s'applique (cf. Z5-AC02). La liste des caractères supprimés est configurable par pack (pour les cas où le tiret est sémantique, ex. demi-vie). |
NOTE : Ce AC complète Z5-AC01 pour couvrir les variations OCR fréquentes sur les sigles et abréviations (IDH/I.D.H., PIB/P.I.B., pH/p.H.). Sans cette normalisation étendue, chaque variation OCR crée un doublon et orpheline le Mastery existant — c'est la source principale de régression silencieuse sur les re-uploads. La configurabilité par pack permet de préserver les cas où la ponctuation est sémantique.
Z5-AC08 — Alerte items à haute maîtrise non retrouvés dans la nouvelle révision
|
|
| Lot 0 |
— |
| GIVEN |
Le chapitre a 12 items dans R1. 3 items sont en état SOLID (« chloroplaste », « photosynthèse », « stomate »). L'élève re-uploade ses photos (R2). L'OCR de R2 produit 10 items. L'item « chloroplaste » n'est pas retrouvé dans R2 (page manquante ou OCR raté sur ce mot). |
| WHEN |
L'héritage Mastery de R1→R2 est calculé (Z5-AC02). |
| THEN |
Les items de R1 qui étaient en état OK ou SOLID et qui n'ont pas de correspondance dans R2 sont listés dans une alerte in-app à l'élève : « Attention — [N] point(s) bien maîtrisés n'ont pas été retrouvés dans ta nouvelle version : [liste des terms]. Vérifie que toutes les pages sont bien uploadées. » L'alerte propose deux actions : (1) « Re-uploader les pages manquantes » (relance le pipeline J0 avec des pages additionnelles), (2) « C'est normal, ce contenu n'est plus au programme » (confirme l'archivage). Les items archivés sans confirmation restent visibles dans la section « Points non retrouvés » pendant 14 jours avant archivage définitif. Le parent est informé dans le prochain digest si des items SOLID ont été perdus. |
NOTE : Un re-upload qui fait disparaître silencieusement des items SOLID est une régression invisible. L'élève qui a travaillé pendant 2 semaines pour amener « chloroplaste » à SOLID ne doit pas découvrir sa disparition par hasard. L'alerte explicite transforme un échec silencieux en action corrective (re-upload de la page manquante). Le délai de 14 jours avant archivage définitif laisse le temps de réagir.
Z5-AC09 — Ajout incrémental de pages à un chapitre existant (sans nouvelle révision)
|
|
| Lot 0 |
— |
| GIVEN |
Le chapitre « Mouvement et vitesse » existe avec une révision R1 contenant les pages 1-3 (uploadées lundi soir). L'élève a cours de physique mercredi. Mercredi soir, il photographie les pages 4-6 (suite du chapitre). |
| WHEN |
L'élève utilise l'action « Ajouter des pages » sur un chapitre existant (distinct de « Re-uploader »). |
| THEN |
Les pages 4-6 sont ajoutées à la révision courante R1 (les champs Page.order sont incrémentés : 4, 5, 6). Aucune nouvelle ChapterRevision n'est créée. Les pages 1-3 ne sont pas re-traitées : leurs résultats OCR, items, et mastery restent intacts. Seules les pages 4-6 entrent dans le pipeline J0 (segmentation → OCR → items → fidelity check). Les nouveaux items sont créés en état UNKNOWN avec revision_id = R1. L'étape de cohérence 7c compare les nouveaux items aux items existants (détection doublons/contradictions cross-pages) mais ne re-vérifie pas les items existants entre eux. La carte de leçon est mise à jour pour inclure les nouvelles pages (streaming, Z2-AC10). La file de validation (Z2-AC09) est recalculée sur l'ensemble des items du chapitre (existants + nouveaux) mais les items déjà validés ne repassent pas en validation. |
NOTE : C'est le cas d'usage #1 en fréquence pour un collégien : un cours se déroule sur 2-3 séances par semaine, et l'élève photographie ses notes au fur et à mesure. Forcer un re-upload complet (nouvelle ChapterRevision) pour ajouter 3 pages crée un risque de perte de maîtrise par drift OCR sur les pages existantes, une latence inutile (re-OCR de pages déjà traitées), et une UX confuse (alertes Z5-AC08 sur des items « disparus » qui sont en fait sur les anciennes pages non re-uploadées). L'action « Ajouter des pages » est la voie par défaut ; « Re-uploader » est réservé aux corrections (photo floue, restructuration).
Z5-AC10 — Pas de re-OCR des pages existantes lors d'un ajout incrémental
|
|
| Lot 0 |
— |
| GIVEN |
Le chapitre a 3 pages existantes (pages 1-3) avec des résultats OCR stables et 8 items dont 4 en état OK ou SOLID. L'élève ajoute les pages 4-6 via « Ajouter des pages ». |
| WHEN |
Le pipeline J0 s'exécute pour les nouvelles pages. |
| THEN |
Les résultats OCR des pages 1-3 sont conservés tels quels — aucune ré-extraction, aucune invalidation de cache OCR pour ces pages. Les items issus des pages 1-3 ne sont pas recalculés, pas re-matchés, pas soumis à un nouveau fidelity check. Leurs Mastery (states, consecutive_successes, next_due_at) restent inchangés. Le cache de questions (QuestionCandidate) des items existants reste valide. Seul le cache au niveau « session composition » est invalidé (pour intégrer les nouveaux items UNKNOWN dans le pool de sélection). Le hash OCR (Z4-AC09) n'est calculé que pour les pages 4-6. |
NOTE : Le principal risque de l'ancien modèle (re-upload complet) était le drift OCR : l'écriture manuscrite d'un collégien produit des variations subtiles à chaque extraction (« PIB/hab. » vs « PIB / hab. » vs « PIB/habitant »). Même avec la normalisation Z5-AC07, le re-OCR d'une page déjà stable introduit un risque de perte de correspondance et donc de régression silencieuse de maîtrise. En sanctuarisant les pages existantes, ce risque est éliminé.
Z5-AC11 — Bouton « Ajouter des pages » et parcours UI d'ajout incrémental
|
|
| Lot 0 |
— |
| GIVEN |
Un chapitre existe avec des pages déjà traitées (pipeline J0 terminé, items générés). L'élève a pris de nouvelles notes lors d'un cours suivant et veut les ajouter au chapitre. |
| WHEN |
L'élève ouvre la fiche du chapitre (vue détail ou carte leçon). |
| THEN |
Un bouton « Ajouter des pages » est visible en permanence sur la fiche du chapitre (pas enfoui dans un menu). Le parcours d'ajout est : (1) Sélection photos : l'élève prend ou sélectionne 1-30 nouvelles photos (même interface que l'upload initial — appareil photo ou galerie). (2) Confirmation : un écran de confirmation affiche les photos sélectionnées avec un résumé : « Ajouter [N] pages à [Nom du chapitre] ». Le texte précise : « Tes pages existantes et tes résultats ne seront pas modifiés. » (3) Lancement pipeline : le pipeline J0 s'exécute en mode incrémental (Z2-AC14) uniquement sur les nouvelles pages. L'indicateur de progression distingue clairement les nouvelles pages : « Analyse des pages 4-6… » (pas « Analyse du chapitre »). (4) Ordre des pages : les nouvelles pages sont ajoutées à la fin de la séquence existante (Page.order = max(existing_order) + 1, +2, …). L'élève peut réordonner les pages ultérieurement (drag & drop dans la carte leçon). (5) Feedback : à la fin du pipeline, un résumé s'affiche : « 6 nouveaux points détectés sur 3 pages. [Voir la carte leçon] ». Les nouveaux items sont en état UNKNOWN et apparaissent dans la prochaine session avec la priorité « premier contact » (Z6-AC33). (6) Distinction re-upload : le bouton « Ajouter des pages » est distinct de « Re-uploader le chapitre » (Z5-AC01). « Ajouter » = nouvelles pages à la suite. « Re-uploader » = remplacer des pages existantes (nouvelle ChapterRevision, Z5-AC01). Si l'élève utilise « Ajouter » mais qu'une page semble être un doublon (similarité visuelle > 80% avec une page existante), un avertissement s'affiche : « Cette page ressemble à la page 2 déjà dans ton chapitre. Ajouter quand même ? » |
NOTE : « Ajouter des pages » est l'action #1 en fréquence pour un collégien : un cours de SVT se déroule sur 3 séances/semaine, et l'élève photographie progressivement. Sans ce bouton visible et accessible, l'élève est tenté de créer un nouveau chapitre par séance (fragmentation) ou de re-uploader tout le chapitre (perte de maîtrise par drift OCR, Z5-AC10). Le parcours doit être aussi simple que l'upload initial — idéalement 2 taps (« Ajouter des pages » → sélection photos → confirmation). La détection de doublons évite le cas fréquent où l'élève re-photographie une page déjà uploadée par erreur.