tableau-de-bord/docs/home-assistant.md

Documentation Home Assistant (Intégration Présence)

Ce document fournit le guide complet et exact pour configurer une intégration Home Assistant avec l'API REST de présence du Tableau de bord pro. L'automatisation s'appuie sur le suivi d'une entité de type person et d'une zone géographique dédiée pour enregistrer automatiquement les arrivées et départs sur le lieu de travail.

---

1. Prérequis

Avant de configurer les automatisations dans Home Assistant, assurez-vous des éléments suivants :

1. Zone géographique : Home Assistant doit posséder une zone dont l'identifiant (ID) exact est lieu_de_travail (dans l'interface ou zones.yaml). Le nom de l'entité de zone doit correspondre à zone.lieu_de_travail.
2. URL HTTPS : L'application Flask (exposée via HAProxy en production) doit être accessible par Home Assistant via une URL HTTPS valide (ex: https://tableau-de-bord-pro.example.com/api/v1/workplace-presence).
3. Jeton d'authentification (secrets.yaml) : Le jeton secret (WORKLOG_API_TOKEN) généré pour l'API doit être stocké de manière sécurisée dans le fichier secrets.yaml de Home Assistant.
4. Vérification SSL : L'utilisation de verify_ssl: true est obligatoire pour garantir la sécurité des échanges HTTPS.

---

2. Configuration des Secrets (secrets.yaml)

Dans le fichier secrets.yaml de votre instance Home Assistant, ajoutez votre jeton d'API en veillant à ce que sa valeur inclue obligatoirement le préfixe exact Bearer (suivi d'un espace et de votre jeton secret) :

worklog_api_bearer_token: "Bearer votre_jeton_api_securise_ici"

Attention (point critique) : Ne préfixez jamais par Bearer dans la section rest_command. La commande utilise authorization: !secret worklog_api_bearer_token, ce qui injecte directement la valeur complète définie dans secrets.yaml (qui doit donc impérativement commencer par Bearer ).

---

3. Configuration de la Commande REST (rest_command)

Déclarez la commande REST dans votre fichier configuration.yaml (ou dans votre fichier de configuration des commandes REST) pour permettre à Home Assistant d'effectuer les requêtes POST vers l'API.

rest_command:
  worklog_presence:
    url: "https://tableau-de-bord-pro.example.com/api/v1/workplace-presence"
    method: "post"
    content_type: "application/json"
    headers:
      authorization: !secret worklog_api_bearer_token
    payload: '{"event": "{{ event }}", "occurred_at": "{{ occurred_at }}", "idempotency_key": "{{ idempotency_key }}"}'
    verify_ssl: true

---

4. Automations Home Assistant

Les deux automatisations ci-dessous surveillent l'entité person.<nom> (à adapter selon votre configuration, par exemple person.antoine) par rapport à la zone zone.lieu_de_travail.

Règle d'idempotence et de cohérence temporelle :

Pour éviter toute divergence entre l'horodatage (occurred_at) et la clé d'idempotence (idempotency_key), les automatisations utilisent des variables locales basées sur l'horodatage du déclenchement (trigger.to_state.last_updated). Ne jamais utiliser now() de manière éclatée ou divergente à plusieurs endroits d'un même payload.

---

A. Automation d'Arrivée

Cette automatisation se déclenche lorsque la personne entre dans la zone lieu_de_travail (l'état passe à lieu_de_travail).

alias: "Travail - Enregistrer Arrivée"
description: "Enregistre automatiquement l'arrivée sur le lieu de travail via l'API REST."
trigger:
  - platform: state
    entity_id: person.antoine
    to: "lieu_de_travail"
action:
  - variables:
      event_timestamp: "{{ trigger.to_state.last_updated.isoformat() }}"
      idempoteno: "{{ trigger.to_state.last_updated.strftime('%Y%m%d-%H%M%S') }}"
      idempotency: "ha-arrival-{{ idempoteno }}"
  - service: rest_command.worklog_presence
    response_variable: response
    data:
      event: "arrival"
      occurred_at: "{{ event_timestamp }}"
      idempotency_key: "{{ idempotency }}"
  - choose:
      - conditions: "{{ response.status not in [200, 201] }}"
        sequence:
          - service: persistent_notification.create
            data:
              title: "Échec Arrivée - Tableau de bord pro"
              message: >
                L'enregistrement de l'arrivée a échoué (Statut HTTP : {{ response.status }}).
                Vérifiez les journaux de l'application.
mode: single

---

B. Automation de Départ

Cette automatisation se déclenche lorsque la personne quitte la zone lieu_de_travail (l'état quitte lieu_de_travail, par exemple vers not_home ou un autre lieu).

alias: "Travail - Enregistrer Départ"
description: "Enregistre automatiquement le départ du lieu de travail via l'API REST."
trigger:
  - platform: state
    entity_id: person.antoine
    from: "lieu_de_travail"
action:
  - variables:
      event_timestamp: "{{ trigger.to_state.last_updated.isoformat() }}"
      idempoteno: "{{ trigger.to_state.last_updated.strftime('%Y%m%d-%H%M%S') }}"
      idempotency: "ha-departure-{{ idempoteno }}"
  - service: rest_command.worklog_presence
    response_variable: response
    data:
      event: "departure"
      occurred_at: "{{ event_timestamp }}"
      idempotency_key: "{{ idempotency }}"
  - choose:
      - conditions: "{{ response.status != 200 }}"
        sequence:
          - service: persistent_notification.create
            data:
              title: "Échec Départ - Tableau de bord pro"
              message: >
                L'enregistrement du départ a échoué (Statut HTTP : {{ response.status }}).
                Vérifiez les journaux de l'application.
mode: single

---

5. Gestion des Réponses et de la Sécurité

• Succès (200 / 201) : Les codes de succès sont validés silencieusement :
  • Arrivée : Renvoie 201 Created lors d'une nouvelle création, ou 200 OK en cas de rejeu (requête idempotente).
  • Départ : Renvoie strictement 200 OK (qu'il s'agisse d'un nouvel enregistrement de départ ou d'un rejeu). En cas de rejeu ou de succès normal, la réponse est gérée sans erreur par les automatisations.
• Erreurs et Notifications : Si l'API renvoie un code d'erreur (400, 401, 404, 405, 409, 413, 415, 422, 429, 500, 503), une notification persistante est créée dans Home Assistant. Le jeton d'authentification n'est jamais inclus dans les messages de notification pour des raisons évidentes de sécurité.

---

6. Limites, Risques et Points de Vigilance

1. Maximum d'une arrivée ouverte (globale) : L'application métier n'autorise qu'une seule arrivée ouverte (time_slot_id IS NULL) simultanément à l'échelle globale de l'application. Si une arrivée précédente n'a pas été fermée (ou en cas de faux départ/réarrivée manqués), une tentative de nouvelle arrivée provoquera un conflit 409 (ArrivalAlreadyOpenError).
2. Précision GPS et Oscillations (Doublons / Faux déclenchements) : Les capteurs de géolocalisation (GPS mobile, intégration companion app) peuvent osciller aux abords de la zone lieu_de_travail (mauvaise réception GPS, rebonds d'antenne). Cela peut générer des micro-entrées et sorties successives. Bien que la clé d'idempotence et la règle chronologique protègent contre les doublons stricts basés sur le même horodatage, des entrées/sorties rapprochées multiples peuvent nécessiter des corrections manuelles dans l'interface web du Tableau de bord pro.
3. Limitation de débit (Rate-limit) : L'API applique une limite stricte de 30 requêtes par fenêtre de 60 secondes par processus. En usage normal avec un unique tracker person, cette limite ne risque pas d'être atteinte, mais un dysfonctionnement d'automatisation en boucle pourrait déclencher un blocage 429.
4. Alignement des fuseaux horaires : Le fuseau horaire configuré dans la section [home_assistant] de config.toml (ex: Europe/Paris) doit être cohérent avec celui de l'instance Home Assistant pour que les conversions d'horodatages ISO 8601 avec offset (occurred_at) s'alignent parfaitement avec les journées de travail locales.
5. Disponibilité de l'API (404 / 503) :
   • Si la section [home_assistant] est absente de config.toml, l'API renvoie 404.
   • Si la variable d'environnement WORKLOG_API_TOKEN n'est pas définie sur le serveur Flask, l'API renvoie 503.
6. Sécurité et Traces Administrateur : Les administrateurs de l'instance Home Assistant ont accès aux fichiers secrets.yaml et aux journaux de traces (traces d'exécution des automatisations). Veillez à ne jamais consigner le jeton d'API en clair dans les messages de log personnalisés ou les notifications.