feat: add error card feature for automated learner misunderstanding detection

data/models/__init__.py

@@ -6,6 +6,7 @@
 from .model import ModelConfig
 from .config import AppConfig
 from .knowledge import KnowledgeBase, KnowledgeFile
+from .error_card import ErrorCard
 
 __all__ = [
     "User",
@@ -18,4 +19,5 @@
     "AppConfig",
     "KnowledgeBase",
     "KnowledgeFile",
+    "ErrorCard",
 ]

data/models/error_card.py

@@ -0,0 +1,47 @@
+import uuid
+from datetime import datetime, timezone
+from sqlalchemy import Column, String, Text, DateTime, ForeignKey, Index
+from data.database import Base
+
+
+class ErrorCard(Base):
+    __tablename__ = "error_cards"
+
+    id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+    support_id = Column(
+        String,
+        ForeignKey("supports.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    user_id = Column(
+        String,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    concept = Column(String(200), nullable=False)
+    error_description = Column(Text, nullable=False)
+    simple_explanation = Column(Text, nullable=False)
+    correct_example = Column(Text, nullable=False)
+
+    # Traçabilité : depuis quel échange la fiche a été générée
+    source_user_message = Column(Text, nullable=True)
+    source_assistant_message = Column(Text, nullable=True)
+
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+
+    __table_args__ = (
+        Index("ix_error_cards_support_user", "support_id", "user_id"),
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "support_id": self.support_id,
+            "user_id": self.user_id,
+            "concept": self.concept,
+            "error_description": self.error_description,
+            "simple_explanation": self.simple_explanation,
+            "correct_example": self.correct_example,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+        }

docs/error-cards-diagrams.md

@@ -0,0 +1,124 @@
+# Diagrammes UML — Carte d'erreur instantanée
+
+Les fichiers image sont dans `docs/diagrams/`.
+Les sources Mermaid supplémentaires sont disponibles en section repliable.
+
+---
+
+## 1. Diagramme d'activité — Flux complet
+
+Montre le déroulement de bout en bout : envoi du message étudiant, génération de
+la réponse tuteur, analyse fire-and-forget, insertion en DB, toast de notification,
+puis consultation des fiches et export PDF.
+
+![Diagramme d'activité](diagrams/activity-flow.png)
+
+---
+
+## 2. Diagramme de classes — Domaine error_cards
+
+Montre les relations entre `ErrorCardsService`, `ErrorCardsRepository`,
+`BaseRepository`, `ProvidersService`, `ErrorCard`, `Support` et `User`.
+
+![Diagramme de classes](diagrams/class-diagram.png)
+
+---
+
+## 3. Diagramme de séquence — Flux détaillé en 4 phases
+
+**Phase 1 — Chargement du support :** `GET /supports/:id/error-cards` au montage
+**Phase 2 — Session de chat :** appel LLM tuteur, réponse streamed
+**Phase 3 — Analyse fire-and-forget :** `POST .../error-cards/analyze`, loop INSERT par erreur
+**Phase 4 — Consultation & export PDF :** rechargement des fiches, `exportErrorCardsToPdf()`, `Blob → window.print()`
+
+![Diagramme de séquence](diagrams/sequence-diagram.png)
+
+---
+
+## Diagrammes Mermaid complémentaires
+
+<details>
+<summary>Diagramme entité-relation — Modèle de données</summary>
+
+```mermaid
+erDiagram
+    USER {
+        string id PK
+        string name
+        string email
+    }
+
+    SUPPORT {
+        string id PK
+        string title
+        string user_id FK
+    }
+
+    ERROR_CARD {
+        string id PK
+        string support_id FK
+        string user_id FK
+        string concept
+        text error_description
+        text simple_explanation
+        text correct_example
+        text source_user_message
+        text source_assistant_message
+        datetime created_at
+    }
+
+    USER ||--o{ ERROR_CARD : "possède"
+    SUPPORT ||--o{ ERROR_CARD : "contient"
+```
+
+</details>
+
+<details>
+<summary>Diagramme de composants — Frontend</summary>
+
+```mermaid
+graph TD
+    SD[SupportDetails.svelte<br/>/student/support/:id]
+    CT[Chat.svelte<br/>chat partagé]
+    TT[tutor/Chat.svelte<br/>chat étudiant]
+    EP[ErrorCardsPanel.svelte]
+    EX[exportErrorCardsPdf.ts]
+    EC[apis/supports/error-cards.ts]
+
+    SD --> TT
+    SD --> EP
+    TT --> CT
+    TT -->|analyzeErrorCards| EC
+    EP -->|getErrorCards| EC
+    EP -->|deleteErrorCard| EC
+    EP -->|exportToPdf| EX
+
+    style EC fill:#fef3c7,stroke:#d97706
+    style EX fill:#fef3c7,stroke:#d97706
+```
+
+</details>
+
+<details>
+<summary>Diagramme d'état — Panneau ErrorCardsPanel</summary>
+
+```mermaid
+stateDiagram-v2
+    [*] --> Chargement : Montage du composant
+    Chargement --> Vide : GET /error-cards → []
+    Chargement --> AvecFiches : GET /error-cards → [...]
+
+    Vide --> AvecFiches : Nouvelles fiches détectées
+    AvecFiches --> AvecFiches : Suppression d'une fiche (reste > 0)
+    AvecFiches --> Vide : Suppression de la dernière fiche
+
+    state AvecFiches {
+        [*] --> Replié
+        Replié --> Déplié : Clic sur l'en-tête
+        Déplié --> Replié : Clic sur l'en-tête
+        Déplié --> ExportPDF : Clic sur ↓ PDF
+        ExportPDF --> Déplié : PDF généré
+    }
+```
+
+</details>

docs/error-cards-mockups.md

@@ -0,0 +1,49 @@
+# Maquette & Screenshots — Carte d'erreur instantanée
+
+Fichiers dans `docs/screenshots/`.
+
+---
+
+## Maquette — Panneau ouvert avec fiches
+
+Vue design de référence : panneau "Rapport d'erreurs" déplié avec 2 fiches.
+
+![Maquette panneau ouvert](screenshots/mockup-panel-open.png)
+
+---
+
+## Screenshots réels
+
+### En-tête du panneau replié
+
+Barre d'en-tête visible sans déplier : titre, badge "N erreurs", bouton PDF.
+
+![En-tête panneau replié](screenshots/student-error-cards-header.png)
+
+### Page support — panneau ouvert avec fiches
+
+Page complète `/student/support/:id` avec le panneau déplié et les fiches détaillées.
+
+![Page support avec fiches](screenshots/student-error-cards-panel.png)
+
+### Export PDF — fenêtre d'impression
+
+Aperçu PDF dans Chrome avant enregistrement (dialogue Print).
+
+![Export PDF](screenshots/student-error-cards-pdf.png)
+
+---
+
+## Palette et composants
+
+| Élément | Style |
+|---------|-------|
+| En-tête du panneau | Fond crème (#FEF9EE), icône livres, badge amber |
+| Badge compteur | Fond amber-500, texte blanc, coins arrondis |
+| Bouton PDF | Fond amber-500, icône téléchargement, texte blanc |
+| Numéro de fiche | Pastille amber carrée arrondie |
+| Label Erreur | Texte amber avec icône ⚠️ |
+| Label Explication | Texte amber avec icône 💡 |
+| Label Exemple correct | Texte vert avec icône ✅ |
+| Exemple code | Fond gris clair, police monospace |
+| Bouton supprimer | Icône corbeille gris, hover rouge |