Eventos do Matcher

O Matcher emite eventos de domínio como mensagens CloudEvents 1.0 em modo de conteúdo binário sobre Kafka, publicadas via lib-streaming. Todo evento trafega no envelope compartilhado: ce-type nomeia o evento como studio.lerian.<resource>.<event>, ce-subject carrega o id do agregado, ce-tenantid o tenant proprietário e ce-schemaversion a versão do payload — 1.0.0 para todos os eventos abaixo. O ce-source vem de STREAMING_CLOUDEVENTS_SOURCE e é obrigatório quando o streaming está habilitado; os deployments convencionalmente definem matcher, então os tópicos chegam em matcher.<resource>.<event> (consulte Nomes de tópicos). Valores monetários — valores de tarifas, valores de ajuste — trafegam pelo fio como strings decimais, nunca como floats. O Matcher serve seu catálogo completo de eventos em GET /system/matcher/streaming/manifest. Esta página cobre o plano de streaming Kafka. O disparo de webhooks de exceção do Matcher — callbacks HTTP para roteamento de exceções — é uma superfície separada, documentada em Webhooks e callbacks.

Políticas de entrega

O catálogo do Matcher usa duas políticas de entrega:

Eventos respaldados por outbox são gravados no outbox na mesma transação de banco de dados que a mudança de estado; um relay publica as linhas confirmadas e tenta novamente durante quedas do broker. São os fatos de nível de auditoria (desfechos de matching, resoluções de exceção, disputas, governança). Essa política não pode ser enfraquecida por deployment.
Eventos diretos publicam depois que a transação confirma, em melhor esforço, com fallback para o outbox apenas quando o circuito do broker está aberto. São os sinais de configuração e de ciclo de vida operacional.

Cada tabela abaixo indica a política dos seus eventos.

Eventos de matching

Respaldados por outbox: transaction.matched, transaction.pending_review. Diretos: os demais.

Evento (`ce-type`)	Tópico	Dispara quando	Payload principal
`studio.lerian.transaction.matched`	`matcher.transaction.matched`	Uma linha de transação atinge o estado terminal MATCHED no commit de uma rodada de matching — um evento por linha casada.	`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`	Um candidato a match precisa de revisão humana (regra não automática).	Mesmo esquema, com `pending_review_at`?
`studio.lerian.transaction.ignored`	`matcher.transaction.ignored`	Uma transação é excluída do 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`	Uma rodada de matching termina. O Lender consome este evento para traduzir vereditos de conciliação em ações de servicing de empréstimos.	`match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`?
`studio.lerian.match_run.failed`	`matcher.match_run.failed`	Uma rodada de matching falha.	Como `completed`, mais `failure_reason`
`studio.lerian.match_group.confirmed`	`matcher.match_group.confirmed`	Um grupo de match é confirmado.	`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`	Um grupo de match confirmado é desfeito.	Como `confirmed`, mais `previous_status`, `reason`, `unmatched_at`
`studio.lerian.fee_variance.created`	`matcher.fee_variance.created`	Uma regra fee-aware detecta uma variação entre tarifas esperadas e reais.	`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 exceção e disputa

Respaldados por outbox, exceto exception.assigned e os eventos de comentário, que são diretos.

Evento (`ce-type`)	Tópico	Dispara quando	Payload principal
`studio.lerian.exception.assigned`	`matcher.exception.assigned`	Uma exceção é atribuída a um operador.	`exception_id`, `status`, `version`, `assigned_at`
`studio.lerian.exception.resolved`	`matcher.exception.resolved`	Uma exceção é resolvida.	`exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at`
`studio.lerian.exception.force_match_resolved`	`matcher.exception.force_match_resolved`	Uma exceção é resolvida por force-match com um motivo de override.	Campos base mais `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at`
`studio.lerian.exception.adjust_entry_resolved`	`matcher.exception.adjust_entry_resolved`	Uma exceção é resolvida por um lançamento de ajuste.	Campos base mais `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at`
`studio.lerian.exception.dispatched`	`matcher.exception.dispatched`	Uma exceção é despachada para um sistema externo.	`exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at`
`studio.lerian.exception.callback_processed`	`matcher.exception.callback_processed`	O callback de um sistema externo é aplicado a uma exceção.	Campos base mais `external_system`, `external_issue_id`, `callback_type`, `processed_at`
`studio.lerian.exception_comment.added`	`matcher.exception_comment.added`	Um comentário é adicionado a uma thread de exceção.	`comment_id`, `exception_id`, `created_at`
`studio.lerian.exception_comment.deleted`	`matcher.exception_comment.deleted`	Um comentário é excluído.	`comment_id`, `exception_id`, `actor`, `deleted_at`
`studio.lerian.dispute.opened`	`matcher.dispute.opened`	Uma disputa é aberta sobre uma exceção.	`dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at`
`studio.lerian.dispute.won`	`matcher.dispute.won`	Uma disputa fecha como ganha.	Como `opened`, mais `closed_at`
`studio.lerian.dispute.lost`	`matcher.dispute.lost`	Uma disputa fecha como perdida.	Como `opened`, mais `closed_at`
`studio.lerian.evidence.submitted`	`matcher.evidence.submitted`	Uma evidência é anexada a uma disputa.	`evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at`

Eventos de configuração e ingestão de dados

Todos diretos.

Evento (`ce-type`)	Tópico	Dispara quando	Payload principal
`studio.lerian.reconciliation_context.created`	`matcher.reconciliation_context.created`	Um contexto de conciliação é criado.	`context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id`
`studio.lerian.reconciliation_context.updated`	`matcher.reconciliation_context.updated`	Os metadados ou o status de ciclo de vida de um contexto mudam.	Mesmo esquema, com `updated_at`
`studio.lerian.reconciliation_source.created`	`matcher.reconciliation_source.created`	Uma fonte (lado de entrada) é criada em um contexto.	`context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`
`studio.lerian.match_rule.created`	`matcher.match_rule.created`	Uma regra de match é criada.	`context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`
`studio.lerian.match_rule.reordered`	`matcher.match_rule.reordered`	As prioridades das regras são reordenadas.	`context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`
`studio.lerian.fetcher_connection.synced`	`matcher.fetcher_connection.synced`	Uma conexão do Fetcher e seu snapshot de esquema descoberto são sincronizados.	`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`	Uma conexão do Fetcher fica inalcançável.	Mesmo esquema, mais `previous_status`
`studio.lerian.extraction_request.created`	`matcher.extraction_request.created`	Uma requisição de extração é criada contra uma conexão.	`extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at`
`studio.lerian.ingestion.completed`	`matcher.ingestion.completed`	Um job de ingestão 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`	Um job de ingestão falha.	`job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`, `failed_at`

Eventos de governança e relatórios

Respaldados por outbox, exceto a família de export-job, que é direta.

Evento (`ce-type`)	Tópico	Dispara quando	Payload principal
`studio.lerian.audit_log.created`	`matcher.audit_log.created`	Uma entrada de log de auditoria encadeada por hash é persistida.	`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`	O worker de arquivamento registra uma partição de arquivo.	`archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, mais `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`?
`studio.lerian.archive.uploaded`	`matcher.archive.uploaded`	Um arquivo é enviado ao armazenamento.	Mesmo esquema
`studio.lerian.archive.completed`	`matcher.archive.completed`	Um ciclo de arquivamento termina.	Mesmo esquema
`studio.lerian.actor.pseudonymized`	`matcher.actor.pseudonymized`	Os dados pessoais de um ator são pseudonimizados (GDPR/LGPD).	`actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id`
`studio.lerian.export_job.created`	`matcher.export_job.created`	Um job de exportação é criado.	`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`	Um job de exportação termina de gravar seu artefato.	Mesmo esquema, mais `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`?
`studio.lerian.export_job.failed`	`matcher.export_job.failed`	Um job de exportação falha.	Mesmo esquema, mais `error_code`, `attempts`?, `finished_at`?
`studio.lerian.export_job.expired`	`matcher.export_job.expired`	Um artefato de exportação expira e é limpo.	Mesmo esquema, mais `expired_at`?

Declarados mas ainda não emitidos

O catálogo e o manifesto declaram sete eventos adicionais que nenhum caminho de código emite hoje: reconciliation_context.deleted e a família de ciclo de vida de extraction_request (submitted, completed, failed, cancelled, bridged, bridge_failed). Eles são reservas de contrato — não construa consumidores que dependam de recebê-los.

Eventos consumidos

O Matcher não consome eventos de streaming Kafka. Seus insumos de integração chegam por HTTP: uploads de arquivo, extrações do Fetcher e — quando habilitadas — entregas de webhook do Streaming Hub em POST /v1/discovery/hub/events (assinadas com HMAC, deduplicadas por id de evento, desabilitadas por padrão).

Visão geral

Midaz

Tracer

Lender

Matcher

Reporter

Fetcher

Consignado

Eventos do Matcher

Políticas de entrega

Eventos de matching

Eventos de exceção e disputa

Eventos de configuração e ingestão de dados

Eventos de governança e relatórios

Declarados mas ainda não emitidos

Eventos consumidos

​Políticas de entrega

​Eventos de matching

​Eventos de exceção e disputa

​Eventos de configuração e ingestão de dados

​Eventos de governança e relatórios

​Declarados mas ainda não emitidos

​Eventos consumidos

Políticas de entrega

Eventos de matching

Eventos de exceção e disputa

Eventos de configuração e ingestão de dados

Eventos de governança e relatórios

Declarados mas ainda não emitidos

Eventos consumidos