# HYDRALMA TERRAIN — HANDOFF IA CANONIQUE

**Dernière consolidation : 12 août 2026 — 23:12 (Casablanca)**  
**But :** permettre à un nouveau chat de reprendre le projet sans demander à l'utilisateur de réexpliquer les décisions déjà validées.

## 1. Objectif actuel

Stabiliser le socle **Hydralma Terrain + Hydralma Pilotage + Gateway**, protéger les versions connues dans Git, puis reprendre les améliorations **une par une** avec test réel entre chaque changement.

### Socle de reprise retenu

- **Hydralma Terrain 0.2.6** — `main`, commit `952d72f3...` — base mobile actuellement préférée pour la stabilité réelle.
- **Hydralma Pilotage 3.3.8** — backend actuel à **figer et auditer** avant de le déclarer production stable.
- **Gateway 1.0.6** — base Gateway actuelle.
- **Terrain 0.2.7** reste **expérimentale**, branche `agent/terrain-0.2.7-settings-arrival-gps`, PR #6 non fusionnée. Ne pas la merger tant que ses fonctions n’ont pas été réintroduites et testées séparément.
- **PR #7 — `agent/auth-password-fallback-from-0.2.6`** : nouvelle candidate créée strictement depuis 0.2.6. Ajoute le fallback login + mot de passe sans reprendre 0.2.7. Code présent, non mergé.
- **Important pour la recette 0.2.6 + 3.3.8 :** garder la règle GPS d'arrivée sur **OFF ou OPTIONAL**, pas `REQUIRED`. Le comportement `Sur place` avec coordonnées obligatoires appartient à la logique introduite en 0.2.7.

## 2. Rôles officiels — exactement 4

1. **Niveau 1 — Administrateur** : administration Hydralma, accès complet.
2. **Niveau 2 — Superviseur interne** : technicien chef interne ; contrôle les techniciens internes et externes.
3. **Niveau 3 — Superviseur externe** : sous-traitant / technicien chef externe ; contrôle uniquement ses propres techniciens.
4. **Niveau 4 — Technicien** : technicien interne ou externe ; accès limité à ses missions et fonctions autorisées.

**Important :** interne/externe est une appartenance organisationnelle, pas un 5e rôle.

## 3. Authentification validée

- Téléphone autorisé / de confiance.
- Biométrie quand disponible.
- **Login + mot de passe obligatoire comme solution de repli lorsque la biométrie/empreinte n’est pas disponible.**
- Backend déjà disponible : Pilotage 3.3.8 expose `password_login` et Gateway 1.0.6 expose `/api/v1/auth/password-login`. Le serveur exige toujours que le login corresponde au compte lié au téléphone autorisé.
- Flutter PR #7 : activation sans biométrie autorisée par code d’activation ; déverrouillage login + mot de passe (+ code 2FA facultatif) uniquement si biométrie inutilisable.
- Prévoir révocation et changement de téléphone.
- Pilotage/serveur reste l'autorité des permissions ; Flutter ne doit pas devenir l'unique source de vérité.

### Audit Pilotage 3.3.8 des 4 niveaux

Le backend contient déjà les 4 profils d’accès attendus :

- `HYDRALMA_ADMIN` → N1 Administrateur → scope `ALL`.
- `HYDRALMA_SUPERVISOR` → N2 Superviseur interne → scope `ALL` (interne + externe selon politique).
- `SUBCONTRACTOR_CHIEF` → N3 Superviseur externe → scope `SUBCONTRACTOR`, donc uniquement son équipe/sous-traitant.
- `TECH_LEVEL4` → N4 Technicien → uniquement ses missions internes ou externes selon son rattachement.

Les anciens champs techniques `role=CHIEF/TECH` existent encore dans le portail pour compatibilité, mais les privilèges opérationnels sont pilotés par `access_profile`. Ne pas créer de nouveaux rôles métier pour les remplacer sans nécessité.

Audit complémentaire : Pilotage 3.3.8 permet déjà de corriger `display_name` et le lien utilisateur interne depuis la supervision sans recréer le compte. La suppression contrôlée d’une mission existe aussi côté backend/API (`mission_delete` / `deleteMission`) avec blocages et audit ; l’UI mobile reste à vérifier/compléter.

## 4. Architecture métier Mission Terrain

La Mission Terrain est une couche opérationnelle au-dessus des objets existants.

```text
Dolibarr / données existantes
        ↓
Hydralma Pilotage — Mission Terrain
        ↓
Hydralma Terrain Gateway
        ↓
Application Flutter Hydralma Terrain
```

Une mission peut :

- être liée à une intervention/facture existante ;
- **exister sans facture préalable** (appel client, entretien, SAV, visite technique) ;
- être facturée ou reliée plus tard ;
- avoir son propre historique d'audit ;
- avoir plusieurs paiements ;
- contenir les pièces réellement utilisées, facturables ou non facturées/garantie.

## 5. Workflow mobile cible

```text
Mission
  ↓
En route
  ↓
Sur place
  ↓
Rapport terrain / pièces / mesures / photos
  ↓
Encaissement si applicable
  ↓
Validation client selon règles
  ↓
Intervention effectuée
  ↓
Retour accueil + historique
```

Les contrôles doivent être configurables selon les règles serveur. Le mobile doit rester simple pour le niveau 4.

## 6. Fonctions déjà présentes ou engagées

- Application Flutter Android + architecture iPhone.
- Téléphone autorisé + biométrie.
- À faire / Historique.
- En route / Sur place.
- Retour automatique accueil après **Intervention effectuée** — testé OK dans l'historique.
- Montant à encaisser distinct du prix commercial — règle à protéger contre toute régression.
- Travaux réalisés.
- Commentaire technique facultatif.
- Pièces / cartouches utilisées.
- N° de série, TDS avant/après, pression.
- Photos avant/après.
- Compression + reprise d'upload persistante/idempotente.
- GPS ponctuel configurable, sans suivi permanent.
- FR + AR.
- Pilotage 3.2.7 : lignes billables/non facturées, paiements partiels/différés, `mission_report`, `mission_delete_line`, synchronisation mobile ; PHP lint 48/48 OK.
- Gateway 1.0.6 : support des attachements/photos.

## 7. Fonctions présentes dans 0.2.7 à récupérer séparément

Ne pas reprendre toute la 0.2.7 d'un bloc. Réintroduire et tester séparément :

1. Ville + adresse complète.
2. Écran Paramètres.
3. Langue mémorisée FR/AR/Automatique.
4. GPS enregistré au clic **Sur place**.

La 0.2.7 a modifié beaucoup de fichiers en un seul lot et a été signalée comme problématique en usage réel malgré des builds GitHub réussis.

## 8. Bugs / anomalies encore ouvertes ou à revalider

### P0

- Certaines interventions **Terminées** laissent encore des boutons d'action/planification actifs. Une mission terminée doit devenir lecture seule sauf action administrative contrôlée.
- Faire une recette réelle complète sur le trio 0.2.6 / 3.3.8 / 1.0.6 avec les 4 niveaux.
- Tester ancienne mission, mission rouverte, mission terminée et statuts legacy.
- Tester réseau coupé, reprise photos et idempotence paiements.
- Login + mot de passe fallback : **code développé sur PR #7, recette réelle encore requise**.
- **GitHub Actions actuellement bloqué** : les jobs Android/iOS de PR #7 n’ont pas démarré. Annotation GitHub : paiement récent échoué ou spending limit à augmenter. Ne pas interpréter cet échec comme un bug du code.
- Auditer les scopes réels N2/N3/N4.

### À revalider

- Recherche client par numéro de téléphone.
- Liste tiers qui s'arrêtait à M.
- Résultats tiers dans une liste déroulante compacte.
- Heure de rendez-vous affichée correctement.
- Historique mobile et montants encaissés selon confidentialité.

### À faire

- Clic sur ligne/statut « Ouvert » doit ouvrir la mission, pas uniquement la référence.
- Suppression contrôlée d'une mission avec droits + audit.
- Possibilité de corriger/modifier le compte utilisateur depuis supervision.
- Contrôle admin de la période d'historique visible sur le téléphone d'un technicien, voire désactivation par technicien.
- Nettoyer les doublons UI « Validation mobile » / « Portail mobile sécurisé » s'ils répètent le menu gauche.

## 9. Encaissements / relevés / compensation

Règles historiques à conserver :

- Compensation nette sans faux mouvement de trésorerie.
- Exemple historique : Omar détient 1 490 MAD, Hydralma lui doit 220 MAD, reversement réel = 1 270 MAD.
- Prévoir reprise idempotente si un règlement échoue partiellement.
- Pour relevés mensuels : toutes les transactions éligibles cochées par défaut ; exclusion exceptionnelle avec motif.
- Ne pas confondre **transaction reportée** et **solde reporté**.
- Au règlement : **verser maintenant** ou **reporter le solde** au relevé suivant sans créer de faux virement.
- Cible : 1 relevé principal / sous-traitant / mois.
- Le mot **Dolibarr ne doit pas apparaître sur le relevé**.

## 10. Gestion Git à mettre en place maintenant

### Terrain

Créer des tags/releases au minimum :

- `v0.2.4-financial-reference`
- `v0.2.5-fallback`
- `v0.2.6-stable`
- `v0.2.7-experimental`

### Pilotage

Créer dépôt privé séparé : `matris9/hydralma-pilotage`.

Conserver les jalons connus, notamment 3.2.6 validée, 3.2.7, 3.2.8 recovery et 3.3.8 candidate actuelle.

### Gateway

Créer dépôt privé séparé : `matris9/hydralma-terrain-gateway`.

Conserver 1.0.3, 1.0.5, 1.0.6 avec 1.0.6 comme base actuelle.

## 11. Garde-fous pour tout futur chat

- Lire ce handoff avant de proposer une modification.
- Ne pas demander à l'utilisateur de réexpliquer une décision déjà écrite ici.
- Ne pas inventer de rôles supplémentaires : 4 niveaux uniquement tant que l'utilisateur ne change pas explicitement la règle.
- Ne pas merger 0.2.7 comme base stable.
- Une amélioration importante à la fois : branche → changement → test → commit → prochaine amélioration.
- Ne jamais exposer les prix détaillés au technicien niveau 4 si la permission ne l'autorise pas.
- Le montant à encaisser est une instruction serveur distincte du prix commercial.
- Pas de tracking GPS permanent.
- Pendant la baseline 0.2.6 + 3.3.8, ne pas activer GPS arrivée `REQUIRED`; utiliser OFF/OPTIONAL jusqu'à la réintroduction isolée de cette fonction.
- Aucun secret, mot de passe, keystore, clé privée ou credential ne doit être ajouté à ce site/handoff.
- Ne pas merger la **PR #7** tant que CI Android/iOS et test réel sur téléphone sans biométrie ne sont pas validés.
- Après chaque version importante, mettre à jour : **Versions + Checklist + Incidents + Décisions + Journal + Prochaine action**.

## 12. Prochaine séquence de travail

1. **Débloquer GitHub Actions (Billing & plans / spending limit)** puis relancer Android + iOS sur PR #7.
2. Générer l’APK de PR #7 et tester un téléphone sans biométrie : activation par code → login/mot de passe → missions.
3. Si test OK, figer cette amélioration comme prochaine version stable candidate ; sinon corriger uniquement le défaut observé.
4. Créer les dépôts privés séparés `hydralma-pilotage` et `hydralma-terrain-gateway`, puis tags/releases Terrain.
5. Exécuter la recette métier complète par rôle sur le trio retenu.
6. Finaliser permissions/confidentialité puis réintroduire les bonnes fonctions de 0.2.7 une par une.
7. Continuer Mission Terrain avancée et relevés mensuels.

---

**Instruction recommandée au démarrage d'un nouveau chat :**  
« Lis ce handoff comme source de vérité du projet Hydralma Terrain. Ne me redemande pas ce qui est déjà validé. Commence par me dire le socle actuel, les P0 ouverts et la prochaine action, puis continue le projet. »