# TRAIL DPS 4.2 - LOT 3 - API tracking multi-catégories

## Objectif

Ajouter les endpoints WEB nécessaires au tracking régulier multi-catégories :

- enregistrement ou mise à jour d'un device ;
- création d'un binding entre un device et un événement / instance PLACE / run ;
- réception de positions GPS historisées ;
- récupération des dernières positions par événement / instance PLACE ;
- distinction stricte des catégories `RESCUE`, `OPENER`, `CLOSER`, `UNKNOWN`.

Le module licence reste séparé et n'est pas modifié.

## Fichiers ajoutés

```text
ovh/SRC/Tracking/TrackingBootstrap.php
ovh/SRC/Tracking/TrackingRepository.php
ovh/SRC/Tracking/TrackingValidation.php
ovh/public/api/tracking/register_device.php
ovh/public/api/tracking/bind_device.php
ovh/public/api/tracking/position.php
ovh/public/api/tracking/latest_positions.php
ovh/docs/TRAIL_DPS_4_2_LOT_3_API_TRACKING.md
```

## Fichiers modifiés

```text
ovh/SRC/Tracking/TrackingHttp.php
ovh/public/api/tracking/status.php
ovh/tracking_config/env.example.php
```

`env.php` de production n'est volontairement pas livré.

## Endpoints

### 1. Enregistrer un device

```bash
curl.exe --ssl-no-revoke -X POST "https://tracking.synoluvia.fr/api/tracking/register_device.php" ^
  -H "Content-Type: application/json" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -d "{\"device_uid\":\"TEL-SECOURS-001\",\"device_label\":\"Secours 1\",\"actor_type\":\"RESCUE\"}"
```

Réponse : l'API renvoie un `device_token`. Ce token doit être conservé. Il sera utilisé par le téléphone/client tracking pour envoyer les positions.

### 2. Associer le device à l'événement PLACE

```bash
curl.exe --ssl-no-revoke -X POST "https://tracking.synoluvia.fr/api/tracking/bind_device.php" ^
  -H "Content-Type: application/json" ^
  -H "X-Api-Key: VOTRE_CLE_API" ^
  -d "{\"device_uid\":\"TEL-SECOURS-001\",\"place_instance_id\":\"PLACE-TEST-001\",\"event_local_id\":1,\"run_id\":1,\"actor_type\":\"RESCUE\",\"local_team_id\":1}"
```

Pour ouvreur / fermeur, utiliser :

- `actor_type = OPENER` avec `local_staff_team_id` ;
- `actor_type = CLOSER` avec `local_staff_team_id`.

### 3. Envoyer une position GPS

Format JSON :

```bash
curl.exe --ssl-no-revoke -X POST "https://tracking.synoluvia.fr/api/tracking/position.php" ^
  -H "Content-Type: application/json" ^
  -H "X-Device-Token: DEVICE_TOKEN_RECU" ^
  -d "{\"device_uid\":\"TEL-SECOURS-001\",\"place_instance_id\":\"PLACE-TEST-001\",\"event_local_id\":1,\"run_id\":1,\"latitude\":44.1000000,\"longitude\":3.0800000,\"accuracy\":8,\"battery\":95,\"recorded_at_device\":\"2026-05-02T13:40:00Z\"}"
```

Format compatible OsmAnd / Traccar-like GET :

```bash
curl.exe --ssl-no-revoke "https://tracking.synoluvia.fr/api/tracking/position.php?id=TEL-SECOURS-001&token=DEVICE_TOKEN_RECU&place_instance_id=PLACE-TEST-001&event_local_id=1&run_id=1&lat=44.1000000&lon=3.0800000&accuracy=8&batt=95"
```

### 4. Lire les dernières positions

```bash
curl.exe --ssl-no-revoke "https://tracking.synoluvia.fr/api/tracking/latest_positions.php?place_instance_id=PLACE-TEST-001&event_local_id=1&run_id=1" ^
  -H "X-Api-Key: VOTRE_CLE_API"
```

Filtre par catégories :

```bash
curl.exe --ssl-no-revoke "https://tracking.synoluvia.fr/api/tracking/latest_positions.php?place_instance_id=PLACE-TEST-001&event_local_id=1&run_id=1&actor_types=RESCUE,OPENER,CLOSER" ^
  -H "X-Api-Key: VOTRE_CLE_API"
```

## Sécurité LOT 3

- L'enregistrement, le binding et la lecture des positions utilisent la clé API serveur `X-Api-Key`.
- L'envoi de position utilise un `device_token` propre au device.
- Le token device est stocké uniquement sous forme de hash SHA-256 en base.
- Les payloads sont validés : coordonnées, catégories, identifiants obligatoires.
- Les doublons évidents sont ignorés via `raw_payload_hash`.

## Non-régression

- Aucune table licence n'est modifiée.
- Aucune table existante du LOT 2 n'est supprimée ou renommée.
- Aucun endpoint du LOT 2 n'est supprimé.
- `status.php` reste compatible et indique simplement la version `4.2-lot3`.

## Limites assumées

- Le mapping automatique avec PLACE sera réalisé côté logiciel PLACE dans les lots ultérieurs.
- Le service SMS n'est pas inclus dans ce lot.
- La stratégie mobile définitive reste prévue au LOT 6, mais l'endpoint GET permet déjà des tests type client OsmAnd/Traccar-like.