130 lines
3.6 KiB
Markdown
130 lines
3.6 KiB
Markdown
# SkillQuiz 🎯
|
||
|
||
Plateforme de gestion de quiz interactifs pour formateurs et étudiants.
|
||
|
||
## Stack Technique
|
||
|
||
- **Frontend/API**: Next.js 15 (TypeScript, Tailwind CSS, App Router)
|
||
- **Base de données & Auth**: Supabase (PostgreSQL, Supabase Auth, Supabase Realtime)
|
||
- **IDs courts**: `nanoid` (codes de session 6 caractères)
|
||
|
||
## Installation
|
||
|
||
### 1. Prérequis
|
||
|
||
- Node.js 20+
|
||
- Un projet Supabase (https://supabase.com)
|
||
|
||
### 2. Configuration
|
||
|
||
```bash
|
||
# Cloner et installer les dépendances
|
||
npm install
|
||
|
||
# Copier le fichier d'environnement
|
||
cp .env.local.example .env.local
|
||
```
|
||
|
||
Remplir `.env.local` avec vos credentials Supabase :
|
||
|
||
```env
|
||
NEXT_PUBLIC_SUPABASE_URL=https://votre-projet.supabase.co
|
||
NEXT_PUBLIC_SUPABASE_ANON_KEY=votre-anon-key
|
||
SUPABASE_SERVICE_ROLE_KEY=votre-service-role-key
|
||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||
```
|
||
|
||
### 3. Base de données
|
||
|
||
Exécuter le script SQL dans l'éditeur SQL de votre projet Supabase :
|
||
|
||
```bash
|
||
# Copier le contenu de supabase/schema.sql dans l'éditeur SQL Supabase
|
||
```
|
||
|
||
### 4. Démarrer
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
L'application sera disponible sur http://localhost:3000
|
||
|
||
## Architecture des Pages
|
||
|
||
| Route | Description |
|
||
|-------|-------------|
|
||
| `/login` | Authentification formateur |
|
||
| `/dashboard` | Dashboard overview (KPIs + sessions actives) |
|
||
| `/dashboard/quizzes` | Gestion des quiz (catégories/chapitres) |
|
||
| `/dashboard/sessions/create` | Création d'une nouvelle session |
|
||
| `/dashboard/sessions/[id]/live` | Dashboard temps réel de la session |
|
||
| `/dashboard/reports` | Liste des rapports de sessions |
|
||
| `/quiz/[code]` | Page de connexion étudiant (via short_code) |
|
||
| `/quiz/[code]/exam` | Interface de quiz pour l'étudiant |
|
||
| `/quiz/[code]/results` | Page de résultats avec correction détaillée |
|
||
|
||
## API Routes
|
||
|
||
| Endpoint | Méthode | Description |
|
||
|----------|---------|-------------|
|
||
| `/api/upload-quiz` | POST | Import d'un quiz via fichier JSON |
|
||
| `/api/sessions/create` | POST | Créer une session avec short_code unique |
|
||
| `/api/sessions/[id]/toggle` | PATCH | Activer/désactiver une session |
|
||
| `/api/student/join` | POST | Rejoindre une session (crée une participation) |
|
||
| `/api/student/submit-answer` | POST | Enregistrer une réponse étudiant |
|
||
| `/api/student/finish` | POST | Terminer le quiz et calculer la note |
|
||
| `/api/student/results` | GET | Récupérer les résultats détaillés |
|
||
|
||
## Format JSON pour l'import de Quiz
|
||
|
||
```json
|
||
{
|
||
"title": "Titre du Quiz",
|
||
"category": "Catégorie (optionnel)",
|
||
"subchapter": "Sous-chapitre (optionnel)",
|
||
"questions": [
|
||
{
|
||
"question": "Texte de la question",
|
||
"explanation": "Explication affichée après (optionnel)",
|
||
"answers": [
|
||
{ "text": "Réponse A", "correct": false },
|
||
{ "text": "Réponse B", "correct": true },
|
||
{ "text": "Réponse C", "correct": false },
|
||
{ "text": "Réponse D", "correct": false }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Voir `quiz-example.json` pour un exemple complet.
|
||
|
||
## Calcul de la Note
|
||
|
||
La note est calculée côté serveur avec la formule :
|
||
|
||
```
|
||
Note = (C / N) × 20
|
||
```
|
||
|
||
Où :
|
||
- `N` = nombre total de questions
|
||
- `C` = nombre de bonnes réponses
|
||
|
||
Le résultat est arrondi à 2 décimales.
|
||
|
||
## Sécurité
|
||
|
||
- **Row Level Security (RLS)** activé sur toutes les tables
|
||
- Les formateurs ne voient que leurs propres quizzes/sessions
|
||
- Les étudiants accèdent uniquement via un short_code actif
|
||
- Middleware Next.js pour la protection des routes `/dashboard`
|
||
|
||
## Temps Réel
|
||
|
||
Le dashboard formateur (`/dashboard/sessions/[id]/live`) utilise **Supabase Realtime** pour afficher en temps réel :
|
||
- Les nouveaux participants qui rejoignent
|
||
- La progression (en_cours → terminé)
|
||
- Les scores finaux
|