Aller au contenu principal

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​

Le SIG va chercher les interviews sur le serveur Survey Solutions : il n'y a pas d'endpoint où Survey Solutions pousserait des données.

Import de ménages​

EndpointMethodePermissionDescription
/api/menages/survey-solutions/importPOSTregistre.importImporte des interviews d'un questionnaire
/api/menages/survey-solutions/syncPOSTregistre.importSynchronise un questionnaire, ou tous les questionnaires ménage actifs
/api/menages/survey-solutions/questionnairesGETregistre.importQuestionnaires de type ménage
/api/menages/survey-solutions/statsGETregistre.menages_viewStatistiques d'import

Mise à jour de ménages existants​

EndpointMethodePermissionDescription
/api/menages/survey-solutions/updates/processPOSTregistre.menages_editApplique des interviews de mise à jour
/api/menages/survey-solutions/updates/syncPOSTregistre.menages_editSynchronisation manuelle des mises à jour
/api/menages/survey-solutions/updates/questionnairesGETregistre.menages_viewQuestionnaires de type mise à jour
/api/menages/survey-solutions/updates/statsGETregistre.menages_viewStatistiques de mise à jour

Synchronisation​

POST /api/menages/survey-solutions/sync
{ "questionnaireId": "<uuid du questionnaire dans le SIG>" }

Sans questionnaireId, tous les questionnaires ménage actifs sont synchronisés.

{
  "success": true,
  "message": "Synchronisation terminée: 120 ménage(s) importé(s), 25 doublon(s), 5 erreur(s)",
  "resultats": {
    "succes": 120,
    "doublons": 25,
    "erreurs": 5,
    "questionnaires": [
      { "id": "…", "title": "Questionnaire ménage", "result": { "…": "détail par interview" } }
    ]
  }
}

Erreurs : 404 Questionnaire non trouvé, 400 Aucun questionnaire de type ménage configuré.

Import ciblé​

POST /api/menages/survey-solutions/import
{
  "questionnaireId": "<uuid du questionnaire dans le SIG>",
  "interviews": [{ "id": "…", "key": "12-34-56-78" }]
}

questionnaireId est obligatoire (400 ID du questionnaire requis) et le questionnaire doit être de type ménage. Le détail de chaque interview porte un statut success, duplicate ou une erreur ; un doublon n'est pas réimporté.

Mapping des champs​

Menage​

Survey SolutionsPCH-SIGDescription
interview__idcollecteIdID unique de l'interview
menage_codecodeCode du menage
regionregion.nomNom de la region
secteursecteur.nomNom du secteur
localitelocalite.nomNom de la localite
gps__LatitudelatitudeLatitude GPS
gps__LongitudelongitudeLongitude GPS
gps__AccuracyprecisionGpsPrecision en metres
taille_menagetailleMenageTaille du menage
nb_enfants_0_4nbEnfants04Enfants 0-4 ans
nb_enfants_5_14nbEnfants514Enfants 5-14 ans
distance_ecoledistanceEcoleDistance ecole (km)
distance_santedistanceSanteDistance centre sante (km)

Chef de menage​

Survey SolutionsPCH-SIGDescription
chef_nomchefMenage.nomCompletNom complet
chef_sexechefMenage.sexeSexe (M/F)
chef_agechefMenage.ageAge
chef_telephonechefMenage.telephoneTelephone
chef_educationchefMenage.niveauEducationNiveau education

Logement​

Survey SolutionsPCH-SIGDescription
type_logementlogement.typeLogementType de logement
statut_occupationlogement.statutOccupationStatut d'occupation
nb_pieceslogement.nbPiecesNombre de pieces
materiau_murlogement.materiauMurMateriau des murs
materiau_toitlogement.materiauToitMateriau du toit
source_eaulogement.sourceEauSource d'eau
type_toilettelogement.typeToiletteType de toilettes

Nouveaux champs​

Distance aux services​

Les champs de distance aux services sociaux ont ete ajoutes :

ChampTypeDescription
distanceEcoledecimalDistance a l'ecole la plus proche (km)
distanceSantedecimalDistance au centre de sante (km)
distanceMarchedecimalDistance au marche (km)
distanceEauPotabledecimalDistance 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​

L'import ne remplace jamais un ménage existant : une interview déjà importée est comptée comme doublon et ignorée. La mise à jour d'un ménage existant passe par les routes /api/menages/survey-solutions/updates/*.

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​

ChampRegleMessage d'erreur
regionDoit 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​

Chaque interview en erreur apparaît dans le détail du résultat avec son index et le message d'erreur ; les autres interviews du lot sont importées.

Configuration​

Variables d'environnement​

SUSO_API_URL=https://survey.example.org
SUSO_API_USER=<utilisateur API>
SUSO_API_PASSWORD=<voir gestionnaire de secrets>
SUSO_WORKSPACE=<workspace>

Un projet peut avoir sa propre configuration de synchronisation (GET/PUT /api/projets/{id}/synchronisation) ; à défaut, la configuration globale s'applique.

Planification​

php bin/console app:survey-solutions:sync

Bonnes pratiques​

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