# TRAIL DPS 4.2.4 - OVH préparation synchronisation PLACE / LIVE DPS et CRON purge

## Objet du lot

Ce lot prépare le serveur OVH pour la future synchronisation PLACE / LIVE DPS.

La version PLACE n'est pas encore déployée : ce lot ne modifie donc pas PLACE et n'active aucune dépendance côté desktop.

Il ajoute :

1. des endpoints de synchronisation incrémentale prêts pour PLACE,
2. une pagination par curseur,
3. une lecture delta sur les positions latest,
4. une lecture delta sur les traces compactées,
5. une lecture delta sur les demandes coureur,
6. un service PHP partagé pour la purge,
7. des scripts CLI pour créer les tâches CRON OVH.

## Règles conservées

- Android/iOS ne sont pas modifiés.
- `position.php` reste le point d'ingestion mobile.
- `tracking_positions` reste le sas brut.
- `tracking_positions_latest` reste la source LIVE rapide.
- `tracking_positions_trace` reste la source trace compacte.
- PLACE reste futur consommateur, pas encore modifié.
- Aucune donnée médicale n'est ajoutée.
- Les flux tracking régulier et coureur SMS restent séparés.

## Fichiers créés

- `public/api/tracking/sync_latest.php`
- `public/api/tracking/sync_trace.php`
- `public/api/tracking/sync_runner_requests.php`
- `SRC/Tracking/TrackingPurgeService.php`
- `scripts/cron_tracking_purge.php`
- `scripts/cron_tracking_purge_dry_run.php`
- `sql/lot_4_2_4_validation_after_ftp.sql`
- `docs/TRAIL_DPS_4_2_4_OVH_SYNC_PLACE_CRON.md`

## Fichiers modifiés

- `public/api/tracking/purge.php`

La modification de `purge.php` ne change pas son contrat HTTP. Elle factorise simplement la logique dans `TrackingPurgeService.php` pour permettre l'appel CLI depuis CRON.

---

# 1. Endpoints de synchronisation PLACE

Tous les endpoints utilisent :

- méthode `GET`,
- header `X-Api-Key`,
- filtrage obligatoire `event_remote_id + place_instance_id`,
- `event_local_id` optionnel,
- `run_id` optionnel.

## 1.1 sync_latest.php

Source : `tracking_positions_latest`

Usage futur PLACE : récupérer les dernières positions courantes à synchroniser localement.

URL type :

```text
/api/tracking/sync_latest.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS
```

Paramètres :

- `event_remote_id` obligatoire,
- `place_instance_id` obligatoire,
- `event_local_id` optionnel,
- `run_id` optionnel,
- `actor_types` optionnel : `RESCUE,OPENER,CLOSER`,
- `updated_after` optionnel,
- `cursor_id` optionnel,
- `limit` optionnel, défaut 200, maximum 500.

Réponse :

- `items`,
- `next_cursor.updated_after`,
- `next_cursor.cursor_id`,
- `has_more`,
- `server_time_utc`.

## 1.2 sync_trace.php

Source : `tracking_positions_trace`

Usage futur PLACE : récupérer les traces compactées, par défaut sur les 3 dernières heures.

URL type :

```text
/api/tracking/sync_trace.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS&hours=3
```

Paramètres :

- `event_remote_id` obligatoire,
- `place_instance_id` obligatoire,
- `event_local_id` optionnel,
- `run_id` optionnel,
- `binding_id` optionnel,
- `device_id` optionnel,
- `actor_types` optionnel,
- `recorded_after` optionnel,
- `cursor_id` optionnel,
- `hours` optionnel, défaut 3, maximum 24,
- `limit` optionnel, défaut 5000, maximum 10000.

## 1.3 sync_runner_requests.php

Source : `runner_location_requests`

Usage futur PLACE : récupérer les demandes coureur ayant évolué.

URL type :

```text
/api/tracking/sync_runner_requests.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS
```

Paramètres :

- `event_remote_id` obligatoire,
- `place_instance_id` obligatoire,
- `event_local_id` optionnel,
- `run_id` optionnel,
- `statuses` optionnel,
- `updated_after` optionnel,
- `cursor_id` optionnel,
- `limit` optionnel, défaut 200, maximum 500.

---

# 2. Tests PowerShell

Remplacer la clé API par `public_api_key` de `tracking_config/env.php`.

## 2.1 Test sync latest

```powershell
$ApiKey = "REMPLACER_PAR_LA_VALEUR_DE_public_api_key"

Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/sync_latest.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS&limit=50" `
  -Method GET `
  -Headers @{ "X-Api-Key" = $ApiKey } |
  ConvertTo-Json -Depth 10
```

## 2.2 Test sync trace

```powershell
$ApiKey = "REMPLACER_PAR_LA_VALEUR_DE_public_api_key"

Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/sync_trace.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS&hours=3&limit=100" `
  -Method GET `
  -Headers @{ "X-Api-Key" = $ApiKey } |
  ConvertTo-Json -Depth 10
```

## 2.3 Test sync demandes coureur

```powershell
$ApiKey = "REMPLACER_PAR_LA_VALEUR_DE_public_api_key"

Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/sync_runner_requests.php?event_remote_id=EVT-TEST-002&place_instance_id=PLACE-TEST-IOS&limit=50" `
  -Method GET `
  -Headers @{ "X-Api-Key" = $ApiKey } |
  ConvertTo-Json -Depth 10
```

## 2.4 Exemple de reprise par curseur

Après une première réponse, reprendre avec les valeurs `next_cursor` retournées :

```text
updated_after=2026-05-10 13:00:00&cursor_id=12
```

En URL, encoder l'espace si besoin :

```text
updated_after=2026-05-10T13:00:00Z&cursor_id=12
```

---

# 3. CRON purge OVH

## 3.1 Script principal

Script à appeler par CRON :

```text
scripts/cron_tracking_purge.php
```

Règles :

- purge réelle,
- batch limité,
- `tracking_positions` > 8 heures,
- `tracking_positions_trace` > 7 jours,
- logs > 30 jours.

## 3.2 Script dry-run CLI

Script de test sans suppression :

```text
scripts/cron_tracking_purge_dry_run.php
```

Il permet de vérifier que le chemin PHP CLI et la configuration OVH sont corrects avant activation du CRON réel.

---

# 4. Mise en place CRON OVH

## Important

Le ZIP ne peut pas créer automatiquement le CRON dans le manager OVH. Il fournit les scripts prêts à planifier.

La création du CRON doit être faite dans l'interface OVH ou dans le système disponible sur l'hébergement.

## Fréquence recommandée

Toutes les 10 minutes.

## Commande type

Le chemin exact dépend du chemin absolu de l'hébergement OVH.

Exemple à adapter :

```bash
php /home/USER/www/scripts/cron_tracking_purge.php
```

Si OVH demande uniquement un chemin de script PHP, renseigner :

```text
www/scripts/cron_tracking_purge.php
```

## Test CLI préalable si accès SSH disponible

```bash
php /home/USER/www/scripts/cron_tracking_purge_dry_run.php
```

Résultat attendu :

```json
{
  "ok": true,
  "script": "cron_tracking_purge_dry_run.php",
  "dry_run": true
}
```

Puis test réel manuel :

```bash
php /home/USER/www/scripts/cron_tracking_purge.php
```

---

# 5. Validation phpMyAdmin

Après FTP, exécuter :

- base : `synoluidpstrack`,
- onglet : `SQL`,
- fichier : `sql/lot_4_2_4_validation_after_ftp.sql`.

Ce script ne modifie aucune donnée.

---

# 6. Critères de recette

Le lot est validé si :

- `sync_latest.php` répond `ok: true`,
- `sync_trace.php` répond `ok: true`,
- `sync_runner_requests.php` répond `ok: true`,
- les réponses contiennent `next_cursor`,
- `purge.php` fonctionne toujours en HTTP POST,
- `cron_tracking_purge_dry_run.php` fonctionne en CLI,
- `cron_tracking_purge.php` fonctionne en CLI,
- aucun endpoint Android/iOS n'est modifié,
- `position.php` continue à recevoir les positions mobiles.

---

# 7. Points de vigilance

- Ne pas activer PLACE sur ces endpoints tant que le lot desktop n'est pas prêt.
- Ne pas passer `limit` trop haut côté PLACE : préférer la pagination.
- Le CRON doit rester batché : éviter une purge massive en un seul passage.
- Garder le filtrage `event_remote_id + place_instance_id` dans tous les appels.
- Les demandes coureur restent un flux distinct du tracking régulier.