Eventos de Matcher

Matcher emite eventos de dominio como mensajes CloudEvents 1.0 en modo de contenido binario sobre Kafka, publicados vía lib-streaming. Cada evento viaja en el sobre compartido: ce-type nombra el evento como studio.lerian.<resource>.<event>, ce-subject lleva el id del agregado, ce-tenantid el tenant propietario y ce-schemaversion la versión del payload — 1.0.0 para todos los eventos de abajo. El ce-source viene de STREAMING_CLOUDEVENTS_SOURCE y es obligatorio cuando el streaming está habilitado; los despliegues convencionalmente definen matcher, así que los tópicos llegan a matcher.<resource>.<event> (consulta Nombres de tópicos). Los importes de dinero — valores de comisiones, importes de ajuste — viajan por el hilo como cadenas decimales, nunca como floats. Matcher sirve su catálogo completo de eventos en GET /system/matcher/streaming/manifest. Esta página cubre el plano de streaming Kafka. El despacho de webhooks de excepción de Matcher — callbacks HTTP para el enrutamiento de excepciones — es una superficie separada, documentada en Webhooks y callbacks.

Políticas de entrega

El catálogo de Matcher usa dos políticas de entrega:

Los eventos respaldados por outbox se escriben en el outbox dentro de la misma transacción de base de datos que el cambio de estado; un relay publica las filas confirmadas y reintenta durante las caídas del broker. Son los hechos de grado de auditoría (desenlaces de matching, resoluciones de excepción, disputas, gobernanza). Esta política no puede debilitarse por despliegue.
Los eventos directos publican después de que la transacción confirma, con mejor esfuerzo, cayendo al outbox solo cuando el circuito del broker está abierto. Son las señales de configuración y de ciclo de vida operativo.

Cada tabla de abajo indica la política de sus eventos.

Eventos de matching

Respaldados por outbox: transaction.matched, transaction.pending_review. Directos: el resto.

Evento (`ce-type`)	Tópico	Se dispara cuando	Payload principal
`studio.lerian.transaction.matched`	`matcher.transaction.matched`	Una línea de transacción alcanza el estado terminal MATCHED en el commit de una corrida de matching — un evento por línea emparejada.	`transaction_id`, `context_id`, `match_run_id`, `previous_status`, `status`, `match_group_id`?, `candidate_match_group_id`?, `source_id`?, `matched_at`?
`studio.lerian.transaction.pending_review`	`matcher.transaction.pending_review`	Un candidato a match necesita revisión humana (regla no automática).	Mismo esquema, con `pending_review_at`?
`studio.lerian.transaction.ignored`	`matcher.transaction.ignored`	Una transacción se excluye del matching.	`transaction_id`, `ingestion_job_id`, `context_id`, `source_id`, `previous_status`, `status`, `extraction_status`, `updated_at`
`studio.lerian.match_run.completed`	`matcher.match_run.completed`	Una corrida de matching termina. Lender consume este evento para traducir los veredictos de conciliación en acciones de servicing de préstamos.	`match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`?
`studio.lerian.match_run.failed`	`matcher.match_run.failed`	Una corrida de matching falla.	Como `completed`, más `failure_reason`
`studio.lerian.match_group.confirmed`	`matcher.match_group.confirmed`	Un grupo de match se confirma.	`match_group_id`, `match_run_id`, `context_id`, `rule_id`, `transaction_ids`, `confidence`, `status`, `confirmed_at`?
`studio.lerian.match_group.unmatched`	`matcher.match_group.unmatched`	Un grupo de match confirmado se deshace.	Como `confirmed`, más `previous_status`, `reason`, `unmatched_at`
`studio.lerian.fee_variance.created`	`matcher.fee_variance.created`	Una regla fee-aware detecta una variación entre comisiones esperadas y reales.	`fee_variance_id`, `context_id`, `match_run_id`, `match_group_id`, `transaction_id`, `fee_schedule_id`, `fee_schedule_name_snapshot`, `currency`, `expected_fee`, `actual_fee`, `delta`, `variance_type`, `created_at`

Eventos de excepción y disputa

Respaldados por outbox, excepto exception.assigned y los eventos de comentario, que son directos.

Evento (`ce-type`)	Tópico	Se dispara cuando	Payload principal
`studio.lerian.exception.assigned`	`matcher.exception.assigned`	Una excepción se asigna a un operador.	`exception_id`, `status`, `version`, `assigned_at`
`studio.lerian.exception.resolved`	`matcher.exception.resolved`	Una excepción se resuelve.	`exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at`
`studio.lerian.exception.force_match_resolved`	`matcher.exception.force_match_resolved`	Una excepción se resuelve por force-match con un motivo de anulación.	Campos base más `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at`
`studio.lerian.exception.adjust_entry_resolved`	`matcher.exception.adjust_entry_resolved`	Una excepción se resuelve mediante un asiento de ajuste.	Campos base más `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at`
`studio.lerian.exception.dispatched`	`matcher.exception.dispatched`	Una excepción se despacha a un sistema externo.	`exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at`
`studio.lerian.exception.callback_processed`	`matcher.exception.callback_processed`	El callback de un sistema externo se aplica a una excepción.	Campos base más `external_system`, `external_issue_id`, `callback_type`, `processed_at`
`studio.lerian.exception_comment.added`	`matcher.exception_comment.added`	Se añade un comentario a un hilo de excepción.	`comment_id`, `exception_id`, `created_at`
`studio.lerian.exception_comment.deleted`	`matcher.exception_comment.deleted`	Se elimina un comentario.	`comment_id`, `exception_id`, `actor`, `deleted_at`
`studio.lerian.dispute.opened`	`matcher.dispute.opened`	Se abre una disputa sobre una excepción.	`dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at`
`studio.lerian.dispute.won`	`matcher.dispute.won`	Una disputa cierra como ganada.	Como `opened`, más `closed_at`
`studio.lerian.dispute.lost`	`matcher.dispute.lost`	Una disputa cierra como perdida.	Como `opened`, más `closed_at`
`studio.lerian.evidence.submitted`	`matcher.evidence.submitted`	Se adjunta evidencia a una disputa.	`evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at`

Eventos de configuración e ingesta de datos

Todos directos.

Evento (`ce-type`)	Tópico	Se dispara cuando	Payload principal
`studio.lerian.reconciliation_context.created`	`matcher.reconciliation_context.created`	Se crea un contexto de conciliación.	`context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id`
`studio.lerian.reconciliation_context.updated`	`matcher.reconciliation_context.updated`	Los metadatos o el estado de ciclo de vida de un contexto cambian.	Mismo esquema, con `updated_at`
`studio.lerian.reconciliation_source.created`	`matcher.reconciliation_source.created`	Se crea una fuente (lado de entrada) en un contexto.	`context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`
`studio.lerian.match_rule.created`	`matcher.match_rule.created`	Se crea una regla de match.	`context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`
`studio.lerian.match_rule.reordered`	`matcher.match_rule.reordered`	Se reordenan las prioridades de las reglas.	`context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`
`studio.lerian.fetcher_connection.synced`	`matcher.fetcher_connection.synced`	Una conexión de Fetcher y su snapshot de esquema descubierto se sincronizan.	`connection_id`, `fetcher_connection_id`, `config_name`, `database_type`, `status`, `schema_discovered`, `last_seen_at`, `updated_at`
`studio.lerian.fetcher_connection.unreachable`	`matcher.fetcher_connection.unreachable`	Una conexión de Fetcher queda inalcanzable.	Mismo esquema, más `previous_status`
`studio.lerian.extraction_request.created`	`matcher.extraction_request.created`	Se crea una solicitud de extracción contra una conexión.	`extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at`
`studio.lerian.ingestion.completed`	`matcher.ingestion.completed`	Un job de ingesta termina.	`job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `transaction_count`, `date_range_start`, `date_range_end`, `completed_at`
`studio.lerian.ingestion.failed`	`matcher.ingestion.failed`	Un job de ingesta falla.	`job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`, `failed_at`

Eventos de gobernanza y reportes

Respaldados por outbox, excepto la familia de export-job, que es directa.

Evento (`ce-type`)	Tópico	Se dispara cuando	Payload principal
`studio.lerian.audit_log.created`	`matcher.audit_log.created`	Se persiste una entrada de log de auditoría encadenada por hash.	`audit_log_id`, `tenant_id`, `entity_type`, `entity_id`, `action`, `tenant_seq`, `hash_version`, `record_hash`, `created_at`
`studio.lerian.archive_metadata.created`	`matcher.archive_metadata.created`	El worker de archivado registra una partición de archivo.	`archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, más `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`?
`studio.lerian.archive.uploaded`	`matcher.archive.uploaded`	Un archivo se sube al almacenamiento.	Mismo esquema
`studio.lerian.archive.completed`	`matcher.archive.completed`	Un ciclo de archivado termina.	Mismo esquema
`studio.lerian.actor.pseudonymized`	`matcher.actor.pseudonymized`	Los datos personales de un actor se seudonimizan (GDPR/LGPD).	`actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id`
`studio.lerian.export_job.created`	`matcher.export_job.created`	Se crea un job de exportación.	`export_job_id`, `tenant_id`, `context_id`, `report_type`, `format`, `status`, `schema_version`, `created_at`, `expires_at`, `updated_at`
`studio.lerian.export_job.succeeded`	`matcher.export_job.succeeded`	Un job de exportación termina de escribir su artefacto.	Mismo esquema, más `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`?
`studio.lerian.export_job.failed`	`matcher.export_job.failed`	Un job de exportación falla.	Mismo esquema, más `error_code`, `attempts`?, `finished_at`?
`studio.lerian.export_job.expired`	`matcher.export_job.expired`	Un artefacto de exportación expira y se limpia.	Mismo esquema, más `expired_at`?

Declarados pero aún no emitidos

El catálogo y el manifiesto declaran siete eventos adicionales que ningún camino de código emite hoy: reconciliation_context.deleted y la familia de ciclo de vida de extraction_request (submitted, completed, failed, cancelled, bridged, bridge_failed). Son reservas de contrato — no construyas consumidores que dependan de recibirlos.

Eventos consumidos

Matcher no consume eventos de streaming Kafka. Sus insumos de integración llegan por HTTP: subidas de archivos, extracciones de Fetcher y — cuando están habilitadas — entregas de webhook del Streaming Hub en POST /v1/discovery/hub/events (firmadas con HMAC, deduplicadas por id de evento, deshabilitadas por defecto).

Resumen

Midaz

Tracer

Lender

Matcher

Reporter

Fetcher

Consignado

Eventos de Matcher

Políticas de entrega

Eventos de matching

Eventos de excepción y disputa

Eventos de configuración e ingesta de datos

Eventos de gobernanza y reportes

Declarados pero aún no emitidos

Eventos consumidos

​Políticas de entrega

​Eventos de matching

​Eventos de excepción y disputa

​Eventos de configuración e ingesta de datos

​Eventos de gobernanza y reportes

​Declarados pero aún no emitidos

​Eventos consumidos

Políticas de entrega

Eventos de matching

Eventos de excepción y disputa

Eventos de configuración e ingesta de datos

Eventos de gobernanza y reportes

Declarados pero aún no emitidos

Eventos consumidos