Integration Survey Solutions

Cette page documente l'integration entre PCH-SIG et Survey Solutions pour la collecte de donnees terrain.

Vue d'ensemble

Survey Solutions est un outil de collecte de donnees de la Banque Mondiale. L'integration permet de :

• Synchroniser les menages collectes sur le terrain
• Importer les donnees de l'enquete
• Mettre a jour les informations des menages existants

Architecture

┌─────────────────┐         ┌─────────────────┐         ┌──────────────┐
│  Survey         │  Sync   │    PCH-SIG      │  Store  │   Database   │
│  Solutions      │ ------> │    API          │ ------> │   PostgreSQL │
│  (Tablettes)    │         │                 │         │              │
└─────────────────┘         └─────────────────┘         └──────────────┘

Endpoints

Endpoint	Methode	Description
/api/collecte/sync	POST	Synchroniser les donnees Survey Solutions
/api/collecte/menages	POST	Importer un nouveau menage
/api/collecte/menages/{id}	PUT	Mettre a jour un menage
/api/collecte/status	GET	Statut de la derniere synchronisation

---

Synchronisation

Endpoint

POST /api/collecte/sync

Corps de la requete

{
  "source": "survey_solutions",
  "questionnaireId": "abc123",
  "data": [
    {
      "interview__id": "int-001",
      "menage_code": "MEN-OIO-001",
      "region": "Oio",
      "secteur": "Farim",
      "localite": "Farim Centro",
      "chef_nom": "Mamadou Diallo",
      "chef_sexe": "M",
      "taille_menage": 5,
      "nb_enfants_0_4": 1,
      "nb_enfants_5_14": 2,
      "latitude": 12.3456,
      "longitude": -15.6789,
      "distance_ecole": 1.5,
      "distance_sante": 2.3
    }
  ]
}

Reponse

{
  "success": true,
  "data": {
    "processed": 150,
    "created": 120,
    "updated": 25,
    "errors": 5,
    "errorDetails": [
      {
        "interview__id": "int-045",
        "error": "Region non trouvee: Unknown"
      }
    ]
  }
}

---

Mapping des champs

Menage

Survey Solutions	PCH-SIG	Description
interview__id	collecteId	ID unique de l'interview
menage_code	code	Code du menage
region	region.nom	Nom de la region
secteur	secteur.nom	Nom du secteur
localite	localite.nom	Nom de la localite
gps__Latitude	latitude	Latitude GPS
gps__Longitude	longitude	Longitude GPS
gps__Accuracy	precisionGps	Precision en metres
taille_menage	tailleMenage	Taille du menage
nb_enfants_0_4	nbEnfants04	Enfants 0-4 ans
nb_enfants_5_14	nbEnfants514	Enfants 5-14 ans
distance_ecole	distanceEcole	Distance ecole (km)
distance_sante	distanceSante	Distance centre sante (km)

Chef de menage

Survey Solutions	PCH-SIG	Description
chef_nom	chefMenage.nomComplet	Nom complet
chef_sexe	chefMenage.sexe	Sexe (M/F)
chef_age	chefMenage.age	Age
chef_telephone	chefMenage.telephone	Telephone
chef_education	chefMenage.niveauEducation	Niveau education

Logement

Survey Solutions	PCH-SIG	Description
type_logement	logement.typeLogement	Type de logement
statut_occupation	logement.statutOccupation	Statut d'occupation
nb_pieces	logement.nbPieces	Nombre de pieces
materiau_mur	logement.materiauMur	Materiau des murs
materiau_toit	logement.materiauToit	Materiau du toit
source_eau	logement.sourceEau	Source d'eau
type_toilette	logement.typeToilette	Type de toilettes

---

Nouveaux champs

Distance aux services

Les champs de distance aux services sociaux ont ete ajoutes :

Champ	Type	Description
distanceEcole	decimal	Distance a l'ecole la plus proche (km)
distanceSante	decimal	Distance au centre de sante (km)
distanceMarche	decimal	Distance au marche (km)
distanceEauPotable	decimal	Distance au point d'eau (km)

Ces champs sont utilises pour :

• Le calcul du score PMT
• L'analyse de vulnerabilite
• Le ciblage geographique

---

Gestion des conflits

Strategie de mise a jour

Par defaut, la synchronisation utilise la strategie "derniere mise a jour gagne" :

• Si collecteId existe : mise a jour des champs
• Si collecteId n'existe pas : creation

Champs proteges

Certains champs ne sont pas mis a jour apres la premiere collecte :

• code (code menage)
• dateEnregistrement
• createdAt

---

Validation des donnees

Regles de validation

Champ	Regle	Message d'erreur
region	Doit exister	"Region non trouvee"
tailleMenage	> 0	"Taille menage invalide"
latitude	-90 a 90	"Latitude hors limites"
longitude	-180 a 180	"Longitude hors limites"

Gestion des erreurs

Les erreurs sont retournees dans errorDetails :

{
  "errorDetails": [
    {
      "interview__id": "int-045",
      "field": "region",
      "value": "Unknown",
      "error": "Region non trouvee"
    }
  ]
}

---

Statut de synchronisation

Endpoint

GET /api/collecte/status

Reponse

{
  "success": true,
  "data": {
    "lastSync": "2026-06-12T08:30:00+00:00",
    "lastSyncStatus": "success",
    "totalProcessed": 150,
    "totalErrors": 0,
    "pendingSync": 0,
    "nextScheduledSync": "2026-06-12T20:00:00+00:00"
  }
}

---

Configuration

Variables d'environnement

SURVEY_SOLUTIONS_URL=https://survey.example.com
SURVEY_SOLUTIONS_API_USER=api_user
SURVEY_SOLUTIONS_API_KEY=secret_key
SURVEY_SOLUTIONS_WORKSPACE=pch_gb

Planification

La synchronisation peut etre planifiee via cron :

# Synchronisation quotidienne a 20h
0 20 * * * /usr/bin/php /app/bin/console app:sync-survey-solutions

---

Bonnes pratiques

:::tip Recommandations

1. Testez en preprod : Validez le mapping avant la production
2. Verifiez les GPS : Controlez la qualite des coordonnees
3. Monitoring : Surveillez les erreurs de synchronisation
4. Backup : Exportez les donnees Survey Solutions regulierement :::