diff --git a/Architecture.md b/Architecture.md deleted file mode 100644 index 15a52ef..0000000 --- a/Architecture.md +++ /dev/null @@ -1,50 +0,0 @@ -# Architecture - -## Vue d'ensemble - -`pronote-sync` est un pipeline qui synchronise les données de **Pronote** vers **CalDAV** (agendas) et **XMPP** (notifications). Le flux principal est : **Pronote (iCal/pronotepy) → normalisation → comparaison avec l'agenda théorique → synchronisation CalDAV → synthèse IA (optionnelle) → notification XMPP**. Les sources sont **iCal** (primaire) et `pronotepy` (repli), avec trois modes de source : `auto`, `ical` et `pronotepy`. - -## Pipeline - -1. Récupération Pronote (iCal + pronotepy) — agenda, devoirs, messages -1. Normalisation et parsing — parsing iCal → modèles Pydantic, déduplication, normalisation des UID -1. Récupération du blog (RSS) — `feedparser`, déduplication par GUID, cache HTTP -1. Comparaison avec l'agenda théorique — matching déterministe, détection des changements -1. Synchronisation CalDAV — sync différentielle et idempotente, UID stables, conservation des annulés -1. Synthèse IA (optionnelle) — synthèse des changements, mode dégradé si échec -1. Envoi XMPP — message structuré (synthèse + devoirs bruts) - -## Modules - -``` -pronote_sync/ -├── config/ Configuration (Pydantic Settings) -├── models/ Modèles de données (Pydantic v2) -├── sources/ Connecteurs (Pronote iCal/pronotepy, blog RSS, agenda théorique) -├── sync/ Synchronisation CalDAV et comparaison -├── synthesis/ Synthèse IA (OpenAI, litellm, openai-compatible) -├── channels/ Canaux de sortie (XMPP) -├── pipeline/ Orchestration (composition root, PipelineRunner) -├── utils/ Utilitaires (redaction, logging, UID) -└── cli/ Interface en ligne de commande -``` - -## Injection de dépendances - -Le projet utilise `typing.Protocol` et une **composition root** dans `pipeline/run.py`. Aucun singleton global n'est autorisé. Le `PipelineRunner` reçoit toutes ses dépendances via **injection par constructeur** : `PronoteFetcher`, `CalDAVClient`, `AgendaComparator`, `SynthesisProvider`, `Channel`. - -## Sources de données - -Les modes de source sont les suivants : - -- `auto` : essaie d'abord iCal, puis bascule vers `pronotepy` **uniquement** si iCal lève une exception. -- `ical` : utilise **uniquement** iCal, sans bascule silencieuse. -- `pronotepy` : utilise **uniquement** `pronotepy`, sans bascule silencieuse. -- En mode `auto`, si iCal **et** `pronotepy` échouent → erreur critique explicite. -- Une liste vide est un **succès valide**, pas une panne. -- `PRONOTE_URL` (connexion API) et `PRONOTE_ICAL_URL` (flux iCal) sont deux paramètres **distincts**. -- Les messages ne sont disponibles que via `pronotepy` (absents du flux iCal). - -## Flux de données - -Le flux de données suit ce chemin : données brutes (iCal/`pronotepy`) → modèles Pydantic (`Lesson`, `Homework`, `Message`, etc.) → `PronoteData` (agrégé) → `AgendaDiff` (comparaison) → `CalDavSyncResult` → `SynthesisInput`/`SynthesisResult` → `XmppMessage` → envoi via le canal XMPP. \ No newline at end of file diff --git a/unnamed.md b/unnamed.md index a814188..631f5d8 100644 --- a/unnamed.md +++ b/unnamed.md @@ -1,36 +1,50 @@ -# pronote-sync +# Architecture -`pronote-sync` est un pipeline Python qui synchronise les données de **Pronote** (agenda et devoirs) vers un calendrier **CalDAV** et envoie des notifications via **XMPP**. Ce wiki s'adresse aux utilisateurs, administrateurs et contributeurs du projet. +## Vue d'ensemble -## Documentation +`pronote-sync` est un pipeline qui synchronise les données de **Pronote** vers **CalDAV** (agendas) et **XMPP** (notifications). Le flux principal est : **Pronote (iCal/pronotepy) → normalisation → comparaison avec l'agenda théorique → synchronisation CalDAV → synthèse IA (optionnelle) → notification XMPP**. Les sources sont **iCal** (primaire) et `pronotepy` (repli), avec trois modes de source : `auto`, `ical` et `pronotepy`. -- [Architecture](Architecture) — Pipeline, modules et flux de données -- [Configuration](Configuration) — Variables d'environnement et paramètres -- [Déploiement](Déploiement) — systemd, timer, logrotate et vérification des secrets -- [Sécurité](Sécurité) — Rédaction, `SecretStr`, `check_secrets` et bonnes pratiques +## Pipeline -## Démarrage rapide +1. Récupération Pronote — agenda et devoirs via iCal ou `pronotepy` ; messages et informations via `pronotepy` uniquement +1. Normalisation et parsing — parsing iCal → modèles Pydantic, déduplication, normalisation des UID +1. Récupération du blog (RSS) — `feedparser`, déduplication par GUID, cache HTTP +1. Comparaison avec l'agenda théorique — matching déterministe, détection des changements +1. Synchronisation CalDAV — sync différentielle et idempotente, UID stables, conservation des annulés +1. Synthèse IA (optionnelle) — synthèse des changements, mode dégradé si échec +1. Envoi XMPP — message structuré (synthèse + devoirs bruts) -```bash -git clone https://git.antoineve.me/AntoineVe/college-infos -cd college-infos -python3.13 -m venv .venv -source .venv/bin/activate -pip install -e ".[dev]" -cp .env.example .env -# Éditer .env et renseigner les URL et identifiants requis -pronote-sync --dry-run --log-level DEBUG +## Modules + +```text +pronote_sync/ +├── config/ Configuration (Pydantic Settings) +├── models/ Modèles de données (Pydantic v2) +├── sources/ Connecteurs (Pronote iCal/pronotepy, blog RSS, agenda théorique) +├── sync/ Synchronisation CalDAV et comparaison +├── synthesis/ Synthèse IA (OpenAI, litellm, openai-compatible) +├── channels/ Canaux de sortie (XMPP) +├── pipeline/ Orchestration (composition root, PipelineRunner) +├── utils/ Utilitaires (redaction, logging, UID) +└── cli/ Interface en ligne de commande ``` -## Utilisation +## Injection de dépendances -```bash -pronote-sync # Exécute la synchronisation -pronote-sync --dry-run # Simulation sans écriture -pronote-sync --log-level DEBUG # Verbosité des journaux -``` +Le projet utilise `typing.Protocol` et une **composition root** dans `pipeline/run.py`. Aucun singleton global n'est autorisé. Le `PipelineRunner` reçoit toutes ses dépendances via **injection par constructeur** : `PronoteFetcher`, `CalDAVClient`, `AgendaComparator`, `SynthesisProvider`, `Channel`. -## Communauté +## Sources de données -- [Signaler un problème ou proposer une évolution](https://git.antoineve.me/AntoineVe/college-infos/issues) -- Licence : MIT \ No newline at end of file +Les modes de source sont les suivants : + +- `auto` : essaie d'abord iCal, puis bascule vers `pronotepy` **uniquement** si iCal lève une exception. +- `ical` : utilise **uniquement** iCal, sans bascule silencieuse. +- `pronotepy` : utilise **uniquement** `pronotepy`, sans bascule silencieuse. +- En mode `auto`, si iCal **et** `pronotepy` échouent → erreur critique explicite. +- Une liste vide est un **succès valide**, pas une panne. +- `PRONOTE_URL` (connexion API) et `PRONOTE_ICAL_URL` (flux iCal) sont deux paramètres **distincts**. +- Les messages ne sont disponibles que via `pronotepy` (absents du flux iCal). + +## Flux de données + +Le flux de données suit ce chemin : données brutes (iCal/`pronotepy`) → modèles Pydantic (`Lesson`, `Homework`, `Message`, etc.) → `PronoteData` (agrégé) → `AgendaDiff` (comparaison) → `CalDavSyncResult` → `SynthesisInput`/`SynthesisResult` → `XmppMessage` → envoi via le canal XMPP. \ No newline at end of file