AntoineVe/college-infos

Fork 0

Table of Contents

Guide-Agenda-Théorique

Principe
Variables de configuration
Fichier d'agenda théorique (THEORETICAL_AGENDA_PATH)

Format JSON
Description des champs

Niveau racine
Chaque cours (lessons[])

Génération automatique des identifiants
Parité des semaines (week)

Fichier des vacances scolaires (SCHOOL_HOLIDAYS_PATH)

Format JSON
Description des champs

Chaque période (periods[])

Comportement

Ancre de parité (THEORETICAL_WEEK_ANCHOR_DATE et THEORETICAL_WEEK_ANCHOR_TYPE)

Principe
Exemple
Calcul
Règles de validation

Créer les fichiers

Exemple de configuration dans .env
Sans agenda théorique (par défaut)

Détection des changements

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.

Principe

Vous décrivez l'emploi du temps théorique dans un fichier JSON local.
Le pipeline compare ce fichier avec les cours réels Pronote pour la date cible.
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

{
  "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 :

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

{
  "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.

Vous choisissez une date qui tombe dans une semaine dont vous connaissez la parité.
Vous déclarez cette parité via THEORETICAL_WEEK_ANCHOR_TYPE (even ou odd).
Le système calcule la parité de toutes les autres semaines par alternation à partir de cette ancre.

Exemple

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.

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`

# --- 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 :

# --- 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 — tableau des variables → Architecture — fonctionnement du pipeline

Guide-Agenda-Théorique

Principe

Variables de configuration

Fichier d'agenda théorique (THEORETICAL_AGENDA_PATH)

Format JSON

Description des champs

Niveau racine

Chaque cours (lessons[])

Génération automatique des identifiants

Parité des semaines (week)

Fichier des vacances scolaires (SCHOOL_HOLIDAYS_PATH)

Format JSON

Description des champs

Chaque période (periods[])

Comportement

Ancre de parité (THEORETICAL_WEEK_ANCHOR_DATE et THEORETICAL_WEEK_ANCHOR_TYPE)

Principe

Exemple

Calcul

Règles de validation

Créer les fichiers

Exemple de configuration dans .env

Sans agenda théorique (par défaut)

Détection des changements

Documentation

Fichier d'agenda théorique (`THEORETICAL_AGENDA_PATH`)

Chaque cours (`lessons[]`)

Parité des semaines (`week`)

Fichier des vacances scolaires (`SCHOOL_HOLIDAYS_PATH`)

Chaque période (`periods[]`)

Ancre de parité (`THEORETICAL_WEEK_ANCHOR_DATE` et `THEORETICAL_WEEK_ANCHOR_TYPE`)

Exemple de configuration dans `.env`