# Stratégie de synchronisation Pearl / Queen

Ce document décrit la stratégie de synchronisation des applications web Pearl et Queen avec leurs api respectives.

_**Rappel** : Il y a dans Pearl, deux types de données synchronisées :_
* les données liées à une synchronisation manuelle de l'utilisateur
* les données synchronisées en continue [à instruire, non décrit dans cette note]

**Principe** : La synchro dans Queen est de deux types :
* synchronisation déclenchée depuis une application parente (cas de Pearl+Queen)
* synchronisation déclenchée (mode standalone) à l'appel d'une ressource, persistance dans le navigateur des ressources requises (model, data, nomemclateures), fonctionnement en ligne uniquement.

## Pearl

### Déclenchement de la synchronisation

La synchronisation est déclenchée par l'intermédiaire du bouton "Synchroniser" présent dans la bandeau du haut dans Pearl.

### Stratégie - flow

**Note :** Pour passer d'une étape (numérotation de 1 à 7) _A_ à une étape _B_, il faut que l'étape _A_ aie réussi

1. **Authentification (pour Pearl):**

- Selon le mode (auth ou anonyme), l'application Pearl récupère l'identité de l'enquêteur ou simule une identité fictive : "Guest"

--> Auth : (Oauth2) : Récupération d'un jeton keycloak
--> Anonyme : "Guest" par défaut.

2. **Envoi des informations de gestion à Pearl-Back-Office:**

- Envoie (PUT) les données modifiées dans Pearl au serveur :
- toutes les UEs (celles marquées à "à Transmettre" et les autres aussi)
(toutes les données : nouvel état, commentaire, adresse, champ modifié (nom, prénom, téléphone,...)) sont envoyés au serveur

3. **Nettoyage :** Suppression totale de la table Pearl du navigateur

4. **Récupérer l'état attendu de Pearl :** Appel à Pearl-Back-Office (GET sur l'API) pour récupérer :

- toutes les données d'UEs liées à l'enquêteur ([GET /survey-units](https://gitlab.insee.fr/sic/collecte-enqueteur/pearl-api/-/wikis/Description-de-l'api-Sabiane/Description-des-endpoints-PEARL#get-survey-units-) --> les listes des UE de l'enquêteur, y compris les informations organisationelles sur les campagnes)

5. **Récupération des données :** Récupérer les données complètes des UEs, (état, commentaire, commentaire DEM, adresse, ...)

- des GET sur toutes les UE du 4/

**Remarque :** la synchronisation annule et remplace les données à chaque fois, légerement gourmand mais sans objet sur le volume des données traitées par Pearl.

**Remarque :** une synchronisation de 25 UE prend moins d'une seconde.

6. **Notifier Queen:**

- Demande à Queen de se synchroniser
- Envoi d'un évènement pour notifier l'application Queen afin qu'elle lance sa stratégie de synchronisation

7. **Attente de l'évènement de fin de synchronisation de Queen**

**Remarque :** timeout de 5 secondes.

## Queen

**Rappel** : déclenchement de la synchronisation de deux manières :
- depuis une application parente (par exemple, url du type https://pearl.insee.fr/queen/survey-unit/\${idSU})
- ou à l'appel d'une ressource si l'application est autonome (par exemple, url du type https://queen.insee.fr/queen/questionnaire/\${questionnaire}/survey-unit/\${idSU})

**Remarque 1 :** les différentes versions des modèles de questionnaire et nomenclatures sont gérés par des urls différentes (si pas de modification de l'url alors pas de mise à jour, si modification alors la phase de nettoyage aura supprimée l'ancienne ressource, l'étape suivante, recupèrera la nouvelle version de cette ressource).

**Remarque 2 :** Les objets de type "données collectées", sont remplacées systématiquement depuis l'api (permettra à terme, d'avoir une possibilité de multimode avec données modifiées dans un autre mode puis "descendue" sur Queen).

### Stratégie - flow

#### Queen autonome (mode non embarqué dans Pearl)

1. **Authentification :** Selon le mode d'authentification (auth ou anonyme) : récupération de l'identité de l'enquêteur (ou Guest le cas échéant).

2. **Récupérer les données nécessaires pour l'affichage de Queen :**
Le contexte d'affichage de Queen est définit par son URL, exemple :
https://queen.insee.fr/queen/questionnaire/\${questionnaire}/survey-unit/\${idSU}

Queen a donc besoin dans cet exemple :

- du modèle de questionnaire \${questionnaire} et de ses nomenclatures (todo)
- des éventuelles données collectées de \${idSU}

Nettoyage complet des données du navigateur
Get sur l'api Queen pour :

- récupérer le modèle de questionnaire
- la liste des ressources associer au questionnaire
- récupérer les ressources
- récupérer les éventuelles données collectées

#### Queen embedded (mode embarqué dans Pearl par exemple)

**Rappel :** La synchronisation dans Queen n'est pas déclenché directement pas l'utilisateur.
Elle est déclenchée indirectement par le bouton "Synchroniser" de Pearl.
Les GET ne sont pas parallélisés

1. **Authentification :** Selon le mode d'authentification (auth ou anonyme) : récupération de l'identité de l'enquêteur (ou Guest le cas échéant

2. **Envoi des données collectées :**

Envoie des données collectées à l'api Queen :

- Envoi des données collectées (y compris state data) dans Queen (stockées dans le navigateur) au serveur (PUT /survey-unit/\{idSU} ).
- Envoi des paradonnées collectées dans Queen (stockées dans le navigateur) au serveur.

3. **Nettoyage :** Suppression de la base de données Queen du navigateur

4. **Récupérer l'état attendu de Queen et les données :**

GET sur l'API Queen pour récupérer :

- la liste de toutes les campagnes ([GET /campaigns](https://gitlab.insee.fr/sic/collecte-enqueteur/queen-api/-/wikis/Description-de-l'api/Endpoints-de-l'api#get-campaigns-liste-des-enqu%C3%AAtes)) et la liste des modèles de questionnaire
- les modèles de questionnaire ([GET /questionnaire/:id](https://gitlab.insee.fr/sic/collecte-enqueteur/queen-api/-/wikis/Description-de-l'api/Endpoints-de-l'api#questionnaire))
- la liste des resources associées
- les ressources (long ;-)
- la liste des UEs de la campagne
- les UEs de la campagne (y compris state data)

5. **Notifier Pearl du succès / échec**:
Envoi d'un évènement à Pearl à travers le DOM pour notifier de l'échec ou de la réussite de la synchronisation.

**Remarque :** une synchronisation de 25 UE, 2 modèles de questionnaires et 3 nomenclatures prend 1-2 minutes la première fois, puis 20-30 secondes les fois suivantes (sans rechargement des nomenclatures et modèles de questionnaire)