# TRAIL DPS 4.2 - LOT 7 - APPLICATION - Tracking mobile complet foreground/offline

## 1. Numéro du lot
LOT 7

## 2. Bloc concerné
APPLICATION, avec deux compléments WEB strictement nécessaires à la recette mobile.

## 3. Objectif du lot
Stabiliser l'intégration mobile TrailDPS Tracker après validation LOT 6 : activation Option B, conservation locale du device_token, capture GPS immédiate puis toutes les 60 secondes en premier plan, écriture SQLite avant envoi réseau, retry, validation offline/retour réseau et préparation du passage en development build pour le background Android/iOS.

## 4. Analyse de l'existant concerné
Après réception du `src.zip` mobile, le projet Expo contient déjà `src/app/(tabs)/index.tsx`, `src/lib/*.ts` et `src/types/tracking.ts`. L'audit a montré que l'écran principal appelle des alias et types (`saveMobileConfig`, `capturePosition`, `getTrackingStats`, `TrackingLoopStatus`, etc.) non exposés par les modules LOT 6. Le présent ZIP corrige ces points et livre les fichiers directement sous `src/`, sans préfixe artificiel `mobile/`.

Côté OVH, les endpoints LOT 6 sont présents : `create_device_activation.php`, `activate_device.php`, `position.php`, `latest_positions.php`. Le endpoint `position.php` impose déjà `event_remote_id`, `place_instance_id`, `event_local_id`, `run_id` et `X-Device-Token`. Le endpoint `latest_positions.php` ne filtrait pas encore par `event_remote_id`, ce qui était une faiblesse multi-client pour la recette et les futurs lots PLACE.

## 5. Choix techniques et justification
- Expo/React Native conservé.
- `expo-location` pour la capture GPS foreground.
- `expo-sqlite` pour garantir que chaque position est écrite localement avant tentative réseau.
- `expo-network` pour journaliser l'état réseau et faciliter le diagnostic terrain.
- `expo-secure-store` pour conserver le device_token reçu une seule fois.
- Pas de modification PLACE dans ce lot.
- Ajout d'un endpoint `mobile_ping.php` pour contrôler, depuis le mobile, que la configuration active correspond bien à un device et à un binding valides.
- Renforcement de `latest_positions.php` par filtre obligatoire `event_remote_id`.

## 6. Fichiers créés
- `ovh/public/api/tracking/mobile_ping.php`
- `ovh/docs/TRAIL_DPS_4_2_LOT_7_APPLICATION_TRACKING_MOBILE_COMPLET.md`
## 7. Fichiers modifiés
- `src/types/tracking.ts`
- `src/lib/configurationStorage.ts`
- `src/lib/pendingPositionQueue.ts`
- `src/lib/foregroundTrackingService.ts`
- `src/app/(tabs)/index.tsx`
- `ovh/public/api/tracking/latest_positions.php`

## 8. Contenu exact du ZIP incrémental
Le ZIP contient uniquement les fichiers listés ci-dessus. Il ne contient pas PLACE, pas BUILD, pas de fichier inchangé.

## 9. Procédure de test détaillée
### 9.1 Préparation mobile
Depuis `C:\TRAIL_DPS_MOBILE\TrailDpsTracker` :

```powershell
npx expo install expo-camera expo-secure-store expo-location expo-sqlite expo-network
```

Copier le contenu du dossier `src/` du ZIP dans le dossier `src/` du projet mobile existant. Les chemins correspondent maintenant exactement au `src.zip` fourni.

Vérifier que `app.config.js` contient au minimum :

```js
plugins: [
  'expo-sqlite',
  ['expo-camera', { cameraPermission: 'Autoriser TrailDPS à scanner les QR codes d activation.' }],
  ['expo-location', {
    locationWhenInUsePermission: 'Autoriser TrailDPS à relever votre position pendant le suivi terrain.',
    locationAlwaysAndWhenInUsePermission: 'Autoriser TrailDPS à relever votre position en arrière-plan.'
  }]
]
```

### 9.2 Test activation
1. Générer un nouveau token avec `create_device_activation.php`.
2. Ne pas ouvrir le lien dans le navigateur avant l'application.
3. Scanner le QR code ou coller le lien dans l'application.
4. Vérifier que `activateDeviceFromText()` retourne une configuration contenant `device_token`, `device_uid`, `event_remote_id`, `place_instance_id`.
5. Enregistrer la configuration avec `saveTrackingConfiguration()`.

### 9.3 Test ping mobile
Après activation, appeler `mobilePing(configuration)` depuis l'application. Résultat attendu : `ok: true`, `binding_id`, `actor_type`, `server_time_utc`.

### 9.4 Test foreground 60 secondes
1. Lancer `startForegroundTracking(configuration)`.
2. Vérifier une capture immédiate.
3. Laisser l'application ouverte au moins 3 minutes.
4. Vérifier au serveur que plusieurs lignes apparaissent dans `tracking_positions` avec le bon `event_remote_id`.
5. Appeler `latest_positions.php` avec `event_remote_id`, `place_instance_id`, `event_local_id`, `run_id` et vérifier la dernière position.

### 9.5 Test offline / retry
1. Démarrer le tracking avec réseau actif.
2. Couper le réseau téléphone pendant 2 à 3 minutes.
3. Vérifier que la file SQLite augmente via `getForegroundTrackingStatus().queue_size`.
4. Rétablir le réseau.
5. Vérifier que la file se vide progressivement et que les positions sont envoyées dans l'ordre.

## 10. Procédure d'intégration
### Mobile
Copier `src/types/tracking.ts` vers `src/types/tracking.ts`.
Copier les fichiers `src/lib/*.ts` vers `src/lib/`.
Copier `src/app/(tabs)/index.tsx` vers `src/app/(tabs)/index.tsx`.
Adapter l'écran existant `src/app/(tabs)/index.tsx` pour appeler :
- `activateDeviceFromText()`
- `saveTrackingConfiguration()`
- `loadTrackingConfiguration()`
- `mobilePing()`
- `startForegroundTracking()`
- `stopForegroundTracking()`
- `getForegroundTrackingStatus()`

### OVH
Copier :
- `ovh/public/api/tracking/mobile_ping.php`
- `ovh/public/api/tracking/latest_positions.php`
- `ovh/docs/TRAIL_DPS_4_2_LOT_7_APPLICATION_TRACKING_MOBILE_COMPLET.md`

Aucune migration SQL n'est nécessaire pour ce lot.

## 11. Procédure de déploiement
Déployer les fichiers OVH par remplacement ciblé. Conserver une sauvegarde du `latest_positions.php` actuel avant remplacement.

Pour le mobile, tester d'abord en Expo Go pour le foreground/offline. Pour le background, passer ensuite en development build :

```powershell
npx expo install expo-dev-client
npx expo prebuild
```

Le background réel ne doit pas être déclaré validé sous Expo Go.

## 12. Critères de recette
- Activation Option B fonctionnelle par lien ou QR.
- `device_token` réel absent du QR/SMS et présent uniquement après activation.
- `mobilePing()` valide le device et le binding.
- Première position capturée immédiatement au démarrage.
- Nouvelle position capturée environ toutes les 60 secondes en foreground.
- Position écrite en SQLite avant envoi réseau.
- Coupure réseau sans perte de position capturée.
- Resynchronisation après retour réseau.
- `latest_positions.php` filtre par `event_remote_id`.
- Aucun fichier PLACE modifié.

## 13. Points de vigilance / risques / non-régression
- Expo Go reste insuffisant pour valider l'écran verrouillé et le background réel.
- Le passage background Android/iOS devra être traité avec un development build et une recette séparée.
- La fréquence 60 secondes est une cible terrain ; elle peut être dégradée par l'OS, la batterie, la précision GPS, ou le réseau.
- Le SMS coureur OVH reste à durcir dans un lot dédié, notamment avec lien court interne.
- Le décalage d'heure serveur doit être surveillé ; les timestamps applicatifs de tracking restent en UTC pour éviter les ambiguïtés.