# TRAIL DPS V4.2 - LOT 4 - Service SMS et demandes coureur

## Bloc
WEB

## Objectif
Créer le socle serveur permettant à PLACE de demander ponctuellement la position d'un coureur par SMS, sans donnée médicale.

Le LOT 4 ne fournit pas encore la page web coureur. Cette page sera livrée au LOT 5.

## Fichiers livrés

### Nouveaux fichiers
- `ovh/SRC/Tracking/SmsService.php`
- `ovh/SRC/Tracking/RunnerLocationRepository.php`
- `ovh/public/api/tracking/create_runner_location_request.php`
- `ovh/public/api/tracking/runner_location_requests.php`
- `ovh/public/api/tracking/cancel_runner_location_request.php`
- `ovh/docs/TRAIL_DPS_4_2_LOT_4_SMS_DEMANDES_COUREUR.md`

### Fichiers modifiés
- `ovh/tracking_config/env.example.php`
- `ovh/public/api/tracking/status.php`

## Configuration à ajouter dans `ovh/tracking_config/env.php`

Ajouter les blocs suivants au même niveau que `database`, `security` et `tracking` :

```php
'runner_location' => [
    'public_base_url' => 'https://tracking.synoluvia.fr',
    'runner_page_path' => '/runner/location.php',
    'default_expiration_minutes' => 45,
],
'sms' => [
    'provider' => 'log_only',
    'sender' => 'TRAILDPS',
    'runner_location_message_template' => 'TRAIL DPS - {event_name} : merci de partager votre position ici {url}',
    'ovh_endpoint' => 'https://eu.api.ovh.com/1.0',
    'ovh_application_key' => '',
    'ovh_application_secret' => '',
    'ovh_consumer_key' => '',
    'ovh_service_name' => '',
],
```

## Mode SMS

### Mode par défaut : `log_only`

Le mode `log_only` ne déclenche aucun SMS réel. Il permet de tester toute la chaîne serveur :
- création de la demande ;
- génération du lien sécurisé ;
- insertion dans `runner_location_requests` ;
- insertion dans `sms_logs` ;
- statut `SMS_SENT` avec provider `log_only`.

### Mode réel OVH : `ovh`

Le code contient le connecteur OVHcloud SMS, mais il ne doit être activé qu'après configuration complète :

```php
'sms' => [
    'provider' => 'ovh',
    'sender' => 'TRAILDPS',
    'runner_location_message_template' => 'TRAIL DPS - {event_name} : merci de partager votre position ici {url}',
    'ovh_endpoint' => 'https://eu.api.ovh.com/1.0',
    'ovh_application_key' => '...',
    'ovh_application_secret' => '...',
    'ovh_consumer_key' => '...',
    'ovh_service_name' => 'sms-...',
],
```

## Endpoints

### 1. Créer une demande coureur

`POST /api/tracking/create_runner_location_request.php`

Champs obligatoires :
- `place_instance_id`
- `event_local_id`
- `event_name`
- `phone`

Champs optionnels :
- `event_remote_id`
- `run_id`
- `expires_in_minutes`

Commande PowerShell :

```powershell
$headers = @{
  "Content-Type" = "application/json"
  "X-Api-Key"    = "TA_CLE_API"
}

$body = @{
  place_instance_id  = "PLACE-TEST-001"
  event_local_id     = 1
  run_id             = 1
  event_name         = "Trail Test DPS"
  phone              = "+33600000000"
  expires_in_minutes = 45
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/create_runner_location_request.php" `
  -Method POST `
  -Headers $headers `
  -Body $body

$response | ConvertTo-Json -Depth 10
```

Réponse attendue :

```json
{
  "ok": true,
  "request": {
    "id": 1,
    "status": "SMS_SENT",
    "expires_at": "..."
  },
  "sms": {
    "provider": "log_only",
    "status": "logged"
  },
  "location_url": "https://tracking.synoluvia.fr/runner/location.php?token=..."
}
```

### 2. Lister les demandes coureur

`GET /api/tracking/runner_location_requests.php`

Commande PowerShell :

```powershell
$headers = @{
  "X-Api-Key" = "TA_CLE_API"
}

$response = Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/runner_location_requests.php?place_instance_id=PLACE-TEST-001&event_local_id=1&run_id=1" `
  -Method GET `
  -Headers $headers

$response | ConvertTo-Json -Depth 10
```

### 3. Annuler une demande coureur

`POST /api/tracking/cancel_runner_location_request.php`

Commande PowerShell :

```powershell
$headers = @{
  "Content-Type" = "application/json"
  "X-Api-Key"    = "TA_CLE_API"
}

$body = @{
  request_id        = 1
  place_instance_id = "PLACE-TEST-001"
  event_local_id    = 1
  run_id            = 1
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Uri "https://tracking.synoluvia.fr/api/tracking/cancel_runner_location_request.php" `
  -Method POST `
  -Headers $headers `
  -Body $body

$response | ConvertTo-Json -Depth 10
```

## Vérifications SQL

```sql
SELECT id, place_instance_id, event_local_id, run_id, event_name, phone, status, expires_at, created_at
FROM runner_location_requests
ORDER BY id DESC;

SELECT id, request_id, provider, phone, status, provider_message_id, error_message, created_at
FROM sms_logs
ORDER BY id DESC;
```

## Non-régression

- Aucun fichier licence n'est modifié.
- Aucune table existante n'est supprimée, renommée ou modifiée destructivement.
- Les endpoints LOT 2 et LOT 3 restent inchangés fonctionnellement.
- Le flux coureur ne collecte aucune donnée médicale.
- Le lien coureur est unique, non prédictible et limité dans le temps.

## Limites volontaires LOT 4

- La page coureur n'est pas encore livrée : elle est prévue au LOT 5.
- PLACE ne récupère pas encore automatiquement les positions coureur : cette intégration viendra plus tard.
- Le mode OVH SMS réel nécessite des identifiants OVHcloud SMS valides.