Estágio 2 — Landing → Bronze

Objetivo da camada

A etapa Landing → Bronze transforma uma entrada temporária em um histórico bruto padronizado, rastreável e reprocessável.

A Bronze não é uma camada de negócio. Ela é a primeira camada persistente da arquitetura.

A função dela é preservar o dado recebido, com o mínimo de alteração possível, mas já com padronização técnica suficiente para permitir leitura, auditoria, reprocessamento e evolução controlada.

Definição do estágio

O que

Persistir dados brutos aprovados da Landing em uma camada histórica padronizada.

Quando

Depois que a ingestão inicial foi concluída e o lote recebeu status:

READY_FOR_BRONZE

Onde

Na camada Bronze / Raw Padronizada / Lakehouse bruto histórico.

Como

Com append-only, metadados técnicos, particionamento, manifesto, validação estrutural e controle de idempotência.

1. Papel da Bronze na arquitetura

A Bronze deve ser a fonte histórica bruta confiável.

Ela responde:

• o que chegou;

• quando chegou;

• de onde veio;

• qual lote trouxe;

• qual arquivo/API/janela originou;

• qual schema foi recebido;

• qual execução processou;

• se o dado foi reprocessado;

• se houve duplicidade técnica;

• se o dado pode ser reconstruído.

A regra principal:

Landing é transitória. Bronze é histórica.

2. O que entra na Bronze

Só deve entrar na Bronze aquilo que passou pela validação inicial da Landing.

Entradas válidas:

• arquivos aprovados;

• payloads de APIs persistidos;

• extrações de banco finalizadas;

• eventos com checkpoint/offset registrado;

• lotes com manifesto válido;

• cargas com status operacional controlado.

Entradas bloqueadas:

• arquivo vazio;

• schema inválido;

• arquivo corrompido;

• lote sem manifesto;

• carga sem batch_id;

• origem desconhecida;

• extração sem controle de janela;

• dados sem rastreabilidade mínima.

3. Característica principal: append-only

A Bronze deve ser preferencialmente append-only.

Isso significa:

não atualizar silenciosamente
não sobrescrever sem controle
não apagar histórico bruto
não corrigir dado original sem rastrear

Mesmo quando houver reprocessamento, o ideal é manter rastreabilidade entre lote original e lote reprocessado.

Exemplo de controle:

batch_id_original
batch_id_reprocessado
parent_batch_id
reprocess_reason
is_reprocessed

4. Estrutura recomendada da Bronze

Modelo genérico:

bronze/
  domain=<dominio>/
    entity=<entidade>/
      ingestion_date=YYYY-MM-DD/
        source_system=<sistema_origem>/
          batch_id=<id_lote>/
            data.parquet
            metadata.json

Ou, em formato de tabela:

bronze.<dominio>.<entidade>

Exemplo:

bronze.financeiro.clientes
bronze.comercial.vendas
bronze.operacional.contratos

5. Formato dos dados

Sempre que possível, a Bronze deve converter os dados recebidos para formato colunar.

Preferência:

Parquet
Delta
Iceberg
Hudi

Depende da plataforma, mas o princípio é o mesmo:

evitar manter CSV, Excel ou JSON como formato principal de consulta histórica.

O arquivo original pode ser mantido temporariamente na Landing ou armazenado em área de auditoria, mas a Bronze deve priorizar formato eficiente para leitura e reprocessamento.

6. Metadados obrigatórios na Bronze

Toda tabela Bronze deveria ter colunas técnicas padronizadas.

Exemplo:

_metadata_batch_id
_metadata_execution_id
_metadata_source_system
_metadata_source_type
_metadata_source_entity
_metadata_source_file
_metadata_source_path
_metadata_ingestion_at
_metadata_landing_path
_metadata_file_hash
_metadata_schema_hash
_metadata_record_hash
_metadata_watermark_start
_metadata_watermark_end
_metadata_load_type
_metadata_is_reprocess
_metadata_parent_batch_id
_metadata_created_at

Esses campos garantem:

• auditoria;

• rastreabilidade;

• idempotência;

• reprocessamento;

• troubleshooting;

• lineage operacional.

7. Validações antes de gravar na Bronze

Antes de persistir na Bronze, o pipeline deve validar:

batch_id existe
manifesto existe
status = READY_FOR_BRONZE
arquivo/payload existe na Landing
schema mínimo foi validado
hash do arquivo confere
quantidade de registros confere
lote ainda não foi processado
origem está cadastrada
destino bronze está configurado

Se falhar, o lote não deve avançar.

Destino:

QUARENTENA_TÉCNICA
ou
FAILED_BRONZE_LOAD

8. Esteira de execução Landing → Bronze

Fluxo ideal:

1. Ler tabela de controle da ingestão
2. Identificar lotes READY_FOR_BRONZE
3. Ler contrato da entidade
4. Ler dados da Landing
5. Validar manifesto e metadados
6. Aplicar padronização técnica mínima
7. Adicionar colunas de metadados
8. Converter para formato colunar
9. Gravar na Bronze em append-only
10. Atualizar controle operacional
11. Marcar lote como BRONZE_PROCESSED
12. Acionar próximo estágio: Bronze → Silver Técnica

Visualmente:

Landing
  ↓
Manifesto + contrato
  ↓
Validação estrutural
  ↓
Padronização técnica mínima
  ↓
Metadados técnicos
  ↓
Bronze append-only
  ↓
BRONZE_PROCESSED

9. Padronização permitida na Bronze

A Bronze pode padronizar tecnicamente, mas não deve aplicar regra de negócio pesada.

Pode fazer:

• normalizar nomes técnicos de colunas;

• remover caracteres problemáticos dos nomes;

• converter formato físico;

• adicionar metadados;

• registrar schema recebido;

• particionar dados;

• preservar payload bruto;

• controlar duplicidade de lote;

• padronizar encoding;

• persistir JSON como struct ou string, conforme contrato.

Não deve fazer:

• criar KPIs;

• aplicar regra complexa de negócio;

• deduplicar entidade final;

• corrigir valores de domínio;

• fazer joins analíticos;

• aplicar SCD;

• criar dimensões ou fatos.

10. Controle de schema

A Bronze precisa registrar o schema recebido.

Possibilidades:

schema_hash
schema_snapshot
schema_version
schema_drift_status

Regras recomendadas:

Situação	Ação
Schema igual ao esperado	Processa normalmente
Coluna nova permitida	Processa com evolução controlada
Coluna obrigatória ausente	Quarentena técnica
Tipo incompatível	Quarentena técnica
Ordem de colunas diferente	Corrige se contrato permitir
Arquivo sem header esperado	Quarentena técnica
Schema totalmente divergente	Bloqueia carga

11. Idempotência na Bronze

A Bronze precisa evitar duplicidade técnica.

Chaves de controle:

source_system
entity
source_file
file_hash
batch_id
watermark_start
watermark_end

Regra prática:

Mesmo batch_id já processado = não processar novamente
Mesmo arquivo + mesmo hash = não duplicar
Mesmo intervalo incremental = exigir reprocessamento controlado

Se for reprocessamento autorizado:

_metadata_is_reprocess = true
_metadata_parent_batch_id = batch original

12. Reprocessamento Landing → Bronze

O reprocessamento pode acontecer por:

• batch_id;

• arquivo;

• entidade;

• domínio;

• data de ingestão;

• janela incremental;

• falha técnica;

• correção de schema;

• solicitação de negócio;

• reprocessamento de quarentena.

Tipos principais:

Reprocessamento por lote

Reprocessar batch_id específico da Landing para Bronze

Reprocessamento por arquivo

Reprocessar arquivo corrigido ou reenviado

Reprocessamento por janela

Reprocessar período incremental

Reprocessamento de quarentena

Reprocessar lote corrigido após falha técnica

Replay controlado

Reexecutar uma carga preservando vínculo com o lote original

13. Tabela de controle Bronze

Além da tabela de ingestão, pode existir uma tabela operacional específica da Bronze.

Exemplo:

control_bronze_loads

Campos recomendados:

bronze_load_id
batch_id
parent_batch_id
source_system
domain
entity
landing_path
bronze_table
load_type
status
record_count_landing
record_count_bronze
schema_hash
file_hash
started_at
finished_at
duration_seconds
is_reprocess
reprocess_reason
error_message
created_at

Status possíveis:

PENDING_BRONZE
BRONZE_RUNNING
BRONZE_PROCESSED
BRONZE_FAILED
BRONZE_QUARANTINED
BRONZE_REPROCESS_REQUESTED
BRONZE_REPROCESSED

14. Quarentena técnica da Bronze

A quarentena técnica também atua nesse estágio.

Motivos comuns:

manifesto ausente
batch_id inválido
arquivo não localizado
schema divergente
falha na conversão para formato colunar
registro corrompido
erro de leitura
lote duplicado não autorizado
record_count divergente

A quarentena precisa guardar:

• lote;

• origem;

• erro;

• dados afetados;

• schema recebido;

• schema esperado;

• data da falha;

• possibilidade de reprocessamento;

• motivo técnico;

• responsável/domínio.

15. Particionamento recomendado

Particionamento depende do volume, mas padrões úteis são:

ingestion_date
source_system
domain
entity

Evitar particionar por campos de alta cardinalidade.

Boas opções:

ano_mes
data_ingestao
dominio
origem

Más opções:

cpf
id_cliente
numero_contrato
timestamp exato

Regra prática:

Particione para reduzir custo de leitura, não para reproduzir cada coluna de filtro possível.

16. Qualidade na Bronze

A qualidade na Bronze é técnica, não analítica.

Validar:

• leitura do arquivo;

• formato;

• schema mínimo;

• colunas obrigatórias técnicas;

• quantidade de registros;

• duplicidade de lote;

• hash;

• metadados;

• integridade do manifesto;

• sucesso da escrita.

Não validar ainda:

• regra de negócio complexa;

• domínio comercial;

• relacionamento entre entidades;

• KPIs;

• granularidade analítica.

Essas validações entram principalmente na Silver Técnica e Silver Analítica.

17. Saída esperada da Bronze

Ao final do estágio, devemos ter:

dados persistidos em camada histórica
formato físico otimizado
metadados técnicos adicionados
append-only garantido
manifesto vinculado
controle operacional atualizado
status BRONZE_PROCESSED
base pronta para Silver Técnica

A entrega da Bronze é:

histórico bruto padronizado, auditável, reprocessável e tecnicamente confiável.

18. Resumo visual do estágio

LANDING
  ↓
MANIFESTO + CONTRATO
  ↓
VALIDAÇÃO ESTRUTURAL
  ↓
PADRONIZAÇÃO TÉCNICA MÍNIMA
  ↓
METADADOS TÉCNICOS
  ↓
BRONZE APPEND-ONLY
  ↓
BRONZE_PROCESSED
  ↓
SILVER TÉCNICA

Em caso de falha:

VALIDAÇÃO / ESCRITA BRONZE
  ↓
QUARENTENA TÉCNICA
  ↓
CORREÇÃO
  ↓
REPROCESSAMENTO CONTROLADO
  ↓
BRONZE

Definição final do estágio

A camada Landing → Bronze é responsável por transformar uma recepção temporária em um histórico bruto persistente, padronizado e rastreável.

Ela deve garantir que todo dado aprovado da Landing seja gravado de forma append-only, com metadados técnicos, controle de schema, manifesto, idempotência e possibilidade real de replay/reprocessamento.

A Bronze não é onde o dado vira confiável para negócio.A Bronze é onde o dado vira confiável para processamento técnico e histórico auditável.