diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..2dbc1a2 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,203 @@ +# Documentation de l'API REST (Intégration Présence) + +Ce document fournit la documentation technique, autonome, exacte et vérifiable de l'API REST implémentée dans l'application **Tableau de bord pro**. + +--- + +## 1. But et périmètre + +L'API REST expose un endpoint unique destiné à recevoir des événements de présence automatisés (par exemple en provenance d'un système domotique comme Home Assistant). Elle permet de : +- Enregistrer l'**arrivée** d'un collaborateur sur son lieu de travail (création automatique d'une entrée de journée `WorkEntry` si elle n'existe pas et d'un événement `WorkplacePresenceEvent`). +- Enregistrer le **départ** du lieu de travail (fermeture de l'arrivée ouverte, création d'une plage horaire `TimeSlot` et de l'événement de départ associé). +- Garantir l'**idempotence** des requêtes via une clé unique pour éviter les doublons en cas de rejeu réseau. + +--- + +## 2. Prérequis de configuration (`[home_assistant]`) + +L'activation de l'API dépend de la présence et de la validité de la section `[home_assistant]` dans le fichier de configuration `config.toml`. Si cette section est absente, l'API est désactivée et renvoie un code `404`. + +Exemple de configuration valide dans `config.toml` : +```toml +[home_assistant] +timezone = "Europe/Paris" +default_day_type = "WORK" +default_journey_profile_id = "moteur_seul" +default_motor_vehicle_id = "citadine" +``` + +### Règles de validation de la configuration : +- **`timezone`** : Doit être un fuseau horaire valide reconnu par `zoneinfo.ZoneInfo` (ex: `"Europe/Paris"`). +- **`default_day_type`** : Doit correspondre à un type de jour valide (`WORK`, `TT`, `GARDE`, `ASTREINTE`, `FORMATION`, `RTT`, `CONGE`, `MALADE`, `FERIE`). +- **`default_journey_profile_id`** : Doit être un identifiant de trajet existant dans la section `[journeys]`. +- **`default_motor_vehicle_id`** : Doit être un identifiant de véhicule existant dans la section `[vehicles]` dont le type est `"moteur"`. + +--- + +## 3. Sécurité, Authentification et Transport + +### Authentification par Jeton (Bearer Token) +- L'API exige un jeton d'authentification transmis via l'en-tête HTTP `Authorization` au format Bearer : + ```http + Authorization: Bearer + ``` +- La variable d'environnement **`WORKLOG_API_TOKEN`** doit être définie sur le serveur d'exécution. Si cette variable n'est pas configurée, l'API refuse toute requête et renvoie le statut `503`. +- La comparaison du jeton fourni avec la valeur configurée est réalisée de manière sécurisée en temps constant via `hmac.compare_digest` pour prévenir les attaques temporelles. + +### Transport et Proxy (HTTPS / HAProxy) +- L'application Flask n'implémente pas nativement le chiffrement TLS ni de mécanisme de rotation de jeton. +- En production, la sécurité du transport (HTTPS) et le routage sont entièrement délégués au serveur amont **HAProxy**. + +--- + +## 4. Spécifications techniques de l'endpoint + +- **URL** : `/api/v1/workplace-presence` +- **Méthode** : `POST` +- **Content-Type requis** : `application/json` +- **Taille maximale du corps** : `4096` octets (`_MAX_BODY_BYTES`). Au-delà, l'API rejette la requête avec le code `413`. + +### Limitation de débit (Rate-Limit) +- Chaque jeton d'authentification est soumis à une limitation de débit par processus de **30 requêtes par fenêtre glissante de 60 secondes** (`_RATE_LIMIT = 30`, `_RATE_WINDOW_SECONDS = 60.0`). +- *Note d'architecture* : Ce compteur est strictement local au processus d'exécution Flask/Gunicorn. Dans un déploiement multi-workers, une limitation globale nécessite un mécanisme amont (tel que HAProxy) ou un stockage partagé. + +--- + +## 5. Structure du Corps de la Requête (JSON) + +Le corps de la requête doit être un objet JSON valide contenant les champs suivants : + +| Champ | Type | Obligatoire | Description | +| :--- | :--- | :--- | :--- | +| `event` | `string` | Oui | Type d'événement : `"arrival"` ou `"departure"`. | +| `occurred_at` | `string` | Oui | Horodatage au format ISO 8601 comportant obligatoirement un offset de fuseau horaire (ex: `2026-08-13T08:00:00+02:00`). | +| `idempotency_key` | `string` | Oui | Clé d'idempotence unique (limitée à 255 caractères). **Obligatoire** : transmise soit dans le corps JSON (`idempotency_key`), soit via l'en-tête HTTP `X-Idempotency-Key`. | + +### Règle sur la clé d'idempotence : +La clé d'idempotence est **obligatoire**. Elle doit être fournie soit dans le corps JSON (`idempotency_key`), soit via l'en-tête HTTP `X-Idempotency-Key`. Si la clé est fournie à la fois dans le corps JSON et dans l'en-tête, **leurs valeurs doivent être strictement identiques**, sous peine d'un rejet avec le code `422`. Ne jamais considérer ce champ comme facultatif. + +--- + +## 6. Gestion du Temps et Règles Métier + +- **Fuseau horaire** : Les horodatages `occurred_at` sont convertis dans le fuseau horaire configuré dans `[home_assistant].timezone` (la configuration explicite de `timezone` est obligatoire dans la section `[home_assistant]` ; `"Europe/Paris"` n'est qu'un exemple de valeur fourni dans la configuration de référence du projet). +- **Arrivée (`arrival`)** : + - Crée une entrée de journée (`WorkEntry`) à la date locale si elle n'existe pas, en appliquant les valeurs par défaut de la configuration (`default_day_type`, `default_journey_profile_id`, `default_motor_vehicle_id`). + - Une seule arrivée peut être ouverte (`time_slot_id IS NULL`) simultanément dans toute l'application. +- **Départ (`departure`)** : + - Ferme l'arrivée ouverte correspondante. + - Crée un intervalle de temps (`TimeSlot`) rattaché à l'entrée de journée, défini entre l'heure de l'arrivée et l'heure du départ. + - L'heure du départ doit être strictement postérieure à celle de l'arrivée locale (`occurred_local > arrival_local`), sinon un code `422` est renvoyé. + +--- + +## 7. Réponses de Succès + +### Codes de statut de succès : +- **`201 Created`** : Événement d'arrivée créé avec succès (nouvelle ressource). +- **`200 OK`** : Événement de départ enregistré avec succès, ou **rejeu (replay)** d'un événement existant identique (idempotence). + +### Format de la réponse JSON : +```json +{ + "status": "created", + "event_id": 42, + "entry_id": 12, + "time_slot_id": null, + "event_type": "arrival" +} +``` +*Champs retournés :* +- `status` : `"created"` (nouvel enregistrement) ou `"replayed"` (requête idempotente rejouée). +- `event_id` : Identifiant unique de l'événement de présence enregistré. +- `entry_id` : Identifiant de la journée de travail associée (`WorkEntry`). +- `time_slot_id` : Identifiant de la plage horaire créée (`null` pour une arrivée non fermée, entier pour un départ). +- `event_type` : Rappel du type d'événement traité (`"arrival"` ou `"departure"`). + +--- + +## 8. Gestion des Erreurs + +L'API renvoie un format d'erreur homogène sous forme d'objet JSON : +```json +{ + "error": "Message explicatif de l'erreur" +} +``` +Toutes les réponses de l'API (succès et erreurs) comportent l'en-tête `Cache-Control: no-store`. + +### Codes de statut HTTP d'erreur pris en charge : + +| Code | Message d'erreur associé | Cause / Description | +| :--- | :--- | :--- | +| **`400`** | `"JSON invalide"` | Le corps de la requête n'est pas un JSON syntaxiquement valide. | +| **`401`** | `"Authentification requise"` | En-tête `Authorization` absent, schéma non Bearer, ou jeton invalide. | +| **`404`** | `"API indisponible"` | Section `[home_assistant]` absente de `config.toml`. | +| **`405`** | `"Méthode non autorisée"` | Utilisation d'une méthode HTTP autre que `POST` sur l'endpoint `/api/v1/...`. | +| **`409`** | `"Conflit métier"` | Conflit logique : tentative d'enregistrement d'un départ sans arrivée ouverte, double arrivée, ou réutilisation d'une clé d'idempotence avec des paramètres différents. | +| **`413`** | `"Requête trop volumineuse"` | La taille du corps de la requête dépasse la limite de 4096 octets. | +| **`415`** | `"Content-Type invalide"` | L'en-tête `Content-Type` est absent ou différent de `application/json`. | +| **`422`** | `"Schéma invalide"` ou `"Événement invalide"` | Données non conformes : clés non autorisées, format `occurred_at` invalide (absence d'offset ou ISO 8601 incorrect), types incorrects, ou départ antérieur à l'arrivée. | +| **`429`** | `"Trop de requêtes"` | Dépassement de la limite de débit (Rate-limit de 30 req / 60s par processus). | +| **`500`** | `"Erreur interne"` | Exception inattendue lors du traitement en base de données. | +| **`503`** | `"API indisponible"` | Variable d'environnement `WORKLOG_API_TOKEN` non définie sur le serveur. | + +--- + +## 9. Idempotence + +- L'API garantit l'idempotence par le biais de la **clé d'idempotence obligatoire** (`idempotency_key` dans le corps ou en-tête `X-Idempotency-Key`). +- Si une requête est rejouée avec une clé d'idempotence déjà enregistrée : + - Si les paramètres (`event` et `occurred_at`) sont strictement identiques, l'API renvoie le résultat précédent avec le statut `200 OK` et `"status": "replayed"`, sans dupliquer les enregistrements. + - Si les paramètres diffèrent pour une même clé, l'API rejette la requête avec le code `409` (`"Conflit métier"`). + +--- + +## 10. Comportement de l'Interface Web après l'API + +- Les journées (`WorkEntry`) créées automatiquement par l'API suite à une arrivée sont pleinement intégrées dans l'application. +- L'utilisateur peut consulter et modifier ces entrées via l'interface Web (formulaire d'édition `/entries//edit`) : + - Modification du type de journée (ex: passer de `WORK` à `FORMATION`), du profil de trajet ou du véhicule à moteur. + - Modification, ajout ou suppression de plages horaires (`TimeSlot`). +- *Cohérence des événements de présence (comportement validé par les tests d'intégration)* : Lorsque les plages horaires d'une entrée sont modifiées ou recréées depuis l'interface Web (formulaire d'édition), les événements de présence associés (`WorkplacePresenceEvent`) conservent leur traçabilité (rattachés à l'entrée `WorkEntry`), mais leurs identifiants de plage (`time_slot_id`) sont dissociés (`NULL`) pour refléter la réorganisation manuelle de la journée, conformément aux tests d'intégration existants. Aucune autre promesse au-delà de cette dissociation (`NULL`) et du maintien des événements n'est garantie. + +--- + +## 11. Exemples d'utilisation `curl` sécurisés + +> **Avertissement de sécurité** : N'écrivez jamais de secret en clair dans des scripts ou des documentations. Utilisez toujours une variable shell (ex: `$WORKLOG_API_TOKEN`). + +### 1. Enregistrer une arrivée : +```bash +curl -i -X POST "http://localhost:5000/api/v1/workplace-presence" \ + -H "Authorization: Bearer $WORKLOG_API_TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Idempotency-Key: arrival-2026-08-13-01" \ + -d '{ + "event": "arrival", + "occurred_at": "2026-08-13T08:00:00+02:00" + }' +``` + +### 2. Enregistrer un départ : +```bash +curl -i -X POST "http://localhost:5000/api/v1/workplace-presence" \ + -H "Authorization: Bearer $WORKLOG_API_TOKEN" \ + -H "Content-Type: application/json" \ + -H "X-Idempotency-Key: departure-2026-08-13-01" \ + -d '{ + "event": "departure", + "occurred_at": "2026-08-13T17:00:00+02:00" + }' +``` + +--- + +## 12. Périmètre et Limites Connues + +- **Fonctionnalités non implémentées** : + - Pas de support CORS (Cross-Origin Resource Sharing) pour des appels directs depuis un navigateur web. + - Pas de rotation automatique des jetons d'API. + - Pas de limite de débit distribuée (le rate-limit est confiné à chaque processus/worker Gunicorn). + - Pas d'import CSV en masse via l'API REST. +- **Exemple Home Assistant** : La configuration d'automatisation Home Assistant (YAML) n'est pas documentée dans ce fichier (cette documentation fait l'objet d'une étape ultérieure).