Boas Práticas Avançadas — Arquitetura e Governança de Dados

1. Decisões de arquitetura — ADRs

Toda decisão arquitetural relevante deve ser registrada como um ADR (Architecture Decision Record): um documento curto e versionado que preserva o contexto, a decisão e suas consequências. Decisão não registrada é decisão que não se pode auditar, justificar ou reverter com segurança.

• Formato MADR/Nygard: arquivos numerados em docs/adr/0001-titulo.md, com as seções Contexto, Decisão, Status (proposto, aceito ou substituído), Consequências e Alternativas consideradas.
• Exigem ADR: a escolha entre DW relacional e lakehouse, a estratégia de modelagem (dimensional ou Data Vault), a opção por ELT ou ETL, o formato de armazenamento (Parquet, Iceberg, Delta), o esquema de particionamento, a ferramenta de orquestração, as fronteiras entre serviços e a política de versionamento de schema.
• O ADR é imutável: um registro aceito não é editado; cria-se outro que o substitui (superseded by ADR-XXXX). O histórico da decisão é tão relevante quanto a decisão vigente.
• Cada registro deve expor os compromissos reais (trade-offs) que sustentaram a escolha, e não uma racionalização posterior. "Optou-se por X por ser a tecnologia dominada pela equipe" é justificativa legítima e auditável; "X é superior", sem critério, não o é.

2. Princípios de design

• Alta coesão e baixo acoplamento: cada componente — ingestão, armazenamento, transformação e serving — possui responsabilidade delimitada e comunica-se por contratos estáveis, nunca por detalhes internos de implementação.
• Camadas com dependência unidirecional: a arquitetura medalhão (raw → trusted → refined → serving) flui em sentido único. A camada de serving não lê diretamente do raw; as transformações não reescrevem a camada de origem.
• Separação de responsabilidades: a ingestão não aplica regra de negócio; a transformação não autentica usuários; a interface analítica não recalcula métricas já materializadas pelo DW.
• Idempotência e determinismo são propriedades de projeto, e não correções aplicadas a posteriori (ver seção 4).
• Arquitetura evolutiva: privilegiam-se decisões reversíveis, e as invariantes são protegidas por fitness functions — verificações automatizadas que falham quando uma restrição arquitetural é violada (por exemplo, "nenhum job de serving importa do pacote de ingestão").
• Representação no C4 e/ou RM-ODP: o sistema deve ser legível em ao menos dois níveis do modelo C4 (Contexto e Contêiner). Quando pertinente, as decisões devem ser posicionadas nos cinco viewpoints do RM-ODP (Empresa, Informação, Computacional, Engenharia e Tecnologia).

3. Modelagem de Data Warehouse

• Grão explícito e documentado em toda tabela fato. A sentença "uma linha representa ___" deve estar escrita. A ambiguidade do grão é a causa mais frequente de métricas incorretas.
• Modelagem dimensional consciente: distingam-se fatos (medidas, aditivas, semiaditivas ou não aditivas) de dimensões (contexto). A escolha entre star e snowflake deve ser justificada; não se normaliza uma dimensão por automatismo.
• Chaves substitutas (surrogate keys) nas dimensões, com a chave natural preservada como atributo. A chave de negócio não deve atuar como chave primária do DW.
• Slowly Changing Dimensions: o tipo (1, sobrescrita; 2, versionamento; 3, atributo anterior) é escolhido por dimensão e justificado. Quando o negócio exige análise histórica, adota-se o Tipo 2.
• Convenções de nomenclatura consistentes (por exemplo, dim_cliente, fato_venda, prefixos sk_ e nk_). A consistência prevalece sobre a preferência individual.
• A desnormalização é uma decisão, não uma conveniência: toda desnormalização declara o ganho de desempenho ou de usabilidade que a motiva e assume o custo de manutenção correspondente.

4. Pipelines de dados (ETL/ELT)

• Idempotência obrigatória: a execução repetida do mesmo pipeline sobre a mesma entrada produz o mesmo estado final. Empregam-se upsert/merge por chave, escrita por partição (sobrescrita da partição-alvo) ou staging seguido de troca atômica; não se admite append incondicional.
• Reprocessamento seguro: o pipeline deve reprocessar uma janela temporal anterior sem duplicar nem corromper dados já carregados.
• Carga incremental com marca temporal (watermark) ou checkpoint explícito (coluna de atualização, offset ou CDC). A carga integral é admitida apenas mediante justificativa de volume.
• Particionamento alinhado ao padrão de consulta — em geral, por data —, o que reduz o volume de varredura e habilita o reprocessamento por partição.
• Dados de chegada tardia e schema drift devem ser tratados explicitamente, e não ignorados até que provoquem falha.
• Orquestração declarativa (DAG com dependências explícitas), composta por tarefas pequenas e reexecutáveis, sem dependência de ordem implícita ou de estado da máquina.

5. Contratos e qualidade de dados

• Contrato de dados na fronteira de ingestão: schema esperado (nomes, tipos e obrigatoriedade), semântica dos campos, responsável pela fonte e SLA de atualização. O dado que viola o contrato é rejeitado ou colocado em quarentena, jamais propagado de forma silenciosa.
• Validação automatizada das dimensões de qualidade — completude, acurácia, consistência, unicidade, validade e atualidade — implementada como teste do pipeline (à maneira de Great Expectations ou dbt tests), e não como inspeção manual.
• Quarentena e fila de rejeição (dead-letter): registros inválidos são isolados com o respectivo motivo de rejeição, o que viabiliza correção e reprocessamento.
• Toda métrica de qualidade deve ser verificável. Afirmações como "os dados estão adequados" são inaceitáveis; exige-se limiar mensurável (por exemplo, "no mínimo 99% das linhas com cpf válido" ou "freshness inferior a 24 horas").
• Contrato versionado: uma alteração de schema é uma alteração de contrato, sujeita a versionamento e à comunicação aos consumidores (ver seção 9, SemVer).

6. Governança e privacidade

• Catálogo e dicionário de dados: toda tabela e coluna disponibilizada possui descrição, tipo, responsável e classificação. Um dado sem responsável definido encontra-se fora de governança.
• Linhagem (data lineage) rastreável: deve-se conhecer a origem do dado, as transformações pelas quais passou e os pontos em que é consumido. Toda métrica apresentada deve ser rastreável até a fonte.
• Classificação de sensibilidade (público, interno, confidencial, dado pessoal) em cada campo, com a marcação explícita dos dados pessoais.
• Privacidade desde a concepção (LGPD): minimização (coleta restrita ao necessário), finalidade declarada, base legal definida e anonimização ou pseudonimização nos ambientes não produtivos e nas análises.
• Controle de acesso por papel (RBAC) e menor privilégio: cada consumidor acessa apenas o necessário; o acesso a dados pessoais é restrito e auditado.
• Políticas de retenção declaradas, definindo o tempo de vida de cada dado e o momento de seu descarte.

7. Observabilidade e telemetria

• Os três pilares aplicados a pipelines: logs estruturados (em JSON, com run_id, job e partition), métricas (registros lidos, gravados e rejeitados, latência e taxa de erro) e traces que correlacionam as etapas de uma execução.
• SLOs de dados declarados e medidos: freshness (atualidade), volume (quantidade esperada) e distribuição (estabilidade da forma dos dados).
• Telemetria de ETL como requisito de primeira ordem (tema da Aula 15): cada execução emite métricas persistidas e consultáveis, não meras impressões no console.
• Alertas acionáveis: um alerta é disparado apenas quando há ação cabível, e indica qual. Alertas não acionáveis ou recorrentes degradam a confiabilidade do próprio sistema de observabilidade.
• Nenhum detalhe interno deve vazar para a interface analítica: o erro técnico destina-se ao log; ao usuário apresenta-se mensagem tratada.

8. Testes em engenharia de dados

A pirâmide de testes adapta-se ao domínio de dados. Da base ao topo:

• Testes unitários das transformações: a lógica de negócio é verificada com fixtures sintéticas, reduzidas e determinísticas (entrada conhecida, saída esperada).
• Testes de schema e de contrato: o schema de entrada e de saída de cada etapa é validado automaticamente.
• Testes de qualidade de dados: as expectativas definidas na seção 5 são executadas como teste (unicidade de chave, faixas válidas, ausência de nulos onde proibidos).
• Teste fim a fim do pipeline: uma execução completa sobre dados sintéticos produz o estado esperado no destino.
• Determinismo integral: nenhum teste depende de relógio, de ordem de execução, de rede externa ou de dados residuais. Não se utilizam dados de produção em teste.
• Casos negativos: dado fora do contrato, partição vazia, reexecução (idempotência) e chave duplicada na origem.

9. Git, commits e colaboração

Os Conventional Commits constituem o requisito mínimo. No 3º ano, o histórico do repositório é tratado como artefato de arquitetura: deve registrar a evolução das decisões, e não apenas as alterações de arquivos.

• O commit atômico corresponde a uma única mudança lógica que respeita uma fronteira arquitetural. Não se combinam, no mesmo commit, a refatoração de uma modelagem e a correção de um pipeline.
• O corpo do commit expõe a motivação e o impacto. O título declara o que mudou; o corpo, por que mudou e com que efeito. Commits que alteram a arquitetura referenciam o ADR correspondente.
• Rodapés (trailers) padronizados: Refs: #issue, ADR: 0007 e Co-authored-by: quando houver autoria conjunta. Mudanças incompatíveis são sinalizadas com ! e com o rodapé BREAKING CHANGE:.
• Ramos por unidade de trabalho (feat/etl-incremental-vendas) e pull requests reduzidos e revisados. A revisão de código é o espaço de defesa das decisões de arquitetura, não apenas de detecção de defeitos.
• Estratégia de ramificação declarada (trunk-based ou GitFlow), com justificativa, e SemVer para schemas, contratos e versões: MAJOR rompe o contrato, MINOR adiciona de forma compatível, PATCH corrige.
• Nenhum segredo no histórico, em hipótese alguma, ainda que removido posteriormente. O histórico do Git é permanente.

Exemplo de commit no padrão exigido:

10. CI/CD e reprodutibilidade

• Pipeline de integração contínua obrigatório: a cada push, executam-se análise estática, testes (inclusive de qualidade de dados e de schema) e validação das migrations. A integração ocorre somente com a verificação aprovada.
• Ambientes isolados (desenvolvimento, homologação e produção), com dados separados; o ambiente de produção não é utilizado para experimentação.
• Infraestrutura como código (IaC) versionada: os recursos de dados (conjuntos de dados, tabelas, permissões e agendamentos) são descritos em código, e não criados manualmente em console.
• Migrations de schema versionadas e aplicadas em ordem; o estado do banco ou do DW resulta sempre das migrations, nunca de ajuste manual.
• Reprodutibilidade: um terceiro provisiona o ambiente desde a origem, com dados sintéticos, seguindo o README. A impossibilidade de reproduzir o ambiente a partir do repositório invalida a entrega.

11. Segurança e segredos

• Segredos fora do código e do histórico: empregam-se variáveis de ambiente ou cofre de segredos. O arquivo .env permanece no .gitignore; versiona-se apenas o .env.example.
• Menor privilégio nas credenciais de dados: a credencial de um job de leitura não escreve; a de homologação não acessa produção.
• Mascaramento ou pseudonimização de dados pessoais nos ambientes não produtivos e nas análises que dispensam o dado identificável.
• Consultas parametrizadas (prepared statements); jamais se concatena entrada do usuário em SQL.
• Criptografia em repouso e em trânsito para dados sensíveis, com acesso a dados pessoais devidamente auditado.

12. NFRs e os 8 eixos (ISO/IEC 25010)

Os oito eixos de requisitos não funcionais permanecem aplicáveis, agora referidos a uma plataforma de dados e formulados de modo mensurável, e não conceitual.

Cada eixo requer ao menos um requisito não funcional verificável; a ausência em algum eixo deve ser justificada de forma explícita, nunca omitida.

13. FinOps e eficiência

• O custo é requisito de primeira ordem (tema da Aula 19): toda decisão de armazenamento e de processamento pondera o custo, e não apenas o desempenho.
• Redução do volume varrido: o particionamento e o clustering alinhados à consulta evitam a varredura integral; em plataformas cobradas por consumo, a varredura desnecessária representa custo direto.
• Camadas de armazenamento e ciclo de vida: dados quentes e frios em níveis de custo distintos, com políticas de expiração automáticas.
• Atribuição de custo: rótulos por área ou por pipeline, de modo a identificar a origem da despesa.
• Materialização deliberada: a decisão entre recalcular a cada consulta e materializar uma única vez pondera custo e atualidade, e é registrada.

14. Documentação e rastreabilidade

• C4 até o nível de Contêiner (e de Componente nas partes críticas), de modo que o sistema seja compreensível sem a leitura integral do código.
• Dicionário de dados mantido junto ao DW, com tabela, coluna, tipo, responsável e classificação.
• RTM adaptada: Requisito → Decisão/ADR → Pipeline/Tabela → Teste → Evidência. Um elo ausente invalida a rastreabilidade.
• README executável: instala, provisiona o ambiente e executa pipeline e testes sobre dados sintéticos, verificado por terceiros.
• Diagramas com título e legenda. Um diagrama que dependa de explicação textual extensa para ser compreendido é inadequado.

15. Severidade e consequências

A tabela consolida as principais infrações ao baseline avançado e suas consequências. A severidade é cumulativa, e uma infração crítica não é compensada por acertos em outras dimensões: o baseline é limiar de aceitação, não média.

Síntese operacional

Antes de submeter qualquer entrega do Módulo 11, o estudante deve responder afirmativamente a todas as perguntas a seguir: