AntoineVe/tableau-de-bord
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(home-assistant): mettre à jour la documentation de l'intégration présence

Browse Source 
Précise l'authentification Bearer (WORKLOG_API_TOKEN), la configuration
des secrets et commandes REST Home Assistant, les codes de réponse de
l'API et la conservation des événements de présence.

Co-authored-by: OpenAI/GPT-5.6-Terra <vibecoder@antoineve.me>
This commit is contained in:
Antoine Van Elstraete
2026-08-15 17:21:20 +02:00
parent fc3250f431
commit b7bde134aa
5 changed files with 34 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/api.md
View File

@@ -71,7 +71,7 @@ Le corps de la requête doit être un objet JSON valide contenant les champs sui
| :--- | :--- | :--- | :--- |
| `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`. |
| `idempotency_key` | `string` | Oui (corps ou en-tête) | 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.
@@ -83,7 +83,7 @@ La clé d'idempotence est **obligatoire**. Elle doit être fournie soit dans le
- **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.
- Une seule arrivée peut être ouverte (`time_slot_id IS NULL`) simultanément **de manière globale à 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.
@@ -159,7 +159,9 @@ Toutes les réponses de l'API (succès et erreurs) comportent l'en-tête `Cache-
- L'utilisateur peut consulter et modifier ces entrées via l'interface Web (formulaire d'édition `/entries/<id>/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.
- *Cohérence et conservation des événements de présence (comportement validé par les tests d'intégration)* :
- **Conservation** : Les événements de présence (`WorkplacePresenceEvent`) sont conservés en base de données **tant que l'entrée de journée associée (`WorkEntry`) n'est pas supprimée** (liaison soumise à la suppression en cascade `cascade="all, delete-orphan"` au niveau du modèle de données).
- **Dissociation de plage** : 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é et leur rattachement à 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`), du maintien conditionnel (tant que `WorkEntry` existe) et du suivi des événements n'est garantie.
---
@@ -200,4 +202,4 @@ curl -i -X POST "http://localhost:5000/api/v1/workplace-presence" \
- 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).
- **Intégration Home Assistant** : La configuration détaillée des scripts, secrets, commandes REST et automatisations Home Assistant est documentée dans la [Documentation Home Assistant](home-assistant.md).