Créer GuideAgendaTheorique : guide pratique de configuration de l'agenda théorique
232
GuideAgendaTheorique.md
Normal file
232
GuideAgendaTheorique.md
Normal file
@@ -0,0 +1,232 @@
|
|||||||
|
# Guide-Agenda-Théorique
|
||||||
|
|
||||||
|
L'agenda théorique représente l'**emploi du temps attendu** de l'élève. Il est comparé à l'emploi du temps réel récupéré depuis Pronote pour **détecter les changements** (cours ajoutés, supprimés ou modifiés). Ces changements sont inclus dans les notifications XMPP et les synthèses IA.
|
||||||
|
|
||||||
|
Cette fonctionnalité est **optionnelle** : si aucun fichier d'agenda théorique n'est configuré, le pipeline fonctionne normalement et aucun changement d'agenda n'est signalé.
|
||||||
|
|
||||||
|
Pour consulter le tableau des variables, reportez-vous à la page [Configuration](Configuration).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Principe
|
||||||
|
|
||||||
|
1. Vous décrivez l'emploi du temps théorique dans un fichier JSON local.
|
||||||
|
2. Le pipeline compare ce fichier avec les cours réels Pronote pour la date cible.
|
||||||
|
3. Les différences (ajouts, suppressions, modifications) sont signalées dans les notifications.
|
||||||
|
|
||||||
|
> **Note** : L'agenda théorique n'affecte **pas** la synchronisation CalDAV. Il alimente uniquement la détection de changements pour les notifications et la synthèse IA.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Variables de configuration
|
||||||
|
|
||||||
|
| Variable | Description | Obligatoire |
|
||||||
|
|----------|-------------|-------------|
|
||||||
|
| `THEORETICAL_AGENDA_PATH` | Chemin vers le fichier JSON de l'agenda théorique | Non — désactivé si absent |
|
||||||
|
| `SCHOOL_HOLIDAYS_PATH` | Chemin vers le fichier JSON des vacances scolaires | Non — pas de filtrage si absent |
|
||||||
|
| `THEORETICAL_WEEK_ANCHOR_DATE` | Date de référence pour la parité des semaines | Requis si le fichier contient des cours `even`/`odd` |
|
||||||
|
| `THEORETICAL_WEEK_ANCHOR_TYPE` | Parité de la semaine de référence (`even` ou `odd`) | Requis si le fichier contient des cours `even`/`odd` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Fichier d'agenda théorique (`THEORETICAL_AGENDA_PATH`)
|
||||||
|
|
||||||
|
### Format JSON
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"lessons": [
|
||||||
|
{
|
||||||
|
"id": "theoretical-maths-monday-1",
|
||||||
|
"week": "all",
|
||||||
|
"day_of_week": 0,
|
||||||
|
"start_time": "08:00",
|
||||||
|
"end_time": "09:00",
|
||||||
|
"subject": "Mathématiques",
|
||||||
|
"teachers": ["Mme Martin"],
|
||||||
|
"rooms": ["101"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "theoretical-english-tuesday-even",
|
||||||
|
"week": "even",
|
||||||
|
"day_of_week": 1,
|
||||||
|
"start_time": "10:00",
|
||||||
|
"end_time": "11:00",
|
||||||
|
"subject": "Anglais",
|
||||||
|
"teachers": ["M. Dupont"],
|
||||||
|
"rooms": ["204"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Description des champs
|
||||||
|
|
||||||
|
#### Niveau racine
|
||||||
|
|
||||||
|
| Champ | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `version` | `1` | Version du format. Doit être `1`. |
|
||||||
|
| `lessons` | tableau | Liste des cours théoriques. Peut être vide. |
|
||||||
|
|
||||||
|
#### Chaque cours (`lessons[]`)
|
||||||
|
|
||||||
|
| Champ | Type | Obligatoire | Description |
|
||||||
|
|-------|------|-------------|-------------|
|
||||||
|
| `week` | `"all"`, `"even"` ou `"odd"` | Oui | `all` = toutes les semaines ; `even` = semaines paires ; `odd` = semaines impaires |
|
||||||
|
| `day_of_week` | entier 0–6 | Oui | Jour de la semaine : 0 = lundi, 1 = mardi, …, 6 = dimanche |
|
||||||
|
| `start_time` | chaîne `HH:MM` | Oui | Heure de début en format 24h (ex. `08:00`, `14:30`) |
|
||||||
|
| `end_time` | chaîne `HH:MM` | Oui | Heure de fin. Doit être strictement après `start_time` |
|
||||||
|
| `subject` | chaîne | Oui | Matière. Comparée avec la matière Pronote après normalisation (suppression de ponctuation, mise en minuscules) |
|
||||||
|
| `teachers` | tableau de chaînes | Non (défaut : `[]`) | Liste des enseignants |
|
||||||
|
| `rooms` | tableau de chaînes | Non (défaut : `[]`) | Liste des salles |
|
||||||
|
| `id` | chaîne | Non | Identifiant unique. Généré automatiquement si absent |
|
||||||
|
|
||||||
|
### Génération automatique des identifiants
|
||||||
|
|
||||||
|
Si le champ `id` n'est pas renseigné, un identifiant est généré automatiquement au format :
|
||||||
|
|
||||||
|
```text
|
||||||
|
theoretical:{week}:{day_of_week}:{start_time}-{end_time}:{subject}
|
||||||
|
```
|
||||||
|
|
||||||
|
Exemple : `theoretical:even:1:10:00-11:00:anglais`
|
||||||
|
|
||||||
|
> ⚠️ Les identifiants en doublon (explicites ou générés) provoquent une erreur au démarrage. Si deux cours partagent le même créneau mais ont une parité différente, leurs identifiants seront distincts car la parité est incluse dans l'ID.
|
||||||
|
|
||||||
|
### Parité des semaines (`week`)
|
||||||
|
|
||||||
|
- **`all`** : le cours a lieu toutes les semaines.
|
||||||
|
- **`even`** : le cours a lieu uniquement les semaines paires (par rapport à l'ancre de parité).
|
||||||
|
- **`odd`** : le cours a lieu uniquement les semaines impaires.
|
||||||
|
|
||||||
|
> Si le fichier contient des cours `even` ou `odd`, les variables `THEORETICAL_WEEK_ANCHOR_DATE` et `THEORETICAL_WEEK_ANCHOR_TYPE` doivent obligatoirement être configurées. Sinon, une erreur est levée au démarrage.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Fichier des vacances scolaires (`SCHOOL_HOLIDAYS_PATH`)
|
||||||
|
|
||||||
|
### Format JSON
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"zone": "A",
|
||||||
|
"school_year": "2026-2027",
|
||||||
|
"periods": [
|
||||||
|
{ "start_date": "2026-10-17", "end_date": "2026-11-02", "label": "Toussaint" },
|
||||||
|
{ "start_date": "2026-12-19", "end_date": "2027-01-04", "label": "Noël" },
|
||||||
|
{ "start_date": "2027-02-06", "end_date": "2027-02-21", "label": "Hiver" },
|
||||||
|
{ "start_date": "2027-04-03", "end_date": "2027-04-19", "label": "Printemps" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Description des champs
|
||||||
|
|
||||||
|
| Champ | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `zone` | chaîne | Zone académique (ex. `A`, `B`, `C`). Informatif. |
|
||||||
|
| `school_year` | chaîne | Année scolaire (ex. `2026-2027`). Informatif. |
|
||||||
|
| `periods` | tableau | Liste des périodes de vacances. Peut être vide ou absent. |
|
||||||
|
|
||||||
|
#### Chaque période (`periods[]`)
|
||||||
|
|
||||||
|
| Champ | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `start_date` | chaîne `YYYY-MM-DD` | Date de début (incluse) |
|
||||||
|
| `end_date` | chaîne `YYYY-MM-DD` | Date de fin (incluse). Doit être ≥ `start_date`. |
|
||||||
|
| `label` | chaîne | Nom de la période (ex. `Toussaint`, `Noël`) |
|
||||||
|
|
||||||
|
### Comportement
|
||||||
|
|
||||||
|
Pendant les vacances scolaires, l'agenda théorique ne retourne **aucun cours** pour les dates concernées. Ainsi, si un cours apparaît dans Pronote pendant une période de vacances, il sera signalé comme **ajouté**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ancre de parité (`THEORETICAL_WEEK_ANCHOR_DATE` et `THEORETICAL_WEEK_ANCHOR_TYPE`)
|
||||||
|
|
||||||
|
### Principe
|
||||||
|
|
||||||
|
La parité des semaines (paire/impaire, ou « semaine A / semaine B ») est déterminée à partir d'une **date de référence** (l'ancre), et non à partir des numéros de semaine ISO.
|
||||||
|
|
||||||
|
1. Vous choisissez une date qui tombe dans une semaine dont vous connaissez la parité.
|
||||||
|
2. Vous déclarez cette parité via `THEORETICAL_WEEK_ANCHOR_TYPE` (`even` ou `odd`).
|
||||||
|
3. Le système calcule la parité de toutes les autres semaines par alternation à partir de cette ancre.
|
||||||
|
|
||||||
|
### Exemple
|
||||||
|
|
||||||
|
```ini
|
||||||
|
THEORETICAL_WEEK_ANCHOR_DATE=2026-09-01
|
||||||
|
THEORETICAL_WEEK_ANCHOR_TYPE=even
|
||||||
|
```
|
||||||
|
|
||||||
|
La semaine contenant le 1er septembre 2026 est déclarée **paire** (`even`). La semaine suivante est **impaire** (`odd`), et ainsi de suite par alternance.
|
||||||
|
|
||||||
|
### Calcul
|
||||||
|
|
||||||
|
- Le système prend le lundi de la semaine cible et le lundi de la semaine d'ancre.
|
||||||
|
- Si le décalage en semaines est pair → la parité est identique à celle de l'ancre.
|
||||||
|
- Si le décalage est impair → la parité est inversée.
|
||||||
|
|
||||||
|
### Règles de validation
|
||||||
|
|
||||||
|
- Les deux variables (`DATE` et `TYPE`) doivent être configurées **ensemble**. Une seule sans l'autre provoque une erreur.
|
||||||
|
- Si le fichier d'agenda théorique ne contient que des cours `all` (pas de `even`/`odd`), l'ancre n'est pas requise.
|
||||||
|
- Si le fichier contient des cours `even` ou `odd` sans ancre configurée, une erreur est levée au démarrage.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Créer les fichiers
|
||||||
|
|
||||||
|
Les fichiers JSON doivent être créés par l'utilisateur. Le répertoire `data/` n'existe pas par défaut dans le dépôt.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p data
|
||||||
|
```
|
||||||
|
|
||||||
|
Créez ensuite les fichiers `data/theoretical.json` et `data/school_holidays.json` en vous basant sur les exemples ci-dessus.
|
||||||
|
|
||||||
|
### Exemple de configuration dans `.env`
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# --- Agenda théorique ---
|
||||||
|
THEORETICAL_AGENDA_PATH=./data/theoretical.json
|
||||||
|
SCHOOL_HOLIDAYS_PATH=./data/school_holidays.json
|
||||||
|
THEORETICAL_WEEK_ANCHOR_DATE=2026-09-01
|
||||||
|
THEORETICAL_WEEK_ANCHOR_TYPE=even
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sans agenda théorique (par défaut)
|
||||||
|
|
||||||
|
Si vous ne souhaitez pas utiliser cette fonctionnalité, laissez ces variables vides ou absentes :
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# --- Agenda théorique (désactivé) ---
|
||||||
|
# THEORETICAL_AGENDA_PATH=
|
||||||
|
# SCHOOL_HOLIDAYS_PATH=
|
||||||
|
# THEORETICAL_WEEK_ANCHOR_DATE=
|
||||||
|
# THEORETICAL_WEEK_ANCHOR_TYPE=
|
||||||
|
```
|
||||||
|
|
||||||
|
Le pipeline fonctionne normalement et signale simplement « Aucun changement d'agenda ».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Détection des changements
|
||||||
|
|
||||||
|
La comparaison entre l'agenda théorique et les cours réels Pronote utilise les critères suivants :
|
||||||
|
|
||||||
|
- **Correspondance** : même jour de la semaine + mêmes heures de début et de fin (tolérance de ±15 minutes) + même matière après normalisation.
|
||||||
|
- **Ajouté** : cours présent dans Pronote mais absent de l'agenda théorique.
|
||||||
|
- **Supprimé** : cours présent dans l'agenda théorique mais absent de Pronote.
|
||||||
|
- **Modifié** : cours correspondant mais avec des différences (horaires exacts, matière, enseignants, salles, ou statut anormal).
|
||||||
|
|
||||||
|
Les changements détectés apparaissent dans :
|
||||||
|
- Les notifications XMPP (section « 📅 Changements d'agenda »).
|
||||||
|
- Les synthèses IA.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
→ [Configuration](Configuration) — tableau des variables
|
||||||
|
→ [Architecture](Architecture) — fonctionnement du pipeline
|
||||||
Reference in New Issue
Block a user