# TRAIL DPS 4.2 - LOT 6 - Strategie application mobile / tracking terrain

## 1. Numero du lot

LOT 6

## 2. Bloc concerne

APPLICATION

## 3. Objectif du lot

Choisir et documenter la strategie mobile permettant le tracking regulier terrain des acteurs :

- SECOURS
- OUVREURS
- FERMEURS

Le lot 6 ne modifie pas le code PLACE et ne modifie pas encore le backend OVH. Il fixe la strategie de production, les prerequis de developpement, le protocole cible et la procedure de validation terrain avant le LOT 7.

Point de vigilance utilisateur : le developpement mobile est nouveau dans le projet. La procedure doit donc etre tres guidee, progressive et verifiable etape par etape.

## 4. Analyse de l'existant concerne

### 4.1 Backend OVH deja disponible

Les lots precedents ont cree le backend tracking avec :

- enregistrement des devices ;
- binding device / evenement / instance PLACE / acteur ;
- reception des positions GPS ;
- recuperation des dernieres positions ;
- demandes de localisation coureur ;
- page coureur one-shot ;
- journalisation SMS/API/erreurs.

Endpoints deja presents :

- `POST /api/tracking/register_device.php`
- `POST /api/tracking/bind_device.php`
- `POST /api/tracking/position.php`
- `GET  /api/tracking/latest_positions.php`
- `POST /api/tracking/create_runner_location_request.php`
- `POST /api/tracking/submit_runner_location.php`

### 4.2 Tables distantes deja presentes

Tables tracking existantes :

- `tracking_devices`
- `tracking_bindings`
- `tracking_positions`
- `runner_location_requests`
- `sms_logs`
- `tracking_api_logs`
- `tracking_error_logs`

Les colonnes `event_remote_id` existent deja dans plusieurs tables mais doivent devenir obligatoires fonctionnellement dans les prochains lots avant exploitation commerciale.

### 4.3 Separation des flux

Flux coureur :

- SMS ;
- lien web one-shot ;
- GPS navigateur ;
- une seule position ;
- aucune application mobile ;
- aucune donnee medicale.

Flux equipes terrain :

- application mobile native ;
- GPS en arriere-plan ;
- envoi periodique toutes les 60 secondes ;
- file locale offline ;
- reprise reseau ;
- identification device ;
- rattachement a un evenement distant.

## 5. Choix techniques et justification

### 5.1 Decision principale

La solution cible retenue est une application mobile interne :

`TrailDPS Tracker`

Elle sera developpee progressivement, avec Android en priorite, puis iOS dans un second temps.

### 5.2 Pourquoi ne pas retenir Traccar comme solution cible

Traccar Client reste une reference utile pour comprendre le tracking GPS, mais n'est pas retenu comme dependance cible principale car :

- l'ergonomie n'est pas controlee par TRAIL DPS ;
- les changements futurs de protocole, d'application ou de distribution ne sont pas maitrises ;
- le binding metier SECOURS / OUVREURS / FERMEURS serait moins naturel ;
- la commercialisation du logiciel doit eviter une dependance forte a un outil tiers non controle.

Traccar peut rester un outil de comparaison ou de secours en test, mais le developpement doit viser une application interne.

### 5.3 Technologie recommandee

Technologie retenue pour le demarrage :

`React Native avec Expo en development build`

Raisons :

- une base de code unique Android/iOS ;
- apprentissage plus accessible ;
- ecosysteme large ;
- API HTTP simple ;
- possibilite de commencer par Android sans Mac ;
- possibilite d'evoluer vers iOS ensuite ;
- gestion possible de la geolocalisation background via modules natifs Expo/React Native.

Important : `Expo Go` ne doit pas etre considere comme suffisant pour valider le tracking background. Il faut utiliser une development build ou une build native, car le tracking en arriere-plan depend de permissions et declarations natives.

### 5.4 Alternative Flutter

Flutter reste une option techniquement valable, mais elle est moins prioritaire pour ce projet car :

- l'apprentissage initial peut etre plus lourd si l'utilisateur vient deja d'environnements web/Python/PHP ;
- le tracking background reste de toute facon soumis aux memes contraintes natives Android/iOS ;
- React Native / Expo permet une montee en competence plus progressive.

### 5.5 PWA interdite pour le tracking continu

Une PWA ou une page web ne doit pas etre utilisee comme canal principal de tracking regulier car :

- suspension possible en arriere-plan ;
- comportement variable selon iOS/Android ;
- fiabilite insuffisante ecran verrouille ;
- permissions navigateur fragiles ;
- perte possible de positions.

La PWA/page web reste uniquement adaptee au flux ponctuel coureur.

## 6. Architecture cible mobile

```text
[TrailDPS Tracker - smartphone terrain]
  - GPS foreground/background
  - envoi toutes les 60 secondes
  - file locale si reseau absent
  - retry automatique
  - logs terrain simples

        HTTPS
          ↓

[API Tracking OVH]
  - authentification device_token
  - controle event_remote_id / place_instance_id / run_id
  - reception positions
  - stockage tracking_positions
  - logs API / erreurs

          ↓

[PLACE Desktop]
  - synchronisation future
  - stockage SQLite local
  - affichage LIVE DPS
  - filtres SECOURS / OUVREURS / FERMEURS
```

## 7. Regle multi-client obligatoire

Avant exploitation commerciale, chaque evenement PLACE doit obtenir un identifiant distant serveur :

`event_remote_id`

Flux cible :

```text
PLACE ouvre un evenement
→ appelle OVH : create_or_get_remote_event
→ OVH renvoie event_remote_id
→ PLACE le stocke localement
→ tous les bindings, SMS, positions et devices utilisent event_remote_id
```

Regle stricte :

- `event_local_id` seul est interdit pour filtrer les donnees serveur ;
- `place_instance_id + event_local_id` n'est pas suffisant pour une commercialisation multi-client ;
- le filtrage serveur doit utiliser `event_remote_id + place_instance_id` ;
- `event_local_id` reste utile comme information de mapping/debug.

## 8. Binding mobile cible

Un device mobile doit etre rattache a :

- `event_remote_id`
- `place_instance_id`
- `run_id`
- `actor_type`
- `local_team_id` pour une equipe SECOURS
- ou `local_staff_team_id` pour un OUVREUR / FERMEUR

Rappels :

- un token unique par telephone ;
- token revocable ;
- aucun token commun ;
- aucun secret OVH dans l'application ;
- aucune donnee coureur dans l'application equipe ;
- aucune donnee medicale.

## 9. Protocole GPS cible

Endpoint actuel :

`POST /api/tracking/position.php`

Headers :

```text
Content-Type: application/json
X-Device-Token: DEVICE_TOKEN
```

Payload cible :

```json
{
  "device_uid": "TEL-SECOURS-001",
  "place_instance_id": "PLACE-XXXX",
  "event_remote_id": "EVT-2026-000001",
  "event_local_id": 1,
  "run_id": 1,
  "latitude": 44.1000000,
  "longitude": 3.0800000,
  "accuracy": 8,
  "speed": 1.2,
  "heading": 120,
  "battery": 87,
  "recorded_at_device": "2026-05-02T13:40:00Z",
  "app_version": "1.0.0",
  "platform": "android",
  "network_status": "online",
  "provider": "gps",
  "offline_queue_size": 0
}
```

Regle : `event_remote_id` doit devenir obligatoire a partir du lot qui mettra en place la creation/recuperation de l'evenement distant.

## 10. Fonctionnalites minimales de TrailDPS Tracker

### 10.1 Ecran configuration

Champs :

- URL serveur ;
- device_uid ;
- device_token ou code d'activation ;
- nom affiche ;
- categorie : SECOURS / OUVREUR / FERMEUR ;
- event_remote_id ;
- place_instance_id ;
- run_id.

Evolution recommandee : configuration par QR code generee depuis PLACE.

### 10.2 Ecran tracking

Affichage :

- statut GPS : actif / inactif ;
- statut autorisation localisation ;
- dernier envoi ;
- derniere latitude / longitude ;
- precision GPS ;
- batterie ;
- reseau ;
- nombre de positions en attente ;
- bouton Demarrer ;
- bouton Arreter.

### 10.3 Ecran diagnostic

Affichage :

- derniere erreur API ;
- nombre de tentatives ;
- dernier code HTTP ;
- taille de la file offline ;
- version application ;
- plateforme ;
- mode economie batterie.

## 11. Gestion offline obligatoire

Regle terrain : ne jamais perdre une position capturee.

Comportement :

- si reseau OK : envoi immediat ;
- si reseau KO : stockage local ;
- reprise reseau : envoi sequentiel des positions en attente ;
- chaque position garde son `recorded_at_device` ;
- chaque tentative augmente `retry_count` ;
- les erreurs sont visibles dans l'ecran diagnostic.

Table locale mobile minimale :

`pending_positions`

Champs :

- id
- latitude
- longitude
- accuracy
- speed
- heading
- battery
- recorded_at_device
- payload_json
- sent_at
- status
- retry_count
- last_error

## 12. Frequence GPS

Reglage par defaut :

`60 secondes`

Modes possibles :

- 30 s : operation critique ;
- 60 s : mode normal ;
- 120 s : economie batterie.

Seuils LIVE DPS :

- fresh : derniere position <= 2 minutes ;
- old : > 2 minutes et <= 10 minutes ;
- stale : > 10 minutes ;
- unknown : aucune position.

## 13. Guide tres progressif pour demarrer le developpement mobile

### 13.1 Poste Windows - prerequis Android

Etape 1 - Installer Node.js LTS

- Installer Node.js version LTS depuis le site officiel.
- Verifier ensuite dans PowerShell :

```powershell
node -v
npm -v
```

Etape 2 - Installer Android Studio

Pendant l'installation, conserver :

- Android SDK ;
- Android SDK Platform ;
- Android Virtual Device ;
- Android Emulator.

Etape 3 - Creer un emulateur Android

Dans Android Studio :

- ouvrir Device Manager ;
- creer un telephone virtuel type Pixel ;
- choisir une image Android recente ;
- demarrer l'emulateur.

Etape 4 - Installer Git

Verifier :

```powershell
git --version
```

Etape 5 - Creer le projet mobile hors du depot PLACE

Recommandation : creer un dossier separe :

```text
C:\TRAIL_DPS_MOBILE\TrailDpsTracker
```

Ne pas melanger l'application mobile avec `C:\TRAIL_DPS\SRC` au demarrage.

Commande proposee plus tard au LOT 7 :

```powershell
npx create-expo-app@latest TrailDpsTracker
```

### 13.2 iOS - contrainte importante

Pour compiler et tester iOS reellement :

- Mac obligatoire ;
- Xcode obligatoire ;
- compte Apple Developer recommande pour distribution ;
- tests background a faire sur iPhone physique, pas seulement simulateur.

Conclusion : Android doit etre valide en premier, iOS ensuite.

## 14. Procedure de validation terrain LOT 6

Le LOT 6 ne livre pas encore l'application, mais fixe la recette de validation du LOT 7.

Tests attendus au LOT 7 :

1. demarrer l'application ;
2. enregistrer/configurer un device ;
3. binder le device a un evenement ;
4. envoyer une position foreground ;
5. verrouiller l'ecran ;
6. attendre 3 a 5 cycles de 60 secondes ;
7. verifier la remontee serveur ;
8. couper le reseau ;
9. verifier la file offline ;
10. retablir le reseau ;
11. verifier l'envoi des positions en attente ;
12. verifier la table `tracking_positions` ;
13. verifier `latest_positions.php` ;
14. verifier que l'evenement filtre par `event_remote_id` ne remonte pas les positions d'un autre evenement.

## 15. Nettoyage donnees OVH avant production

Decision validee : un script de purge sera ajoute dans le dernier lot avant passage en production, ou dans un lot de durcissement dedie.

Script cible :

`ovh/tools/cleanup_tracking_data.php`

Regles :

- supprimer `tracking_positions` de plus de 30 jours ;
- supprimer `tracking_api_logs` de plus de 30 jours ;
- supprimer `tracking_error_logs` de plus de 30 jours ;
- supprimer `sms_logs` de plus de 30 jours ;
- supprimer ou anonymiser `runner_location_requests` de plus de 30 jours ;
- conserver `tracking_devices` ;
- conserver `tracking_bindings` sauf revocation/archivage.

Execution cible :

- CRON OVH quotidien ;
- log de purge ;
- aucun DROP ;
- aucune suppression de structure.

## 16. Fichiers crees

- `ovh/docs/TRAIL_DPS_4_2_LOT_6_STRATEGIE_APPLICATION_MOBILE.md`

## 17. Fichiers modifies

Aucun fichier existant modifie.

## 18. Contenu exact du ZIP incrementiel

```text
ovh/
└── docs/
    └── TRAIL_DPS_4_2_LOT_6_STRATEGIE_APPLICATION_MOBILE.md
```

## 19. Procedure de test detaillee

### Test documentaire

1. Decompresser le ZIP incrementiel a la racine du projet contenant `ovh`.
2. Verifier la presence du fichier :

```text
ovh/docs/TRAIL_DPS_4_2_LOT_6_STRATEGIE_APPLICATION_MOBILE.md
```

3. Verifier que le ZIP ne contient aucun fichier de code modifie.
4. Verifier que le document contient :

- decision application interne ;
- event_remote_id obligatoire ;
- binding mobile complet ;
- protocole GPS cible ;
- guide d'installation debutant ;
- validation terrain ;
- purge 30 jours avant production.

## 20. Procedure d'integration

1. Sauvegarder le dossier `ovh/docs` si necessaire.
2. Decompresser le ZIP incrementiel a la racine du projet.
3. Aucun script SQL a executer.
4. Aucun deploiement serveur obligatoire pour ce lot.
5. Aucun redemarrage applicatif.

## 21. Procedure de deploiement APPLICATION

Aucun deploiement applicatif mobile n'est realise dans ce lot.

Preparer uniquement le poste de developpement :

- Node.js LTS ;
- Git ;
- Android Studio ;
- Android SDK ;
- emulateur Android ;
- telephone Android physique pour les tests background reels.

## 22. Criteres de recette

Le LOT 6 est valide si :

- la strategie mobile cible est claire ;
- Traccar n'est plus une dependance cible ;
- React Native / Expo development build est retenu pour demarrer ;
- Android est priorise ;
- iOS est identifie comme second temps avec contrainte Mac/Xcode ;
- `event_remote_id` est confirme comme obligatoire ;
- le binding mobile cible est documente ;
- le protocole GPS cible est documente ;
- la procedure d'installation debutant est presente ;
- la purge OVH 30 jours est planifiee pour le dernier lot avant production.

## 23. Points de vigilance / risques / non-regression

### 23.1 Risques techniques

- Le tracking background ne peut pas etre valide uniquement dans un navigateur.
- Expo Go ne suffit pas pour valider un comportement background fiable.
- Les tests doivent etre faits sur telephone physique.
- iOS est plus contraignant qu'Android pour le background.
- La batterie peut limiter la frequence reelle.
- Certains constructeurs Android coupent les applications en arriere-plan.

### 23.2 Risques multi-client

- Ne jamais utiliser `event_local_id` seul.
- Ne jamais synchroniser PLACE sans verifier `event_remote_id`.
- Ne jamais afficher dans PLACE des positions d'un autre evenement.

### 23.3 Risques securite

- Aucun secret OVH dans l'app mobile.
- Aucun token commun.
- Aucun stockage medical.
- Pas de donnee coureur dans l'application terrain.
- Tokens revocables.

### 23.4 Non-regression

Ce lot ne modifie aucun fichier code existant. Il ne peut donc pas impacter :

- LIVE DPS ;
- interventions ;
- SMS coureur ;
- API tracking actuelle ;
- licence ;
- SQLite PLACE ;
- build Windows.