> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral do event streaming

> O contrato compartilhado de event streaming dos produtos Lerian: o envelope CloudEvents, as convenções de tópicos e tipos, o isolamento por tenant, o versionamento de esquema e as garantias de entrega.

Os produtos Lerian emitem eventos de domínio — fatos de negócio no passado, como a criação de uma conta ou a emissão de uma credencial — em um backbone de streaming compartilhado. Qualquer serviço ou assinante downstream os consome sem se acoplar às APIs internas do produtor. Esta página descreve o contrato de transporte que todo evento da plataforma segue. As páginas por produto listam os eventos concretos que cada sistema emite e consome.

## 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 prefixo `ce-`, 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çalho `ce-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.<resource>.<event>
```

A criação de uma conta no ledger chega em `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](#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 em `ce-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](/pt/reference/tolerant-reader) — 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 por `ce-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.