# Guide pour les agents et contributeurs — `pronote-sync`

> **Langue de travail** : Français (ce fichier et toute la documentation projet).

---

## 1. Description du projet
`pronote-sync` est un pipeline Python qui synchronise les données de **Pronote** (système de gestion scolaire) vers **CalDAV** (agendas) et **XMPP** (notifications).

> **Spécification complète** : Voir [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md).

---

## 2. Stack technique

### Langage et dépendances
- **Python** : ≥ 3.13 (actuellement 3.14 dans `.venv/`)
- **Dépendances principales** :
  `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, `feedparser`, `requests`, `httpx`

### Outils de développement
- **Linter** : `ruff` (longueur de ligne : 100)
- **Typage** : `mypy` (mode `strict=true`)
- **Tests** : `pytest` (couverture ≥ 90%), `pytest-mock`, `responses`, `aioresponses`
- **Sécurité** : `bandit`
- **Pre-commit** : hooks configurés pour `ruff`, `mypy`, `bandit`

### Environnement
- **Virtualenv** : `.venv/` (à activer avant toute opération)
- **Fichier de configuration** : `.env` (à partir de `.env.example`)

---

## 3. Structure du projet

```
pronote_sync/
├── config/          # Configuration et paramètres
├── models/          # Modèles de données (Pydantic v2)
├── sources/         # Connecteurs (Pronote, iCal, etc.)
├── sync/            # Logique de synchronisation
├── synthesis/       # Génération de synthèses (IA)
├── channels/        # Canaux de sortie (CalDAV, XMPP)
├── pipeline/        # Orchestration du pipeline
├── utils/           # Utilitaires (redaction, logging, etc.)
├── cli/             # Interface en ligne de commande
└── __init__.py

tests/
├── fixtures/        # Données de test anonymisées
├── unit/            # Tests unitaires
└── integration/     # Tests d'intégration
```

> **Plan de développement** : Voir [`TODO.md`](./TODO.md) pour les 15 jalons (M1-M15).

---

## 4. Commandes essentielles

### Environnement
```bash
# Activer le virtualenv
source .venv/bin/activate

# Installer les dépendances de développement
pip install -e ".[dev]"
```

### Qualité de code
```bash
# Linter (ruff)
ruff check .

# Formattage (ruff)
ruff format .

# Vérification des types (mypy)
mypy .

# Analyse de sécurité (bandit)
bandit -r pronote_sync/

# Pre-commit (tous les hooks)
pre-commit run --all-files
```

### Tests
```bash
# Exécuter les tests
pytest

# Exécuter les tests avec couverture
pytest --cov
```

### CLI
```bash
# Exécuter en mode dry-run (simulation)
pronote-sync --dry-run
```

---

## 5. Conventions de code

### Typage
- **Strict** : `mypy` en mode `strict=true`. **Tous** les paramètres, retours et variables locales doivent être typés.
- **Pydantic v2** : Tous les modèles de données héritent de `BaseModel`. Les modèles de contrat utilisent `frozen=True`.

### Architecture
- **Injection de dépendances** : Utiliser `typing.Protocol` et une **composition root** dans `pipeline/run.py`. **Interdiction** des singletons globaux.

### Style
- **Longueur de ligne** : 100 caractères maximum (configuré dans `ruff`).
- **Imports** : Triés automatiquement par `ruff` (intègre `isort`).

### Tests
- **Sans réseau** : Utiliser **uniquement** des mocks (`pytest-mock`, `responses`, `aioresponses`).
- **Fixtures** : Les données de test doivent être anonymisées et stockées dans `tests/fixtures/`.

### Comportement
- **Idempotence** : Deux exécutions identiques sans changement externe doivent produire le **même résultat**.
- **Mode dégradé** :
  - Si l'IA échoue → retourner un message **sans synthèse**.
  - Si `pronotepy` échoue → fallback vers le parsing **iCal**.
  - Si tout échoue → lever une **erreur explicite**.

---

## 6. Sécurité et secrets

### Règles absolues
- **Aucun secret en clair** : Ni dans le code, ni dans les logs, ni dans les erreurs, ni dans les fixtures.
- **Masquage** : Utiliser systématiquement `redact_url()`, `redact_secrets()`, et `redact_exception()` depuis `utils/redaction.py`.

### Bonnes pratiques
- **Types sécurisés** : Les mots de passe et clés API doivent utiliser `pydantic.SecretStr`.
- **Fichier `.env`** : **Jamais** committé (couvert par `.gitignore`). Utiliser `.env.example` comme template.

---

## 7. Plan de développement

Le projet suit un plan séquentiel en **15 jalons** (M1-M15) décrits dans [`TODO.md`](./TODO.md).

- Chaque jalon a des **critères d'acceptation** à valider avant de passer au suivant.
- Ordre logique :
  **scaffolding → config → modèles → sources → sync → synthèse → canaux → pipeline → CLI → tests → déploiement → docs**

---

## 8. Référence

| Document | Rôle |
|----------|------|
| [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md) | Spécification complète (architecture, modèles, parsing, déploiement) |
| [`TODO.md`](./TODO.md) | Plan de développement détaillé (15 jalons) |