Créer GuideAgendaVacancesScolaires : guide de configuration du fichier des vacances scolaires
135
GuideAgendaVacancesScolaires.md
Normal file
135
GuideAgendaVacancesScolaires.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Guide-Agenda-Vacances-Scolaires
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Le fichier des vacances scolaires permet de filtrer l'**agenda théorique** afin qu'aucun cours ne soit attendu pendant les périodes de vacances.
|
||||
Ce fichier est **optionnel** : s'il n'est pas configuré (`SCHOOL_HOLIDAYS_PATH` absent), le pipeline fonctionne normalement mais ne filtre pas les cours en fonction des vacances.
|
||||
Si l'agenda théorique n'est pas configuré (`THEORETICAL_AGENDA_PATH` absent), le fichier des vacances scolaires seul n'a **aucun effet**.
|
||||
|
||||
---
|
||||
|
||||
## Principe
|
||||
|
||||
Les périodes de vacances scolaires sont décrites dans un fichier JSON local.
|
||||
Pendant ces périodes, l'agenda théorique ne retourne **aucun cours**.
|
||||
Si un cours réel Pronote apparaît pendant une période de vacances, il sera signalé comme un cours **ajouté** dans la détection des changements.
|
||||
|
||||
---
|
||||
|
||||
## Variable de configuration
|
||||
|
||||
| Variable | Description | Obligatoire |
|
||||
|----------|-------------|-------------|
|
||||
| `SCHOOL_HOLIDAYS_PATH` | Chemin vers le fichier JSON des vacances scolaires | Non — pas de filtrage si absent |
|
||||
|
||||
Cette variable est utilisée conjointement avec `THEORETICAL_AGENDA_PATH` — voir [Guide Agenda Théorique](GuideAgendaTheorique).
|
||||
|
||||
---
|
||||
|
||||
## Format JSON
|
||||
|
||||
Voici la structure JSON, illustrée avec l'académie de Bordeaux (zone A, année scolaire 2026-2027) :
|
||||
|
||||
```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-13", "end_date": "2027-03-01", "label": "Hiver" },
|
||||
{ "start_date": "2027-04-10", "end_date": "2027-04-26", "label": "Printemps" },
|
||||
{ "start_date": "2027-07-03", "end_date": "2027-09-01", "label": "Été" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Description des champs
|
||||
|
||||
### Niveau racine
|
||||
|
||||
| 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
|
||||
|
||||
La fonction `is_holiday(date)` retourne `True` si la date tombe dans une période (`start_date <= date <= end_date`), **bornes incluses**.
|
||||
Pendant les vacances, l'agenda théorique ne retourne **aucun cours**.
|
||||
Un cours réel apparaissant pendant les vacances sera signalé comme **ajouté** dans la détection des changements.
|
||||
|
||||
---
|
||||
|
||||
## Zones académiques
|
||||
|
||||
La France est divisée en 3 zones : A, B, C.
|
||||
Bordeaux fait partie de la zone A.
|
||||
Les zones diffèrent pour les vacances d'hiver et de printemps ; les vacances de la Toussaint, de Noël et d'été sont **identiques pour toutes les zones**.
|
||||
Le champ `zone` dans le JSON est **purement informatif** — il n'a pas d'impact sur le comportement du pipeline.
|
||||
Vous pouvez trouver votre zone sur le calendrier officiel du ministère à l'adresse [education.gouv.fr](https://education.gouv.fr).
|
||||
|
||||
---
|
||||
|
||||
## Où trouver les dates officielles
|
||||
|
||||
Le calendrier scolaire officiel est publié par le ministère de l'Éducation nationale sur [education.gouv.fr](https://education.gouv.fr) (rechercher « calendrier scolaire »).
|
||||
Les données sont également disponibles sur [data.education.gouv.fr](https://data.education.gouv.fr).
|
||||
Les dates sont publiées par académie et par zone.
|
||||
|
||||
---
|
||||
|
||||
## Créer le fichier
|
||||
|
||||
```bash
|
||||
mkdir -p data
|
||||
```
|
||||
|
||||
Créez le fichier `data/school_holidays.json` en vous basant sur le format ci-dessus, en utilisant les dates officielles de votre zone.
|
||||
|
||||
---
|
||||
|
||||
## Exemple de configuration dans `.env`
|
||||
|
||||
```ini
|
||||
# --- Agenda théorique ---
|
||||
THEORETICAL_AGENDA_PATH=./data/theoretical.json
|
||||
SCHOOL_HOLIDAYS_PATH=./data/school_holidays.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sans vacances scolaires (par défaut)
|
||||
|
||||
Si vous ne souhaitez pas de filtrage par vacances scolaires, laissez `SCHOOL_HOLIDAYS_PATH` vide ou absent :
|
||||
|
||||
```ini
|
||||
# SCHOOL_HOLIDAYS_PATH=
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cas particuliers
|
||||
|
||||
- **Week-ends** : Le calendrier officiel commence les vacances le samedi. Si votre établissement n'a pas cours le samedi, vous pouvez indiquer le lundi suivant comme `start_date` sans altérer le comportement. Les bornes incluses signifient que le samedi est déjà considéré comme un jour de vacances.
|
||||
- **Vacances d'été** : L'inclusion des grandes vacances est optionnelle. Si elles sont omises, le calendrier ne filtrera simplement pas les dates pendant l'été — ce qui est généralement acceptable, le pipeline ne synchronisant qu'une fenêtre configurable (`SYNC_PAST_DAYS` / `SYNC_FUTURE_DAYS`).
|
||||
|
||||
---
|
||||
|
||||
→ [Guide Agenda Théorique](GuideAgendaTheorique) — configuration complète de l'agenda théorique
|
||||
→ [Configuration](Configuration) — tableau des variables
|
||||
Reference in New Issue
Block a user