Travailleur au rapprochement des paiements dans la construction (Travailleur Au Rapprochement Des Paiements Dans La Construction)

Dans la section précédente, nous avons vu comment une entreprise peut être détenue en toute sécurité grâce au mécanisme de location. Mais même le bail le plus robuste ne peut changer un fait : parfois, le travailleur expire avant de recevoir une réponse définitive de la PSP, le processus plante ou le bail expire et la tâche est marquée « expirée » — juste au moment où le paiement du côté du PSP a effectivement été effectué.

C'est la raison d'être du travailleur de réconciliation : un balayeur qui scanne et corrige périodiquement les dérives entre le système local et les propres archives du PSP.```text Local kayıt: Payment #123 → Expired PSP kaydı: Payment #123 → Succeeded │ ▼ Mutabakat worker sürüklenmeyi tespit eder │ ▼ Local kayıt → Captured olarak düzeltilir

## Concepts à la première mention```text
📦 Reconciliation (Mutabakat)
İki bağımsız kaynağın (local sistem ve PSP) kayıtlarını karşılaştırıp farkı düzeltme süreci.

📦 Drift (Sürüklenme)
Local durumun PSP'nin gerçek kaydından farklılaşması; genellikle bir hata veya zaman aşımı sonucu.

📦 Sweeper
Belirli bir kritere uyan (örn. 'aged' veya 'expired') kayıtları periyodik olarak tarayan arka plan işi.

📦 FinalizePending
Ödemenin PSP tarafında sonuçlanmış olabileceği ama local sistemde henüz kesin bir duruma geçmediği ara statü.
```La réconciliation n’est pas une solution en temps réel ; C'est un filet de sécurité. Le flux principal (webhook, réponse synchrone) fonctionne correctement la plupart du temps ; Le consensus élimine la minorité qui en est exclue « la plupart du temps ».

## Les vraies sources de dérive

La dérive est rarement aléatoire ; provient généralement de scénarios spécifiques et répétitifs : le travailleur envoie une demande à PSP, le processus plante avant l'arrivée de la réponse ; La réponse n'arrive jamais en raison d'une erreur réseau, mais la transaction est terminée du côté PSP ; ou la durée du bail est définie plus courte que le temps de réponse de la PSP et la tâche est marquée « expirée » prématurément.```text
Senaryo 1: Worker çöktü
  Request gönderildi → PSP işledi → Worker cevabı hiç okuyamadı

Senaryo 2: Ağ hatası
  Request gönderildi → PSP işledi → yanıt ağda kayboldu

Senaryo 3: Lease erken doldu
  Request gönderildi → PSP yavaş yanıt verdi → lease expired → job stuck watcher tarafından sıfırlandı → ama PSP zaten başarılı olmuştu
```Ce que les trois scénarios ont en commun, c'est que **le registre local** reste dans un statut incertain ou faux, tandis que le **propre registre du PSP** connaît déjà le véritable résultat.

## Requête du Sweeper : quels enregistrements analyser

Le responsable du rapprochement ne compare pas constamment chaque enregistrement au PSP – cela est coûteux et inutile. Il cible uniquement les enregistrements « suspects » : les enregistrements qui ont dépassé un certain âge (vieillis) et restent encore dans un statut intermédiaire (`FinalizePending`, `Expired`, `Processing` pendant une longue période).```sql
SELECT id, provider_ref FROM payments
WHERE status IN ('FinalizePending', 'Expired')
  AND updated_at < now() - interval '10 minutes';
```Le seuil des « 10 minutes » n'est pas arbitraire ; Il s'agit d'un SLA indiquant combien de temps un flux normal devrait prendre pour se produire. Les enregistrements inférieurs à ce seuil ne sont pas encore « suspects », ils peuvent simplement être lents.

## Interroger la PSP et prendre des décisions

Pour chaque enregistrement candidat, le travailleur vérifie l'API de requête d'état de la PSP (si disponible) ou son propre historique de webhook archivé. Trois résultats sont possibles :```text
PSP: Succeeded  → local kaydı Captured'a taşı, semantik event yayınla
PSP: Failed     → local kaydı Failed'a taşı
PSP: Not Found / Unknown → local kaydı gerçekten sonuçsuz say, telafi akışına yönlendir
```Le point critique ici est que cette transition doit également être idempotente : le résultat ne doit pas changer même si le agent de réconciliation traite deux fois le même enregistrement (par exemple, si l'enregistrement est déjà `Captured`, il ne doit pas émettre à nouveau le même événement).

## Alerte : la balayeuse ne doit pas fonctionner en silence

Chaque dérive trouvée par le chercheur de consensus devrait produire un signal d’observabilité. Si le nombre de dérives augmente soudainement, cela indique généralement un problème dans le flux principal (traitement du webhook, durée du bail, réseau) — la réconciliation doit rendre ce problème visible, et non le cacher.

| Métrique | Qu'est-ce que ça dit |
| --- | --- |
| Nombre d'inscriptions de candidats numérisées | Dans quelle mesure le flux principal est-il « propre » |
| Nombre de dérives corrigées | Volume réel des écarts de données |
| Nombre de dossiers toujours non résolus | File d'attente nécessitant une révision manuelle |

## Distinctions souvent confuses```text
❌ Mutabakat gerçek zamanlı bir düzeltmedir
✓ Mutabakat periyodik bir güvenlik ağıdır, ana akışın yerini almaz

❌ Sürüklenme sayısı sıfır olmalı, aksi halde sistem bozuk
✓ Düşük ve stabil bir sürüklenme oranı normaldir; artan oran bir sinyaldir

❌ Her kayıt PSP ile karşılaştırılmalı
✓ Sadece 'aged' ve ara statüdeki kayıtlar hedeflenmeli
```## Rôle du consensus avec le flux principal

| Taille | Flux principal (webhook/synchrone) | Travailleur de réconciliation |
| --- | --- | --- |
| Vitesse | Secondes | Minutes-heures |
| Portée | Chaque paiement | Dossiers suspects/âgés uniquement |
| Objectif | Voie normale | Filet de sécurité |

## Liste de contrôle lors de l'installation de l'agent de réconciliation

1. La requête SLA détermine-t-elle le seuil « âgé » en fonction du SLA de l'entreprise ou s'agit-il d'un nombre aléatoire ?
2. L'interrogation de la PSP est-elle conforme à sa politique de limite de débit et de nouvelle tentative ?
3. La correction de dérive est-elle idempotente ? Le résultat ne change-t-il pas si le même enregistrement est traité deux fois ?
4. Les enregistrements irréparables tombent-ils dans une file d'attente visible (qui est également introuvable sur PSP) ?
5. Le nombre de dérives est-il surveillé comme une mesure et génère-t-il des alarmes en cas d'augmentation soudaine ?

## Ce qu'il faut retenir de cet article

1. Le consensus est un complément au courant principal et non un substitut ; le flux principal fonctionne correctement la plupart du temps, la balayeuse nettoie la minorité restante.
2. Sweeper cible les enregistrements suspects qui répondent aux critères d'âge et de statut, et non tous les enregistrements.
3. La correction post-requête PSP doit être idempotente et respecter sa discipline de nouvelle tentative.
4. Le numéro de dérive est un signal d’observabilité ; Il devrait se rapprocher tranquillement de zéro, la hausse soudaine est un avertissement.

> Un chercheur de consensus montre à quel point le système est honnête et non pas à quel point il est parfait.

Dans la section suivante, nous examinons la forme la plus gênante de cette dérive : le client a été facturé du côté de la PSP mais il n'y a aucun ordre dans le système — et comment pouvons-nous y remédier en toute sécurité ?