Transporte
Os eventos trafegam como mensagens CloudEvents 1.0 em modo de conteúdo binário sobre Kafka. O modo binário coloca os atributos de contexto do CloudEvents nos cabeçalhos do registro Kafka, cada um com o prefixoce-, e o corpo do evento no valor do registro como JSON. Um consumidor lê o roteamento e a identidade a partir dos cabeçalhos sem desserializar o payload.
O envelope
Todo registro carrega estes cabeçalhos CloudEvents.| Cabeçalho | Presença | Contém |
|---|---|---|
ce-specversion | Sempre | Versão da especificação CloudEvents — 1.0. |
ce-id | Sempre | Id único do evento (UUIDv7). Deduplique por este valor. |
ce-source | Sempre | O serviço produtor. |
ce-type | Sempre | Tipo do evento — studio.lerian.<resource>.<event>. |
ce-time | Sempre | Carimbo de tempo da emissão (RFC 3339). |
ce-resourcetype | Sempre | O recurso — por exemplo account. |
ce-eventtype | Sempre | O evento — por exemplo created. |
ce-schemaversion | Sempre | Versão do esquema do payload. |
ce-subject | Quando aplicável | O id do agregado a que o evento se refere. |
ce-tenantid | Quando aplicável | O tenant proprietário; omitido no escopo single-tenant. |
ce-datacontenttype | Quando aplicável | Tipo de mídia do corpo — application/json. |
Tipo do evento
O cabeçalhoce-type nomeia o evento como studio.lerian.<resource>.<event>. A criação de uma conta no ledger é studio.lerian.account.created. Os dois segmentos também aparecem separadamente em ce-resourcetype e ce-eventtype, de modo que um consumidor filtra pelo tipo completo ou por suas partes.
Nomes de tópicos
Cada evento chega a um tópico do Kafka nomeado pelo recurso e pelo evento que transporta, sob um prefixo de plataforma compartilhado:lerian.streaming.account.created; a criação de um titular no CRM em lerian.streaming.holder.created. O prefixo é idêntico em todos os produtores Lerian, então um consumidor se inscreve por recurso e evento sem precisar saber qual serviço emitiu o registro. O nome do tópico não carrega sufixo de versão — a versão do esquema do payload viaja no cabeçalho ce-schemaversion (consulte Versionamento de esquema), então uma mudança de esquema nunca renomeia um tópico.
Fonte
ce-source identifica o serviço produtor e é configurado no deployment pela variável de ambiente STREAMING_CLOUDEVENTS_SOURCE; não é fixado no produto. Registra onde um registro se originou, para auditoria e roteamento do lado do consumidor. O nome do tópico não deriva dela — os tópicos usam o prefixo compartilhado lerian.streaming. independentemente da fonte — então um deployment pode definir qualquer valor de fonte estável e descritivo.
| Produtor | Fonte padrão |
|---|---|
| Ledger do Midaz | lerian.midaz.ledger |
| CRM do Midaz | lerian.midaz.crm |
Subject e tenant
ce-subject carrega o id do agregado a que o evento se refere — a conta, a transação ou a credencial que o fato descreve. ce-tenantid carrega o tenant proprietário em deployments multi-tenant; é omitido nos eventos de negócio single-tenant, então um consumidor trata a ausência de id de tenant como escopo single-tenant válido, e não como erro.
Versionamento de esquema
Cada evento declara sua própria versão de esquema de payload emce-schemaversion, independente dos demais eventos da mesma fonte. O padrão é 1.0.0. Um incremento menor é aditivo e retrocompatível; um incremento maior é uma mudança incompatível. A versão fica no cabeçalho, nunca no nome do tópico, então um consumidor que lê os payloads como um leitor tolerante — ignorando campos desconhecidos — não é afetado por uma mudança aditiva.
Garantias de entrega
A entrega é at-least-once. Um consumidor confirma sua posição apenas depois de terminar de processar um registro, então uma queda no meio do processamento reprocessa o registro em vez de descartá-lo — o que significa que o mesmo evento pode chegar mais de uma vez. Deduplique porce-id e mantenha os handlers idempotentes.
No lado do produtor, a durabilidade vem de um outbox transacional. Um produto grava o evento em seu outbox na mesma transação de banco de dados que a mudança de estado que o gerou, de modo que o evento e o fato que ele reporta são confirmados ou revertidos juntos. Em seguida, um relay publica no Kafka as linhas confirmadas do outbox e tenta novamente durante as quedas do broker, então nenhum fato de negócio confirmado se perde antes de chegar ao stream.