Contrats API et événements
En bref : Annexe de référence pour la DSI : comment les composants de CRISalid se parlent, et ce que ces échanges garantissent ou non. Le point à retenir pour la décision : les suppressions ne sont pas propagées. Une personne retirée de l'annuaire reste dans le graphe ; 3 353 documents marqués à supprimer attendent sur l'instance. Il n'existe aucun contrat d'échange unique et versionné jusqu'à une vitrine : il faudra l'écrire avec le service d'export.
Le circuit des données est expliqué dans Comprendre CRISalid ; cette page n'en reprend pas le schéma. Le sens des champs est dans le dictionnaire, les règles de fusion dans Provenance, qualité et fusion.
Suppressions non propagées
Cette section fait foi. Statut : Confirmé dans le code ; Observé sur instance (dev) pour les documents en attente.
| Cas | Ce qui se passe | Conséquence |
|---|---|---|
| Personne ou structure retirée de l'annuaire | La passerelle d'annuaire la marque « supprimée » ; le graphe (IKG) ignore ce statut et ne traite que créations, modifications et inchangés | La personne reste dans le graphe |
| Notice retirée par une source | Le graphe reçoit l'événement mais n'a aucun traitement de suppression | La notice reste |
| Document supprimé dans le graphe | SoVisu+ le retire de sa base, si le message porte encore son identifiant | Fonctionne dans le cas nominal |
| Structure supprimée | SoVisu+ ignore explicitement l'événement | La structure reste dans SoVisu+ |
| Personne supprimée | SoVisu+ n'a pas de traitement de suppression | La personne reste dans SoVisu+ |
| Fusion de documents | Pas d'alias « ancien identifiant → document conservé » dans les messages | Un lien externe vers l'ancien document se perd |
Sur l'instance, 3 353 documents marqués à supprimer ne sont pas purgés (données observées). Le retrait d'un identifiant de personne a son propre chemin de nettoyage, qui ne comble pas ces manques.
Pour la vitrine : l'export doit être régénéré en entier à chaque cycle et filtré sur une liste de personnes et de structures actives fournie par l'établissement. Sinon, les départs restent affichés. Le droit à l'effacement n'est pas outillé de bout en bout (sécurité et données personnelles).
API observées
Statut : Confirmé dans les révisions lues. Les chemins et préfixes par défaut du code ne sont pas reproduits ici ; ils diffèrent d'ailleurs dans l'exemple de déploiement.
| Composant | Ce que l'interface fait | Limite |
|---|---|---|
| API Apollo (GraphQL) | Lecture du graphe par SoVisu+ ; écritures également générées | Une seule clé, qui ouvre aussi les écritures (voir ci-dessous) |
| Graphe (IKG), interface HTTP | Création ou mise à jour de personnes, structures et notices | Pas de clé d'idempotence ; à garder sur le réseau interne (page sécurité) |
| Moissonneur, interface HTTP | Lancer une collecte pour une personne et en lire le résultat | Une lecture apparente lance une collecte : ne pas l'utiliser comme simple contrôle |
| Sondes de santé (graphe, Apollo) | Réponse « OK » | Réponse constante : ne vérifie ni Neo4j ni le bus |
Le numéro de version des chemins HTTP ne versionne ni le schéma GraphQL ni les messages. Aucun quota, plafond de coût ni pagination stable n'est configuré dans Apollo.
Apollo : schéma généré et clé d'API
Statut : Confirmé par génération et tests locaux le 22 octobre 2026 (procédure). Le schéma expose 60 requêtes et 60 mutations (création, modification, suppression de personnes, de documents…). La clé d'API est vérifiée, mais une clé valide accepte les mutations comme les requêtes : il n'existe pas de clé en lecture seule. Aucun serveur n'a été lancé : rien ne prouve qu'une écriture réussirait avec le compte Neo4j déployé. Conséquences et décision : sécurité, droits et données personnelles.
Familles de messages
Le bus RabbitMQ porte trois familles d'échanges : annuaire, publications et graphe, chacune avec ses files d'erreur.
| De → vers | Contenu |
|---|---|
| Passerelle d'annuaire → graphe | Personnes et structures, avec leur statut : créée, modifiée, inchangée, supprimée |
| Graphe → moissonneur | Commande de collecte pour une personne, avec ses identifiants et les sources à interroger |
| Moissonneur → graphe | Notices collectées, avec l'identifiant utilisé |
| Graphe → SoVisu+ | Avis de changement (personne, structure, document, suivi de collecte) ; SoVisu+ relit l'état courant dans Apollo |
| SoVisu+ → graphe | Actions des utilisateurs : corrections, fusions, demandes de moissonnage |
| Graphe → SoVisu+ | Résultat de chaque correction : appliquée ou en échec |
Deux modes coexistent, par lots et interactif, sans ordre global garanti entre eux. Aucun numéro de version de schéma ni identifiant d'événement universel n'accompagne les messages. Aucun message n'a été envoyé à une instance.
Livraison, rejeu et idempotence
| Étape | Ce qui est confirmé | Limite |
|---|---|---|
| Publication par la passerelle d'annuaire | Échange durable | Ni message persistant ni accusé de réception de l'éditeur configurés |
| Fin d'import par la passerelle | La diffusion est lancée sans attendre sa fin | Le succès du chargement ne prouve pas l'application dans le graphe, ni « structures avant personnes » |
| Publication par le graphe | Messages persistants, accusés de réception | Une erreur de publication est journalisée sans être remontée ; pas de transaction graphe → bus |
| File d'attente des actions de SoVisu+ | Action enregistrée, relevée toutes les 3 secondes, publiée puis marquée « envoyée » | Marquée envoyée sans accusé de réception ; pendant une coupure du bus, au-delà de 100 messages en attente, l'action est abandonnée avec un simple avertissement |
| Consommation par le graphe | Accusé après traitement ; erreur de base → remise en file ; erreur de valeur → rejet | Pas de nombre maximal de tentatives |
| Consommation par le moissonneur | Erreurs de connexion remises en file | Rejouer une commande peut créer une nouvelle collecte |
| Consommation par SoVisu+ | Accusé après traitement ; exception → rejet | Un événement ignoré n'est pas signalé |
| Corrections | Identifiant application:id, une action déjà appliquée est ignorée | Certaines actions ne sont pas enregistrées comme corrections |
Statut : Confirmé dans le code. Écart de files d'erreur : le graphe relie ses files d'erreur à toutes les clés, alors que l'exemple de déploiement utilise la clé de la file d'origine ; un rejet peut être recopié dans plusieurs files. La supervision et le rejeu des files d'erreur sont À confirmer.
Exigences contractuelles restant à obtenir
Statut : À confirmer, auprès de l'équipe CRISalid ou dans le service d'export :
- Versionnement : schémas d'API et de messages figés, versionnés, avec délai de dépréciation ;
- Identité et retrait : identifiant stable, numéro de révision, marque de suppression portant l'identifiant, alias après fusion ;
- Rejeu : clé d'idempotence, ordre, accusés de bout en bout, tentatives bornées ;
- Accès : périmètres, champs publiables, quotas, pagination stable ;
- Fraîcheur : délais mesurés de la source au graphe, comportement en panne ;
- Export : complet, filtré, versionné, avec manifeste, compteurs et dernière version saine.
Preuves principales
- Graphe (crisalid-ikg)
ebdaae75: consommateurs et producteurs, rejeu des corrections. - Apollo
d377579a: schéma déclaré. - Moissonneur
6898db85: messages. - Passerelle d'annuaire
95be05d7: calcul des statuts, publication des événements. - SoVisu+
8e571657: traitements des événements. - Déploiement
10e0e710: exemple d'échanges, de files et de liaisons.
Les tests de publication et de consommation ont été lus, sans exécution. Les révisions sont centralisées dans Sources et preuves.