Service Sensors

Responsabilités

Le service Sensors réconcilie l'état persisté d'un capteur avec le résultat des actions à distance déjà exécutées sur l'appareil physique.

Il ne demande ni n'exécute lui-même une action distante. Cette étape est prise en charge en amont par le service remote-action et le pipeline MQTT. Une fois qu'une action est résolue, remote-action publie le résultat sur Kafka ; le service Sensors le consomme et met à jour les informations du capteur en base.

Le service couvre actuellement ces cas d'usage :

appliquer une nouvelle fréquence de mesure à un capteur électronique ;
appliquer un changement de mode DeltaV sur les capteurs de la famille DELTV ;
notifier le domaine DeltaV lorsqu'un mode a réellement changé.

Note

Le service n'expose aucune API GraphQL. Le module GraphQL est initialisé au démarrage, mais aucune query ni mutation n'est déclarée. Le service est entièrement piloté par événements Kafka, et n'expose en HTTP qu'un endpoint de healthcheck.

Vue d'ensemble du flux

Le service Sensors n'est jamais appelé directement par un client. Il réagit au message sensors.post_action_update produit par remote-action après résolution d'une action.

sequenceDiagram
  participant RemoteAction as remote-action
  participant Kafka as Kafka
  participant Sensors as sensors
  participant Db as rs-manager DB
  participant DeltaV as Domaine DeltaV

  RemoteAction->>Kafka: sensors.post_action_update
  Kafka->>Sensors: { sensorId, actionsList }
  Sensors->>Sensors: Charge le capteur électronique
  Sensors->>Sensors: Applique chaque action
  Sensors->>Db: Sauvegarde le capteur mis à jour
  Sensors->>Kafka: deltav.mode_changed (si le mode a changé)
  Kafka->>DeltaV: { sensorId, fromMode, toMode }

Un message peut contenir plusieurs actions. Elles sont appliquées dans l'ordre au même capteur, puis le capteur est sauvegardé une seule fois.

Contrats exposés

HTTP

Le service expose uniquement un endpoint HTTP de healthcheck.

GET /

Réponse :

OK

Les opérations métier passent exclusivement par Kafka.

Kafka

Topic	Sens	Rôle
`sensors.post_action_update`	Consommé	Reçoit les résultats d'actions à appliquer à l'état du capteur.
`deltav.mode_changed`	Produit	Notifie le domaine DeltaV qu'un mode de capteur a réellement changé.

Le message entrant est validé à l'ingress : sensorId doit être un UUID, et chaque action de actionsList doit correspondre à un type supporté.

Types supportés

Actions

Le champ actionsList est une liste d'actions. Chaque action est un objet discriminé par son champ type.

export type FrequencyAction = {
  type: "frequency";
  value: number;
};

export type ChangeMode = {
  type: "change_mode";
  mode: DELTA_V_MODE;
};

export type SensorPostAction = FrequencyAction | ChangeMode;

Contraintes de validation :

frequency.value doit être un entier supérieur ou égal à 0 ;
change_mode.mode doit valoir une valeur de l'enum DELTA_V_MODE.

Modes DeltaV

export enum DELTA_V_MODE {
  ACCELERO_TILT = "accelero_tilt",
  VIBRATION = "vibration",
}

Seule la famille DELTV supporte la metadata delta_v_mode. L'action change_mode ne s'applique donc qu'aux capteurs de cette famille.

Message consommé `sensors.post_action_update`

Message produit par remote-action après résolution d'une ou plusieurs actions.

{
  sensorId: string;              // UUID
  actionsList: SensorPostAction[];
}

Exemple `frequency`

{
  "sensorId": "4d43f274-1e13-4e66-a19c-53ec6c598f01",
  "actionsList": [
    {
      "type": "frequency",
      "value": 60
    }
  ]
}

Exemple `change_mode`

{
  "sensorId": "4d43f274-1e13-4e66-a19c-53ec6c598f01",
  "actionsList": [
    {
      "type": "change_mode",
      "mode": "vibration"
    }
  ]
}

Exemple avec plusieurs actions

{
  "sensorId": "4d43f274-1e13-4e66-a19c-53ec6c598f01",
  "actionsList": [
    {
      "type": "frequency",
      "value": 120
    },
    {
      "type": "change_mode",
      "mode": "accelero_tilt"
    }
  ]
}

Message produit `deltav.mode_changed`

Message produit uniquement lorsqu'une action change_mode fait réellement transiter le mode du capteur vers une valeur différente.

{
  sensorId: string;              // UUID
  fromMode: DELTA_V_MODE;
  toMode: DELTA_V_MODE;
}

Exemple :

{
  "sensorId": "4d43f274-1e13-4e66-a19c-53ec6c598f01",
  "fromMode": "accelero_tilt",
  "toMode": "vibration"
}

Ce message n'est pas émis si le capteur n'avait pas de mode précédent, ou si le nouveau mode est identique au mode courant.

Comportement d'application

Chaque action est dispatchée vers un handler selon son type.

Type d'action	Effet sur le capteur	Événement produit
`frequency`	Met à jour l'intervalle de mesure. Réactive le capteur si `value > 0`, le désactive sinon.	Aucun.
`change_mode`	Met à jour la metadata `delta_v_mode` du capteur.	`deltav.mode_changed` si le mode change réellement.

L'intervalle de mesure pilote l'état actif du capteur : une value strictement positive active le capteur et renseigne activatedAt, tandis qu'une valeur nulle le désactive.

Cas d'erreur

Capteur introuvable : si aucun capteur électronique ne correspond au sensorId, le traitement échoue avec une erreur NotFound.
Action non supportée : un type d'action inconnu du registre déclenche une erreur Action <type> not found.

Points d'attention côté producteur

sensorId doit être un UUID correspondant à un capteur électronique existant.
L'action change_mode ne concerne que les capteurs de la famille DELTV.
L'action change_mode est idempotente sur le mode : réappliquer le mode courant ne produit aucun événement deltav.mode_changed.
L'action frequency ne produit jamais d'événement Kafka ; elle met uniquement à jour l'état du capteur en base.
Le service ne demande pas l'exécution d'une action distante. Il n'applique que des résultats déjà obtenus en amont. Pour demander une action, voir le service Remote Action.