Trabajador de conciliación de pagos de construcción (Trabajador DE Conciliacion DE Pagos DE Construccion)

En la sección anterior vimos cómo se puede poseer una empresa de forma segura con el mecanismo de arrendamiento. Pero ni siquiera el contrato de arrendamiento más sólido puede cambiar un hecho: a veces el trabajador se agota antes de recibir una respuesta definitiva del PSP, el proceso falla o el contrato de arrendamiento vence y el trabajo se marca como "vencido", justo cuando el pago por parte del PSP realmente ha sido exitoso.

Ésta es la razón de ser del trabajador de reconciliación: un barrendero que escanea y corrige periódicamente la deriva entre el sistema local y los propios registros del 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

## Conceptos en la primera mención```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 reconciliación no es una solución en tiempo real; Es una red de seguridad. El flujo principal (webhook, respuesta sincrónica) funciona correctamente la mayor parte del tiempo; El consenso elimina a la minoría que queda fuera de eso "la mayor parte del tiempo".

## Las verdaderas fuentes de deriva

La deriva rara vez es aleatoria; generalmente proviene de escenarios específicos y repetitivos: el trabajador envía una solicitud al PSP, el proceso falla antes de que llegue la respuesta; La respuesta nunca llega debido a un error de red, pero la transacción se completa en el lado del PSP; o la duración del arrendamiento se establece más corta que el tiempo de respuesta de la PSP y el trabajo se marca como "vencido" prematuramente.```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
```Lo que los tres escenarios tienen en común es que **el registro local** permanece en un estado incierto o falso, mientras que el **registro propio del PSP** ya conoce el resultado verdadero.

## Consulta del barrendero: qué registros escanear

El trabajador de conciliación no compara constantemente cada registro con el PSP; esto es costoso e innecesario. Se dirige únicamente a registros "sospechosos": registros que han superado una determinada antigüedad (envejecido) y aún permanecen en un estado intermedio (`FinalizePending`, `Expired`, `Processing` durante mucho tiempo).```sql
SELECT id, provider_ref FROM payments
WHERE status IN ('FinalizePending', 'Expired')
  AND updated_at < now() - interval '10 minutes';
```El umbral de "diez minutos" no es arbitrario; Proviene de un SLA sobre cuánto tiempo debe tardar en producirse un flujo normal. Los registros por debajo de este umbral todavía no son "sospechosos", simplemente pueden ser lentos.

## Consultar PSP y tomar decisiones

Para cada registro de candidato, el trabajador verifica la API de consulta de estado del PSP (si está disponible) o su propio historial de webhook archivado. Son posibles tres resultados:```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
```El punto crítico aquí es que esta transición también debe ser idempotente: el resultado no debe cambiar incluso si el trabajador de conciliación procesa el mismo registro dos veces (por ejemplo, si el registro ya es `Captured`, no debería emitir el mismo evento nuevamente).

## Alerta: la barredora no debe funcionar silenciosamente

Each drift the consensus worker finds should produce an observability signal. Si el número de desviaciones aumenta repentinamente, esto generalmente indica un problema en el flujo principal (procesamiento de webhook, plazo de arrendamiento, red); la conciliación debe hacer visible este problema, no ocultarlo.

| Métrica | ¿Qué dice?
| --- | --- |
| Número de inscripciones de candidatos escaneadas | Qué tan "limpia" es la corriente principal |
| Número de desviaciones corregidas | Volumen real de discrepancia de datos |
| Número de expedientes aún sin resolver | Cola que requiere revisión manual |

## Distinciones frecuentemente confusas```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
```## Papel del consenso con el flujo principal.

| Tamaño | Transmisión principal (webhook/síncrono) | Trabajador de reconciliación |
| --- | --- | --- |
| Velocidad | Segundos | Minutos-horas |
| Alcance | Cada pago | Sólo registros sospechosos/antiguos |
| Propósito | Modo normal | Red de seguridad |

## Lista de verificación al instalar el trabajador de reconciliación

1. ¿La consulta de barrido determina el umbral de "antigüedad" según el SLA empresarial o es un número aleatorio?
2. ¿La consulta al PSP cumple con su límite de velocidad y política de reintentos?
3. ¿Es la corrección de deriva idempotente? ¿El resultado no cambia si el mismo registro se procesa dos veces?
4. ¿Los registros que no se pueden reparar caen en una cola visible (que tampoco se puede encontrar en PSP)?
5. ¿Se monitorea el número de desviaciones como métrica y genera alarmas ante aumentos repentinos?

## Lo que debes recordar de este artículo

1. El consenso es un complemento de la corriente principal, no un sustituto; la corriente principal funciona correctamente la mayor parte del tiempo, el barrendero limpia la minoría restante.
2. Sweeper apunta a registros sospechosos que cumplen con los criterios de edad y estado, no a todos los registros.
3. La corrección posterior a la consulta de PSP debe ser idempotente y cumplir con su disciplina de reintento.
4. El número de deriva es una señal de observabilidad; Se espera que se acerque silenciosamente a cero; el aumento repentino es una advertencia.

> Un trabajador de consenso muestra cuán honesto es el sistema, no cuán perfecto es.

En la siguiente sección consideraremos la forma más molesta de esta deriva: al cliente se le ha cobrado en el lado de PSP pero no hay orden en el sistema, y ​​¿cómo solucionamos esto de manera segura?