A Quem Este Livro se Destina

Este livro foi escrito para quem constrói software de verdade e quer construí-lo bem. Não pressupõe um título nem um cargo — pressupõe curiosidade e a disposição de entender o porquê por trás de cada decisão, não apenas o como.

Ele serve a três tipos de leitor, em três momentos diferentes da jornada. Ao desenvolvedor que já programa mas sente que falta uma estrutura maior — que escreve código que funciona, mas não sabe ainda por que alguns sistemas envelhecem bem e outros viram um pântano. Ao arquiteto ou tech lead que precisa tomar decisões que outras pessoas vão herdar, e quer um repertório de padrões testados e um jeito de registrar o raciocínio. E ao fundador técnico que constrói uma plataforma sozinho ou em equipe pequena, e não tem o luxo de errar nas fundações.

O que une esses leitores é uma ambição: não se contentar em fazer o software funcionar hoje, mas torná-lo sustentável — capaz de crescer, de ser entendido por quem chega depois, de sobreviver a mudanças de requisito, de parceiro, de escala. Essa é a diferença entre escrever um programa e construir uma plataforma.

O Que Você Será Capaz de Construir

Os softwares que admiramos por sua robustez — os sistemas operacionais que rodam por décadas, as plataformas corporativas que sustentam empresas inteiras, os ERPs que orquestram operações globais — não são feitos de truques secretos. São feitos de princípios disciplinados, aplicados com consistência: separação clara de responsabilidades, fronteiras que se respeitam, dados modelados com rigor, operação observável, segurança construída desde o início.

Este livro destila esses princípios e os torna concretos. Você não vai sair daqui sabendo recriar um sistema operacional inteiro — mas vai sair com o modo de pensar que os torna possíveis, e com padrões aplicáveis imediatamente ao seu próprio software. A meta é elevar o teto do que você considera construível.

Como Esta Obra Funciona

A obra é organizada em capítulos, e cada capítulo em tópicos. Mas a verdadeira estrutura está dentro de cada tópico: uma anatomia fixa de sete seções que se repete do início ao fim. Essa repetição não é monotonia — é um contrato com o leitor. Você sempre sabe onde está e o que vem a seguir.

Além dessas sete seções, cada tópico traz elementos que tornam o aprendizado concreto e confortável: estudos de caso baseados em situações reais de operação, incidentes reais apresentados como linhas do tempo — porque se aprende muito com o que quebrou —, decisões arquiteturais (ADRs) completas que preservam o raciocínio, e exercícios que levam o conceito ao seu contexto.

As Técnicas e a Stack

Este livro usa duas linguagens, deliberadamente, porque cada uma brilha em um papel — e porque saber quando usar qual é parte da maturidade de engenharia.

PHP sustenta o núcleo da plataforma: as engines, o domínio, os casos de uso. Não o PHP de scripts soltos, mas o PHP moderno, tipado, organizado segundo a Arquitetura Limpa — provando que a disciplina arquitetural independe da reputação de uma linguagem. Python assume os pipelines de dados, a automação e os coletores: o ETL que move milhões de registros, os scripts que sustentam a operação, a manipulação de dados em escala. Juntas, elas cobrem o espectro de uma plataforma real.

Os bancos de dados são tratados com a seriedade que merecem, cada um por sua força: PostgreSQL como o cavalo de batalha transacional (OLTP); ClickHouse e DuckDB para análise em escala (OLAP); e MySQL, Firebird e Oracle como realidades de sistemas legados com os quais toda plataforma madura precisa conviver. Você aprenderá não só a usá-los, mas a decidir qual usar e por quê.

Como Ler

Há dois caminhos legítimos por esta obra, e ambos funcionam.

O caminho linear, do Capítulo I ao XV, constrói a competência camada por camada — é o ideal para quem quer a formação completa, do fundamento à maestria. O caminho por necessidade, saltando direto ao volume que resolve um problema atual, funciona porque cada volume é razoavelmente autossuficiente e aponta explicitamente para os conceitos de que depende. Você verá, ao longo do texto, referências cruzadas como "(Cap II)" — elas são pontes, não pré-requisitos rígidos.

O Problema

A maioria dos sistemas corporativos nasce rígida. A regra de negócio é cravada no código, e qualquer mudança — um novo tipo de cliente, uma alíquota diferente, um fluxo de aprovação — exige um desenvolvedor, um deploy, um ciclo. O negócio espera dias pelo que deveria levar minutos.

Esse engessamento não é falha de execução; é falha de arquitetura. Quando não se distingue o que varia do que é estável, tudo vira código — e código só muda com programador. A pergunta fundadora desta obra é: o que precisa ser código, e o que pode ser dado?

A Decisão

O que varia entre clientes, entre contextos, ao longo do tempo — campos de um formulário, regras de aprovação, fluxos, telas — é descrito como dado (metadado), editável sem deploy. O que é invariante — como persistir com segurança, como isolar tenants, como cifrar — é código, testado e estável. A plataforma é o mecanismo que lê o metadado e o executa sobre o código.

Um segundo princípio acompanha o primeiro: operação antes de automação opaca. Automatizar algo que não se consegue observar é construir uma caixa-preta que ninguém saberá consertar. Toda automação nasce acompanhada da evidência que a torna operável — o quarto plano da figura.

Estudo de Caso

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Decisões de engenharia tomadas longe do trabalho real são chutes bem-vestidos. "Acho que o gargalo é o banco", "deve ser a rede", "provavelmente é o cache" — suposições que enviam a equipe a caçar o problema errado enquanto o real persiste.

A complexidade acidental agrava tudo: camadas que ninguém pediu, abstrações que não pagam seu custo, configuração que ninguém entende. Cada peça desnecessária é um lugar a mais onde o problema pode se esconder e onde a próxima pessoa vai tropeçar.

A Decisão

Genba — "o local real" — é a recusa de decidir por suposição: vá aos logs, às métricas, ao comportamento observado. Kanso é a recusa da complexidade que não paga seu custo. Hansei é a reflexão honesta sobre o que falhou, focada na causa sistêmica e não em culpados. Kaizen é a melhoria contínua: cada lição vira uma mudança concreta no sistema.

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Sistemas organizados por funcionalidade — "a tela de cadastro", "o botão de exportar", "o relatório X" — herdam a volatilidade da interface. Cada redesenho de tela ameaça a arquitetura, porque a arquitetura foi amarrada ao que mais muda: a aparência.

Capacidades de negócio, ao contrário, são notavelmente estáveis. "Emitir um documento fiscal", "aprovar uma operação", "cobrar um cliente" são coisas que o negócio faz há décadas e fará por décadas. A interface por onde se faz muda toda semana; a capacidade em si, quase nunca.

A Decisão

A plataforma se organiza em quatro camadas. O negócio expressa capacidades. A aplicação as realiza em casos de uso. O núcleo fornece engines genéricas (permissão, metadado, auditoria) que servem a qualquer capacidade. A infraestrutura — banco, rede, provedores — é detalhe que se troca sem abalar o resto. Cada camada depende apenas da camada interna, nunca o contrário.

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Uma decisão arquitetural sem registro é conhecimento condenado a evaporar. Seis meses depois, ninguém lembra por que se escolheu PostgreSQL em vez de outro banco, por que a auditoria é imutável, por que aquele serviço não foi quebrado em microserviços. A discussão se repete — ou pior, a decisão é revertida por quem não conhecia suas razões.

O custo não é só o tempo da rediscussão. É o risco de desfazer aprendizado: alguém, com boa intenção, remove uma trava que parecia desnecessária — e que existia justamente para evitar um problema já vivido. Sem o registro do porquê, cada decisão é uma armadilha esperando a próxima pessoa.

A Decisão

Um ADR é deliberadamente curto — cabe em uma página. Registra o contexto (que forças levaram à decisão), a decisão em si, as alternativas consideradas (e por que foram preteridas) e as consequências (positivas, negativas e riscos). Quando uma decisão é superada, não se apaga o ADR: cria-se um novo que o substitui, preservando a trilha de raciocínio.

Estudo de Caso

Decisão Arquitetural

Antipadrões

Exercício

O Problema

A plataforma cresce em produtos e módulos. Sem disciplina de fronteira, eles se entrelaçam: o faturamento lê direto a tabela do cadastro, o rastreamento chama um método interno das rotas. Quando tudo conhece tudo, nada pode mudar sem quebrar outra coisa — o monólito modular degenera na "grande bola de lama".

Do outro extremo está a moda dos microserviços adotada cedo demais: quebrar um sistema jovem em vinte serviços distribuídos antes de entender seus limites reais. O resultado é complexidade operacional brutal — rede, latência, consistência distribuída — para resolver um problema de escala que ainda não existe. Ambos os erros nascem da mesma falta: ausência de disciplina sobre quando e como separar.

A Decisão

A plataforma começa como um monólito modular: um único processo, mas com módulos de fronteiras nítidas. Cada módulo expõe um contrato e esconde sua implementação; ninguém lê a tabela do vizinho. Quando — e só quando — surge uma razão concreta (um módulo precisa escalar sozinho, tem um time dedicado, ou um ritmo de release próprio), ele é extraído para um serviço independente, conversando com o resto pelo mesmo contrato que já existia.

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Construir a coisa certa é mais difícil que construir certo a coisa. Times caem na armadilha de transformar pedidos diretamente em features, sem validar se resolvem o problema real — e descobrem tarde, com o código já escrito, que ninguém precisava daquilo. Em uma operação enxuta, esse desperdício é especialmente caro.

O pedido do usuário é uma pista, não uma especificação. Quando alguém pede "um botão de exportar", o problema real pode ser "preciso levar estes dados para o meu contador" — e a melhor solução talvez nem seja um botão. Tratar o pedido como ordem direta pula a etapa mais importante: entender o problema por trás dele.

A Decisão

O discovery inverte a ordem usual. Em vez de pedido → feature, faz-se problema → hipótese → validação → construção. O problema é observado no usuário real (Genba, §1.2). A hipótese é uma aposta de solução. A validação é o menor experimento que confirma ou refuta a aposta — uma conversa, um protótipo, uma medição. Só o que sobrevive à validação vira código.

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Engenharia que não enxerga custo otimiza no escuro. Um cartão recusado na serviço financeiro ou na provedor de nuvem, um pagamento do serviço de pagamento em atraso, um risco no serviço de conectividade — esses não são "problemas do financeiro". São sinais operacionais que afetam diretamente a continuidade da plataforma. Um sistema que não torna seu próprio custo visível não é operável de forma sustentável.

A separação tradicional entre "engenharia" e "custo" é uma ficção perigosa. Um serviço que escala lindamente mas cujo custo cresce mais rápido que o valor que entrega não é um sucesso técnico — é uma bomba-relógio. A viabilidade econômica não é um relatório que o financeiro emite depois; é uma propriedade do sistema, tão real quanto a latência ou a disponibilidade.

A Decisão

A plataforma trata seu próprio custo como parte da operação. A relação fundamental é a razão entre valor entregue e custo operacional: ela precisa crescer, ou ao menos manter-se saudável, conforme o sistema escala. Custos — infraestrutura (os ~40 servidores virtuais), licenças, pagamentos recorrentes — são tornados visíveis, e sinais de risco (um pagamento que vai falhar) são tratados com a mesma seriedade de um alerta de produção.

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Uma plataforma com muitas engines corre um risco arquitetural específico: o surgimento de um kernel-deus — um núcleo central que conhece todas as engines e do qual todas dependem. Quando ele existe, qualquer mudança nele ameaça o sistema inteiro, e nenhuma engine pode evoluir sozinha.

O acoplamento na direção errada é o vetor desse desastre. Quando o domínio — onde vivem as regras de negócio — depende diretamente do banco de dados, da biblioteca de e-mail, do framework web, ele fica refém de detalhes que deveriam ser substituíveis. Trocar o banco vira cirurgia de coração aberto; testar uma regra exige subir a infraestrutura inteira.

A Decisão

A arquitetura se organiza em camadas concêntricas. No centro, o domínio — entidades e regras puras, sem nenhuma dependência externa. Em volta, a aplicação — casos de uso que orquestram o domínio. Na borda, a infraestrutura — banco, rede, provedores. A regra inviolável: a seta de dependência sempre aponta para dentro. O domínio declara o que precisa (uma interface, uma "porta"); a infraestrutura implementa, dependendo do domínio, nunca o contrário.

Isto é a Inversão de Dependência aplicada com rigor. A consequência prática é profunda: o domínio torna-se testável sem nenhuma infraestrutura, e os detalhes externos tornam-se substituíveis sem abalar o núcleo. Não há kernel-deus porque não há centro do qual tudo dependa — há apenas a direção da seta.

A porta no domínio, o adaptador na borda

O domínio declara uma interface — o que ele precisa, em seus próprios termos. A infraestrutura fornece a implementação concreta.

// DOMÍNIO: declara o que precisa. Não sabe que existe PostgreSQL.
namespace plataforma\Core\Cliente\Dominio;

interface RepositorioDeClientes
{
 public function porId(ClienteId $id): ?Cliente;
 public function salvar(Cliente $cliente): void;
}

// INFRAESTRUTURA: implementa a porta. DEPENDE do domínio, não o contrário.
namespace plataforma\Infra\Persistencia;

use plataforma\Core\Cliente\Dominio\RepositorioDeClientes;

final class RepositorioDeClientesPostgres implements RepositorioDeClientes
{
 public function __construct(private readonly PDO $conexao) {}

 public function porId(ClienteId $id): ?Cliente
 {
 // O detalhe de persistência vive AQUI, na borda — substituível.
 $linha = $this->conexao->query('...')->fetch();
 return $linha ? Cliente::deLinha($linha) : null;
 }
 // ...
}

A Verificação

A regra não é confiada à boa vontade — é imposta pelo CI. O Deptrac mapeia as camadas e falha o build se uma dependência apontar para fora.

# Deptrac: a regra de dependência vira lei verificável no CI.
layers:
 - name: Dominio
 collectors: [{ type: directory, value: Core/.*/Dominio/.* }]
 - name: Infra
 collectors: [{ type: directory, value: Infra/.* }]
ruleset:
 Dominio: [] # o domínio NÃO pode depender de nada
 Infra: [Dominio] # a infra só pode depender do domínio

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Se cada engine expusesse suas tripas — suas tabelas, suas classes internas, seus detalhes —, as outras engines acabariam dependendo desses detalhes. O resultado seria o acoplamento total: nada poderia mudar dentro de uma engine sem quebrar quem espiava seu interior.

A questão é de fronteira e segredo. Para que muitas engines coexistam, cada uma precisa ser uma caixa com uma interface clara por fora e liberdade total por dentro. Sem essa disciplina, a "modularidade" é só uma ilusão de pastas separadas que na prática se entrelaçam.

A Decisão

Uma engine tem quatro partes. O contrato público — a interface que outras engines usam. O domínio interno — suas regras próprias, invisíveis de fora. As portas de saída — o que ela precisa de outras engines ou da infraestrutura, declarado como interfaces (seguindo §2.1). E a implementação privada — como o contrato é cumprido, totalmente escondida. Quem usa a engine toca apenas o contrato; o interior pode ser reescrito sem que ninguém perceba.

O contrato como única superfície

A engine de permissão expõe uma pergunta — "este sujeito pode esta ação?" — e nada mais. Como ela decide é assunto interno.

// CONTRATO PÚBLICO: tudo o que outras engines conhecem da permissão.
namespace plataforma\Core\Permission\Publico;

interface PermissionEngine
{
 // A única pergunta que o exterior faz. O "como" é segredo da engine.
 public function permite(
 Sujeito $sujeito,
 string $acao,
 Recurso $recurso,
 ): Decisao;
}

// IMPLEMENTAÇÃO PRIVADA: como a engine cumpre o contrato. Invisível de fora.
namespace plataforma\Core\Permission\Interno;

final class PermissionEnginePadrao implements PermissionEngine
{
 public function permite(Sujeito $s, string $acao, Recurso $r): Decisao
 {
 // Combina papéis (RBAC) e atributos (ABAC) — detalhe interno.
 if ($this->papeis->concede($s, $acao, $r)) {
 return Decisao::permitido();
 }
 return $this->atributos->avaliar($s, $acao, $r);
 }
}

A Verificação

O teste exercita a engine pelo seu contrato, exatamente como outra engine faria — provando que o contrato basta e que o interior é irrelevante para quem consome.

final class PermissionEngineTest extends TestCase
{
 public function test_consome_apenas_pelo_contrato(): void
 {
 // O teste só conhece a interface pública — como outra engine.
 PermissionEngine $engine = $this->engineComPapel('gestor');

 $decisao = $engine->permite(
 $this->sujeito('gestor'), 'cliente.editar', $this->recurso(),
 );

 $this->assertTrue($decisao->permitido);
 }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Se cada engine criasse suas próprias dependências — instanciando o banco, o cliente HTTP, as outras engines de que precisa — o acoplamento voltaria pela porta dos fundos. A engine de permissão "saberia" como construir a de auditoria, e trocar uma implementação exigiria caçar instanciações espalhadas por todo o código.

O localizador de serviços global (um service locator que qualquer engine consulta) parece resolver, mas só esconde o problema: a dependência passa a ser oculta — não se vê, lendo o construtor, do que a engine realmente precisa. O acoplamento vira invisível, e invisível é pior que explícito.

A Decisão

A composição segue a injeção de dependência por construtor. Cada engine recebe, ao ser construída, as implementações concretas das portas que declarou (§2.2) — ela não as cria nem as procura. Existe um único lugar, o composition root, que conhece todas as implementações concretas e monta o grafo inteiro de objetos. É o "SDK do Core": o ponto onde as peças se encaixam. Em todo o resto do sistema, só há abstrações.

A engine declara; a raiz fornece

A engine de auditoria precisa de um repositório e de um relógio. Ela os declara no construtor — e nunca os instancia.

// A engine DECLARA o que precisa. Não cria, não busca.
final class AuditEnginePadrao implements AuditEngine
{
 public function __construct(
 private readonly RepositorioDeAuditoria $repo, // porta
 private readonly Relogio $relogio, // porta
 ) {}

 public function registrar(EventoDeAuditoria $e): void
 {
 $this->repo->acrescentar($e->em($this->relogio->agora()));
 }
}

// COMPOSITION ROOT: o ÚNICO lugar que conhece implementações concretas.
final class CoreContainer
{
 public function auditEngine(): AuditEngine
 {
 // A raiz injeta as implementações nas portas da engine.
 return new AuditEnginePadrao(
 $this->repositorioDeAuditoria(), // implementação concreta
 $this->relogioDoSistema(),
 );
 }

 public function permissionEngine(): PermissionEngine
 {
 // Trocar uma implementação = mudar UMA linha, aqui.
 return new PermissionEnginePadrao($this->repositorioDePapeis());
 }
}

A Verificação

Como as dependências são injetadas, o teste fornece dublês triviais — provando que a engine funciona com qualquer implementação das suas portas.

final class AuditEngineTest extends TestCase
{
 public function test_engine_funciona_com_dubles_injetados(): void
 {
 // A injeção torna o teste trivial: passo dublês pelas portas.
 $repo = new RepositorioDeAuditoriaEmMemoria();
 $engine = new AuditEnginePadrao($repo, new RelogioFixo());

 $engine->registrar(EventoDeAuditoria::de('cliente.criado'));

 $this->assertCount(1, $repo->registros());
 }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Toda chamada a um sistema externo é uma promessa que pode ser quebrada: o parceiro pode falhar, travar, ou responder devagar demais. Quando o código assume que a chamada sempre retorna rápido e com sucesso, uma única dependência lenta consegue travar threads, esgotar recursos e derrubar o sistema inteiro — um problema alheio virando um problema seu.

O caso é concreto na operação da plataforma: as conexões órfãs no Firebird, originadas de processos do sistema de rastreamento que não as fechavam, acumulavam até degradar tudo. Bater repetidamente numa integração que está saturada não ajuda — só agrava. A resiliência é a disciplina de conter a falha externa antes que ela se espalhe.

A Decisão

O timeout impede a espera infinita: passou do limite, a chamada falha de forma controlada. O retry tenta de novo o que é transitório, com recuo entre tentativas para não martelar o parceiro. O circuit breaker é o mais importante: após muitas falhas, ele "abre" e passa a falhar imediatamente, sem nem tentar a chamada — dando ao parceiro tempo de se recuperar e protegendo o próprio sistema de desperdiçar recursos numa porta que não abre.

A chamada protegida pelos três mecanismos

// Toda chamada externa passa pelos três mecanismos.
final class ChamadaResiliente
{
 public function executar(string $servico, callable $chamada): mixed
 {
 // 1) Circuit breaker: se está aberto, falha JÁ — nem tenta.
 if ($this->breaker->estaAberto($servico)) {
 throw new CircuitoAberto($servico);
 }

 // 2) Retry com recuo para falhas transitórias.
 return $this->retry->tentar(fn() =>
 // 3) Timeout: não espera além do limite.
 $this->comTimeout($servico, $chamada)
 );
 }
}

// O breaker abre após muitas falhas e protege parceiro e sistema.
final class CircuitBreaker
{
 public function registrarResultado(string $servico, bool $sucesso): void
 {
 if ($sucesso) {
 $this->estado->fechar($servico); // volta ao normal
 return;
 }
 $falhas = $this->estado->incrementarFalhas($servico);
 if ($falhas >= $this->limite) {
 // Para de tentar: dá ao parceiro tempo de recuperar.
 $this->estado->abrir($servico, $this->pausaSegundos);
 }
 }
}

A Verificação

final class CircuitBreakerTest extends TestCase
{
 public function test_abre_apos_o_limite_de_falhas(): void
 {
 $breaker = $this->breaker(limite: 3);
 foreach ([false, false, false] as $r) {
 $breaker->registrarResultado('firebird', $r);
 }
 // Após 3 falhas, o circuito abre: não tenta mais.
 $this->assertTrue($breaker->estaAberto('firebird'));
 }

 public function test_sucesso_fecha_o_circuito(): void
 {
 $breaker = $this->breaker(limite: 3);
 $breaker->registrarResultado('firebird', true);
 $this->assertFalse($breaker->estaAberto('firebird'));
 }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Quando uma engine, ao concluir uma ação, precisa avisar todas as outras interessadas chamando-as diretamente, ela passa a conhecer cada uma delas. Criar um cliente vira "criar o cliente, depois notificar, depois auditar, depois atualizar o parceiro" — e a cada nova reação, é preciso reabrir e editar a engine que cria o cliente.

Esse acoplamento sufoca o crescimento. A engine que causa o fato acumula responsabilidades que não são dela e fica dependente de todas as outras. Pior: se o aviso a um interessado é feito numa transação separada da ação principal, abre-se a porta para inconsistência — o cliente é criado mas a notificação se perde, ou a notificação dispara para um cliente que, por um erro, não chegou a ser salvo.

A Decisão

Quando algo relevante acontece, a engine publica um evento de domínio — um fato no passado, como "ClienteCriado" — e segue em frente, sem saber quem reagirá. Outras engines se inscrevem nos eventos que lhes interessam e reagem de forma independente. Para garantir consistência, usa-se o padrão outbox: o evento é gravado na mesma transação de banco que persiste o fato. Ou ambos são salvos, ou nenhum — eliminando eventos perdidos e fatos fantasma.

Publicar o fato, gravando na mesma transação

// A engine anuncia o fato. Não sabe — nem precisa saber — quem reage.
final class CriarCliente
{
 public function executar(DadosDoCliente $dados): void
 {
 $this->transacao->executar(function () use ($dados) {
 $cliente = Cliente::criar($dados);
 $this->repo->salvar($cliente);

 // OUTBOX: o evento grava na MESMA transação do fato.
 // Ou os dois persistem, ou nenhum.
 $this->outbox->publicar(new ClienteCriado($cliente->id()));
 });
 }
}

// Um reator se INSCREVE no evento. A origem não o conhece.
final class EnviarBoasVindas implements Reator
{
 public function reageA(): string
 {
 return ClienteCriado::class; // inscrição
 }

 public function manipular(ClienteCriado $evento): void
 {
 // Reage de forma independente. Adicionar este reator
 // NÃO exigiu tocar a engine que cria o cliente.
 $this->mensageria->enviarBoasVindas($evento->clienteId);
 }
}

A Verificação

final class CriarClienteTest extends TestCase
{
 public function test_publica_evento_na_mesma_transacao(): void
 {
 $outbox = new OutboxEmMemoria();
 $uc = $this->casoDeUsoCom($outbox);

 $uc->executar(DadosDoCliente::deExemplo());

 // O fato foi salvo E o evento foi publicado — juntos.
 $this->assertTrue($outbox->publicou(ClienteCriado::class));
 }

 public function test_falha_ao_salvar_nao_publica_evento(): void
 {
 // Se a transação falha, NEM fato NEM evento persistem.
 $uc = $this->casoDeUsoQueFalhaAoSalvar();
 $this->expectException(FalhaAoSalvar::class);
 $uc->executar(DadosDoCliente::deExemplo());
 }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Um contrato publicado — a interface de uma engine, o formato de um evento, a estrutura de uma resposta — é uma promessa àqueles que o consomem. No momento em que outra engine, outro serviço ou um parceiro passa a depender dele, alterá-lo deixa de ser uma decisão local: vira uma mudança que pode quebrar o sistema de quem confiou na promessa.

A tentação é "só ajustar" o contrato: renomear um campo, mudar seu tipo, remover algo que parece não ser mais usado. Cada um desses ajustes é uma ruptura silenciosa — funciona na engine que mudou, mas quebra, talvez em produção e sem aviso, todo consumidor que esperava a forma anterior. Em um ecossistema com muitos consumidores e parceiros, essa quebra se multiplica.

A Decisão

A evolução de contratos segue uma regra clara. Uma mudança aditiva — acrescentar um campo opcional, uma operação nova — não quebra ninguém e pode ser feita no próprio contrato. Uma mudança que quebra — remover ou renomear um campo, alterar um tipo, mudar o significado de algo — exige uma nova versão do contrato. Durante a transição, a versão antiga e a nova coexistem: os consumidores migram no seu ritmo, e só quando todos saíram da versão antiga ela pode ser aposentada.

Distinguir o aditivo do que quebra

// Evento versionado: a v2 NÃO altera a v1 — coexiste com ela.
final class ClienteCriadoV1
{
 public function __construct(
 public readonly string $clienteId,
 ) {}
}

final class ClienteCriadoV2
{
 public function __construct(
 public readonly string $clienteId,
 public readonly string $tenantId, // campo novo
 ) {}
}

// Durante a migração, a engine publica AMBAS as versões.
final class PublicarClienteCriado
{
 public function publicar(Cliente $c): void
 {
 // Consumidores da v1 e da v2 são atendidos ao mesmo tempo.
 $this->outbox->publicar(new ClienteCriadoV1($c->id()));
 $this->outbox->publicar(new ClienteCriadoV2($c->id(), $c->tenantId()));
 // A v1 só é removida quando NENHUM consumidor depende mais dela.
 }
}

A Verificação

final class CompatibilidadeDeContratoTest extends TestCase
{
 public function test_consumidor_v1_continua_funcionando(): void
 {
 // Um consumidor que só conhece a v1 não pode ser afetado pela v2.
 $consumidorV1 = new ReatorQueEsperaV1();
 $evento = new ClienteCriadoV1('cli-1');

 $consumidorV1->manipular($evento); // funciona como sempre

 $this->assertTrue($consumidorV1->processou('cli-1'));
 }

 public function test_mudanca_aditiva_nao_quebra_v1(): void
 {
 // Adicionar campo opcional à v1 não pode quebrar quem já a usa.
 $this->assertConsumidorV1Intacto();
 }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Uma plataforma orientada por metadados promete algo sedutor: descrever o sistema como dado, sem programar. Um formulário novo vira um registro; uma regra, uma linha de configuração. Mas há uma armadilha à espreita, e ela é traiçoeira justamente porque começa parecendo uma vitória.

A armadilha é a linguagem de programação acidental. Conforme o metadado ganha poder — primeiro um campo, depois uma condição, depois um laço, depois uma expressão aninhada — a configuração silenciosamente se transforma numa linguagem de programação completa. Só que uma linguagem sem tipos, sem testes, sem depurador, sem documentação, e que ninguém jamais projetou conscientemente. O que deveria ser dado vira código disfarçado, e o pior tipo de código: o que finge não ser código.

A Decisão

O metamodelo é a descrição declarativa do sistema — o que existe, não como funciona. Uma entidade "cliente" é descrita por seus campos, seus tipos, suas relações: estrutura. Como o cliente é validado, salvo, ou cobrado é algoritmo, e algoritmo é código. A regra que mantém a sanidade: o metadado descreve, o código executa, e a fronteira entre os dois nunca é cruzada. Quando surge a tentação de colocar uma decisão no metadado, essa decisão vira uma ação nomeada (§3.2) — um ponto de código referenciado pelo dado, não lógica embutida nele.

Descrever uma entidade como dado

O metamodelo guarda a descrição — campos, tipos, obrigatoriedade. Note o que não está aqui: nenhuma lógica, nenhuma condição, nenhum algoritmo.

-- O metamodelo DESCREVE a estrutura. Nenhuma lógica aqui.
CREATE TABLE meta_entidade (
    id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    chave        TEXT NOT NULL,            -- 'cliente'
    rotulo       TEXT NOT NULL             -- 'Cliente'
);

CREATE TABLE meta_campo (
    id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    entidade_id  BIGINT NOT NULL REFERENCES meta_entidade,
    chave        TEXT NOT NULL,            -- 'cnpj'
    tipo         TEXT NOT NULL,            -- 'texto','numero','data'
    obrigatorio  BOOLEAN NOT NULL DEFAULT false
    -- NÃO existe coluna 'logica' ou 'expressao'. Isso seria a armadilha.
);

// O CÓDIGO lê a descrição e a realiza. A lógica vive aqui, testável.
final class LeitorDeMetamodelo
{
    public function entidade(string $chave): DescricaoDeEntidade
    {
        // Carrega a DESCRIÇÃO (dado) e a entrega como um objeto rico.
        $campos = $this->repo->camposDe($chave);
        return new DescricaoDeEntidade($chave, $campos);
        // Como validar cada tipo é lógica DESTE código, não do metadado.
    }
}

A Verificação

final class MetamodeloTest extends TestCase
{
    public function test_descreve_estrutura_sem_logica(): void
    {
        $entidade = $this->leitor->entidade('cliente');

        // O metadado entrega ESTRUTURA: campos e tipos.
        $this->assertTrue($entidade->temCampo('cnpj'));
        $this->assertSame('texto', $entidade->tipoDe('cnpj'));
    }

    public function test_metamodelo_nao_contem_expressoes(): void
    {
        // Garante a fronteira: nenhum campo guarda lógica/expressão.
        $this->assertNenhumCampoContemLogica('cliente');
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

O tópico anterior estabeleceu uma fronteira rígida: metadado descreve, não programa. Mas isso levanta uma pergunta imediata. Se o dado não pode conter lógica, como um formulário descrito como dado dispara uma validação de negócio? Como uma regra configurável executa uma ação? Sem uma resposta, a fronteira se torna uma prisão — e a tentação de burlá-la, embutindo "só uma lógica" no dado, volta com força.

O risco, sem um mecanismo claro, é o pior dos dois mundos: ou o metadado vira código disfarçado (a linguagem acidental do §3.1), ou o sistema fica engessado, incapaz de associar comportamento à sua descrição declarativa. Precisamos de uma ponte que conecte o dado ao código sem que um contamine o outro.

A Decisão

Uma ação nomeada é um pedaço de comportamento encapsulado numa classe de código, identificado por um nome estável — "aprovar_pedido", "calcular_frete", "validar_cnpj". O metadado refere esse nome; ele não sabe (nem precisa saber) como a ação é implementada. Um registro de ações faz a ponte: dado um nome, ele resolve a classe de código correspondente. Assim, o dado permanece declarativo (refere nomes), o código permanece testável (implementa ações), e a fronteira do §3.1 é honrada — a lógica vive no código, referenciada pelo dado.

Definir e registrar uma ação

Uma ação é uma classe com um contrato único — executar. O nome a torna referenciável pelo dado.

// Toda ação nomeada cumpre este contrato. O nome a torna referenciável.
interface Acao
{
    public function nome(): string;            // 'aprovar_pedido'
    public function executar(Contexto $ctx): Resultado;
}

final class AprovarPedido implements Acao
{
    public function nome(): string { return 'aprovar_pedido'; }

    public function executar(Contexto $ctx): Resultado
    {
        // A lógica REAL vive aqui — código testável, tipado.
        $pedido = $ctx->pedido();
        $pedido->aprovar();
        return Resultado::ok();
    }
}

// A PONTE: resolve um nome (dado) para uma ação (código).
final class RegistroDeAcoes
{
    /** @var array<string, Acao> nome → ação */
    public function __construct(private readonly array $acoes) {}

    public function resolver(string $nome): Acao
    {
        // O metadado passou só o NOME. Aqui ele vira código executável.
        return $this->acoes[$nome]
            ?? throw new AcaoNaoRegistrada($nome);
    }
}

-- O metadado REFERE a ação pelo nome. Nenhuma lógica embutida.
INSERT INTO meta_botao (entidade, rotulo, acao)
VALUES ('pedido', 'Aprovar', 'aprovar_pedido');
--                                          ^^^^^^^^^^^^^^^
-- Só o NOME. A implementação é código, resolvida pelo registro.

A Verificação

final class AcaoNomeadaTest extends TestCase
{
    public function test_registro_resolve_nome_para_acao(): void
    {
        $registro = new RegistroDeAcoes(['aprovar_pedido' => new AprovarPedido()]);

        $acao = $registro->resolver('aprovar_pedido');

        $this->assertInstanceOf(AprovarPedido::class, $acao);
    }

    public function test_nome_desconhecido_falha_alto(): void
    {
        // Um nome não registrado falha cedo e claro — não silenciosamente.
        $this->expectException(AcaoNaoRegistrada::class);
        (new RegistroDeAcoes([]))->resolver('inexistente');
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Regras de negócio são a parte mais volátil de qualquer sistema. "Clientes acima de tal porte exigem aprovação", "pedidos de tal tipo têm desconto", "operações de tal valor disparam revisão" — essas regras mudam com o mercado, com a estratégia, com a regulação. Quando estão cravadas no código, cada mudança de regra é um pedido ao time de desenvolvimento, um ciclo, um deploy. O negócio fica refém da agenda da engenharia para ajustar o que é, essencialmente, uma decisão de negócio.

A solução óbvia — colocar as regras como dado, editáveis sem deploy — esbarra na armadilha do §3.1. Uma regra é, afinal, lógica condicional. Se a deixarmos livre no dado, ela acumula condições aninhadas, operadores arbitrários, expressões complexas — e vira exatamente a linguagem de programação acidental que queremos evitar. Precisamos de regras como dado, mas com uma forma tão rígida que não há espaço para a degradação.

A Decisão

O Business Rules Engine avalia regras com uma estrutura deliberadamente restrita. Cada regra é um par condição → ação. A condição é declarativa e tem forma fixa: um atributo, um operador de um conjunto fechado (igual, maior, contém...), e um valor. Nada de aninhamento arbitrário, nada de expressões livres. A ação é uma ação nomeada (§3.2): a regra refere o que fazer, sem conter a lógica. O motor avalia as condições contra os dados e, quando satisfeitas, dispara as ações — registrando cada execução para auditoria. A rigidez da forma é o que mantém a regra como dado legível, e não como código disfarçado.

As regras como dado estruturado

-- Regras como DADO, em forma fixa. Condição e ação separadas.
CREATE TABLE bre_rule (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    chave       TEXT NOT NULL,        -- 'aprovacao_grande_frota'
    entidade    TEXT NOT NULL,        -- 'cliente'
    ativa       BOOLEAN NOT NULL DEFAULT true
);

-- Condição: forma FIXA. atributo + operador + valor. Sem aninhamento livre.
CREATE TABLE bre_condition (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    rule_id     BIGINT NOT NULL REFERENCES bre_rule,
    atributo    TEXT NOT NULL,        -- 'frota'
    operador    TEXT NOT NULL,        -- conjunto FECHADO: '>', '=', 'contém'
    valor       TEXT NOT NULL         -- '50'
);

-- Ação: referência a ação NOMEADA (§3.2). Não contém lógica.
CREATE TABLE bre_action (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    rule_id     BIGINT NOT NULL REFERENCES bre_rule,
    acao        TEXT NOT NULL         -- 'exigir_aprovacao' (nome, §3.2)
);

// O motor avalia a forma fixa e dispara ações nomeadas.
final class AvaliadorDeRegras
{
    public function avaliar(string $entidade, Dados $dados): void
    {
        foreach ($this->repo->regrasAtivas($entidade) as $regra) {
            if ($this->condicoesSatisfeitas($regra, $dados)) {
                // Resolve a ação NOMEADA (§3.2) e a executa.
                foreach ($regra->acoes() as $nomeAcao) {
                    $this->acoes->resolver($nomeAcao)->executar($dados->contexto());
                }
                $this->registro->execucao($regra, $dados);  // auditável
            }
        }
    }

    private function condicoesSatisfeitas(Regra $r, Dados $d): bool
    {
        // Avalia atributo/operador/valor — operadores de conjunto fechado.
        foreach ($r->condicoes() as $c) {
            if (! $this->operadores->aplicar($c->operador, $d->valor($c->atributo), $c->valor)) {
                return false;
            }
        }
        return true;
    }
}

A Verificação

final class BusinessRulesTest extends TestCase
{
    public function test_regra_dispara_quando_condicao_satisfeita(): void
    {
        // Regra: SE frota > 50 ENTÃO exigir_aprovacao. Dado: frota = 80.
        $acaoEspia = new AcaoEspia('exigir_aprovacao');
        $avaliador = $this->avaliadorCom($acaoEspia, regra: 'frota > 50 → exigir_aprovacao');

        $avaliador->avaliar('cliente', $this->dadosComFrota(80));

        $this->assertTrue($acaoEspia->foiExecutada());
    }

    public function test_regra_nao_dispara_quando_condicao_falsa(): void
    {
        // Mesma regra, dado: frota = 20 (não satisfaz).
        $acaoEspia = new AcaoEspia('exigir_aprovacao');
        $avaliador = $this->avaliadorCom($acaoEspia, regra: 'frota > 50 → exigir_aprovacao');

        $avaliador->avaliar('cliente', $this->dadosComFrota(20));

        $this->assertFalse($acaoEspia->foiExecutada());
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

A promessa é poderosa: a partir de uma única descrição no metamodelo, quatro engines geram a interface inteira — o Form Engine monta o formulário, o Screen Engine compõe a tela, o Menu Engine constrói a navegação, o Grid Engine renderiza as listagens. Descrever uma vez, gerar em quatro lugares. Mas há um risco prático que mina a promessa por dentro.

O risco é a duplicação da lógica de resolução. Antes de gerar qualquer coisa, cada engine precisa responder perguntas idênticas: qual versão do metadado vale agora? Há um override específico desta empresa que sobrepõe o padrão? Quais permissões do usuário escondem ou revelam campos? Se cada engine responde essas perguntas à sua maneira, surgem quatro implementações sutilmente diferentes — e elas divergem. O formulário mostra um campo que a grade esconde; o menu respeita um override que a tela ignora. "Dirigido por metadados" vira quatro verdades em conflito, e o usuário vê um sistema incoerente.

A Decisão

A resolução do metadado — decidir a versão vigente, aplicar o override da empresa, filtrar pela permissão do usuário — acontece em um só lugar: o resolvedor. Ele recebe o contexto (empresa, usuário) e devolve a descrição resolvida: a verdade única sobre o que existe, o que está visível e como. Os quatro engines (Form, Screen, Menu, Grid) recebem essa descrição já pronta e apenas a renderizam, cada um à sua maneira visual. Eles nunca tocam na resolução; logo, não há como divergirem. Uma só verdade, quatro formas de apresentá-la.

O resolvedor como única fonte de verdade

// O ÚNICO lugar que resolve versão, override e permissão.
final class ResolvedorDeMetadados
{
    public function resolver(string $entidade, Contexto $ctx): DescricaoResolvida
    {
        // 1) versão vigente   2) override da empresa   3) permissão do usuário
        $base     = $this->versoes->vigente($entidade);
        $comOver  = $this->overrides->aplicar($base, $ctx->empresa());
        $visivel  = $this->permissao->filtrar($comOver, $ctx->usuario());

        // A verdade única que os quatro engines consumirão.
        return new DescricaoResolvida($visivel);
    }
}

// Os quatro engines RECEBEM a descrição resolvida. Não a calculam.
final class FormEngine
{
    public function renderizar(DescricaoResolvida $desc): Formulario
    {
        // Apenas apresenta os campos JÁ resolvidos. Zero lógica de versão/permissão.
        return Formulario::deCampos($desc->campos());
    }
}

final class GridEngine
{
    public function renderizar(DescricaoResolvida $desc): Grade
    {
        // MESMA descrição do FormEngine → impossível divergir dele.
        return Grade::deColunas($desc->campos());
    }
}

A Verificação

final class ResolucaoUnicaTest extends TestCase
{
    public function test_engines_veem_a_mesma_verdade(): void
    {
        // Uma resolução, consumida por dois engines diferentes.
        $desc = $this->resolvedor->resolver('cliente', $this->contexto());

        $campoForm = (new FormEngine())->renderizar($desc)->camposVisiveis();
        $colsGrid  = (new GridEngine())->renderizar($desc)->colunasVisiveis();

        // Form e Grid DEVEM concordar sobre os campos visíveis.
        $this->assertEquals($campoForm, $colsGrid);
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

O Metadata Studio é o ápice da plataforma orientada por metadados: a tela onde se criam formulários, campos, menus, relatórios e workflows sem escrever código, no espírito das grandes plataformas de baixo código. É o que permite ao negócio construir e ajustar o sistema na velocidade da necessidade. Mas justamente por ser tão poderoso, ele carrega um perigo que o Capítulo I já havia nomeado.

"Parametrização sem governança" é um antipadrão. Se qualquer pessoa edita o metamodelo livremente — sem validação que impeça uma configuração incoerente, sem versão que permita reverter, sem trilha que registre quem mudou o quê —, a plataforma se transforma num caos configurável. Uma alteração quebra algo em outro canto, e ninguém sabe quem a fez, quando, ou como desfazê-la. O poder de mudar tudo sem código vira o poder de quebrar tudo sem rastro. A flexibilidade, sem governança, devora a operabilidade.

A Decisão

O Metadata Studio oferece a flexibilidade do baixo código dentro de uma estrutura de governança. Validação: antes de uma alteração virar realidade, ela é checada — um campo que referencia uma ação inexistente, uma estrutura incoerente, é rejeitado na porta. Versão imutável: cada mudança publicada cria uma nova versão numerada do metamodelo; as versões anteriores não são apagadas, o que torna qualquer alteração reversível. Auditoria: toda edição registra quem a fez, quando, e o que mudou. Assim, o poder de configurar sem código convive com a capacidade de depurar, reverter e prestar contas — a flexibilidade ganha a operabilidade que o caos configurável destruiria.

A publicação governada de uma mudança

// Toda alteração passa por validação, versão e auditoria. Sem exceção.
final class PublicarAlteracaoDeMetadados
{
    public function publicar(Alteracao $alteracao, Autor $autor): Versao
    {
        // 1) VALIDAÇÃO: rejeita o incoerente ANTES de publicar.
        $problemas = $this->validador->checar($alteracao);
        if ($problemas->existem()) {
            throw new AlteracaoInvalida($problemas);  // não passa
        }

        // 2) VERSÃO IMUTÁVEL: cria nova versão; as antigas permanecem.
        $versao = $this->versoes->criarNova($alteracao);

        // 3) AUDITORIA: quem, quando, o quê.
        $this->auditoria->registrar($autor, $alteracao, $versao);

        return $versao;
    }
}

// Como as versões são imutáveis, reverter é restaurar uma anterior.
final class ReverterMetadados
{
    public function paraVersao(int $numero, Autor $autor): Versao
    {
        $anterior = $this->versoes->porNumero($numero);  // nunca foi apagada

        // Reverter é publicar a versão anterior como nova — também auditado.
        return $this->publicar->publicar(Alteracao::restaurar($anterior), $autor);
    }
}

A Verificação

final class GovernancaDoStudioTest extends TestCase
{
    public function test_alteracao_invalida_e_rejeitada(): void
    {
        // Uma alteração incoerente NÃO pode virar versão.
        $this->expectException(AlteracaoInvalida::class);
        $this->publicar->publicar($this->alteracaoIncoerente(), $this->autor());
    }

    public function test_toda_publicacao_e_auditada(): void
    {
        $versao = $this->publicar->publicar($this->alteracaoValida(), $this->autor('ana'));

        // O registro de auditoria DEVE existir, com autor e versão.
        $this->assertTrue($this->auditoria->temRegistro(autor: 'ana', versao: $versao));
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Uma plataforma cresce em tabelas — dezenas, centenas. Se cada uma é modelada à sua maneira, com sua própria coluna de identidade aqui, seu próprio jeito de marcar exclusão ali, seu padrão particular de registrar quando algo mudou, então não há nada de genérico no sistema. Cada engine que precisa tratar tabelas de forma uniforme — auditoria, permissão, soft delete — esbarra na diversidade e acaba precisando de código específico para cada caso.

O resultado é a antítese de uma plataforma: um amontoado de tabelas que só se parecem por acaso, exigindo lógica sob medida para cada uma. O que deveria ser uma operação genérica ("marque esta linha como excluída", "diga a que empresa ela pertence") vira uma exceção por tabela. A falta de um contrato estrutural comum mina a própria ideia de um núcleo que serve a tudo.

A Decisão

Cada tabela da plataforma segue convenções canônicas fixas. Uma coluna id de identidade estável, gerada pelo banco. Uma coluna tenant_id que diz a qual empresa a linha pertence (a base do isolamento multiempresa, §4.2). Colunas created_at e updated_at que registram quando a linha nasceu e mudou. Uma coluna deleted_at que implementa o soft delete (§4.3): nula significa viva. Esse contrato uniforme não é burocracia — é o que permite que um único código genérico trate qualquer tabela: filtrar por empresa, ocultar excluídos, ordenar por criação, tudo sem saber qual tabela específica está manipulando.

O contrato como base de toda tabela

-- Toda tabela de negócio herda este contrato estrutural.
CREATE TABLE cliente (
    -- ── contrato canônico (idêntico em TODA tabela) ──
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tenant_id   BIGINT      NOT NULL,                  -- §4.2
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at  TIMESTAMPTZ,                            -- nulo = vivo (§4.3)

    -- ── campos específicos do negócio ──
    nome        TEXT        NOT NULL,
    documento   TEXT        NOT NULL
);

-- O índice de empresa+vivo serve quase toda consulta (§4.2, §4.3).
CREATE INDEX ix_cliente_tenant_vivo
    ON cliente (tenant_id) WHERE deleted_at IS NULL;

// Porque o contrato é uniforme, UM repositório serve QUALQUER tabela.
abstract class RepositorioCanonico
{
    abstract protected function tabela(): string;

    public function vivosDoTenant(int $tenantId): array
    {
        // Filtra por empresa e oculta excluídos — genérico, sem saber a tabela.
        return $this->conexao->buscar(
            "SELECT * FROM {$this->tabela()}
              WHERE tenant_id = :t AND deleted_at IS NULL",
            ['t' => $tenantId],
        );
    }
}

A Verificação

final class ContratoCanonicoTest extends TestCase
{
    /** @dataProvider todasAsTabelas */
    public function test_toda_tabela_segue_o_contrato(string $tabela): void
    {
        $colunas = $this->colunasDe($tabela);

        // Nenhuma tabela escapa do contrato estrutural.
        foreach (['id', 'tenant_id', 'created_at', 'updated_at', 'deleted_at'] as $c) {
            $this->assertContains($c, $colunas, "{$tabela} sem coluna canônica {$c}");
        }
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Numa plataforma que serve muitas empresas sobre a mesma base de dados, existe um incidente que supera todos os outros em gravidade: uma empresa enxergar os dados de outra. Não é um bug comum — é uma quebra de confiança, de contrato comercial e, frequentemente, da legislação de proteção de dados. Uma única consulta que esqueça de filtrar pela empresa certa pode expor informações sigilosas de um cliente a outro.

O perigo é que, na abordagem ingênua, o isolamento depende inteiramente de o desenvolvedor lembrar de adicionar a cláusula de filtro por empresa em toda consulta. Centenas de consultas, escritas por pessoas diferentes ao longo de anos — basta uma esquecer o filtro para abrir o vazamento. Confiar a segurança multiempresa à memória humana, consulta por consulta, é construir sobre areia. O isolamento precisa ser garantido por algo mais forte que a disciplina.

A Decisão

A separação entre empresas usa defesa em profundidade — três travas independentes. A primeira, na aplicação: todo acesso a dados injeta automaticamente o tenant_id do contexto, sem depender de o desenvolvedor lembrar. A segunda, e mais importante, no banco: o Row-Level Security (RLS) do PostgreSQL força o filtro por empresa no nível do próprio banco — mesmo que uma consulta esqueça a cláusula, o banco recusa devolver linhas de outra empresa. A terceira, no teste: provas automatizadas tentam ativamente acessar dados de outra empresa e verificam que isso é impossível. Nenhuma trava sozinha é suficiente; juntas, tornam o vazamento improvável até diante de um erro humano.

A trava do banco: Row-Level Security

-- A 2ª trava: o BANCO força o isolamento, não só a aplicação.
ALTER TABLE cliente ENABLE ROW LEVEL SECURITY;

-- Política: só enxerga linhas da empresa do contexto atual.
CREATE POLICY isolamento_tenant ON cliente
    USING (tenant_id = current_setting('app.tenant_id')::BIGINT);

-- Mesmo um SELECT sem WHERE tenant_id devolve APENAS a empresa atual.
-- Esquecer o filtro na aplicação NÃO vaza dados: o banco recusa.

// A 1ª trava: a aplicação fixa o tenant do contexto a cada requisição.
final class ContextoDeTenant
{
    public function ativar(int $tenantId, Conexao $conexao): void
    {
        // Informa ao banco qual empresa é a do contexto (alimenta o RLS).
        $conexao->executar(
            "SET app.tenant_id = :t", ['t' => $tenantId],
        );
        // A partir daqui, TODA consulta nesta conexão é isolada pelo banco.
    }
}

A Verificação

final class IsolamentoTenantTest extends TestCase
{
    public function test_tenant_nao_ve_dados_de_outro(): void
    {
        // Empresa A cria um cliente.
        $this->comoTenant(1)->criarCliente('Cliente da Empresa A');

        // Empresa B tenta listar — e NÃO pode ver o cliente de A.
        $clientesDeB = $this->comoTenant(2)->listarClientes();

        $this->assertEmpty($clientesDeB, 'VAZAMENTO: B viu dados de A!');
    }

    public function test_consulta_sem_filtro_ainda_isola(): void
    {
        // Mesmo uma consulta "esquecida" (sem WHERE tenant) deve isolar.
        $this->comoTenant(1)->criarCliente('A');
        $todos = $this->comoTenant(2)->queryBruta('SELECT * FROM cliente');
        $this->assertEmpty($todos, 'RLS falhou: filtro do banco não isolou');
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Apagar dados de verdade — o DELETE físico que remove a linha do banco para sempre — é, numa plataforma de negócio, quase sempre um erro disfarçado de operação rotineira. O cliente que foi "excluído" por engano precisa voltar. A operação que "sumiu" precisa ser auditada por uma questão fiscal. A alteração que alguém fez ontem precisa ser comparada com a de hoje. Dado apagado fisicamente não volta, não se audita, não se compara — ele simplesmente deixou de existir, levando consigo qualquer resposta sobre o passado.

E não é só sobre exclusão. O próprio estado atual de um registro conta apenas metade da história. Saber que um limite de crédito é hoje um certo valor não diz quem o alterou, quando, nem qual era antes. Em um sistema de negócio, o histórico das mudanças é tão importante quanto o estado presente — para auditoria, para resolver disputas, para entender como se chegou aqui. Um sistema que só guarda o agora é um sistema com amnésia.

A Decisão

Duas decisões preservam a memória do sistema. O soft delete: excluir um registro não o remove do banco; apenas preenche a coluna deleted_at do contrato canônico (§4.1). O dado desaparece das telas e das consultas normais (que filtram por deleted_at IS NULL), mas continua existindo — recuperável com um gesto, auditável a qualquer momento. O histórico de mudanças: cada alteração relevante de um registro é registrada — o valor anterior, o novo, quem mudou, quando. Assim, o sistema guarda não só o estado atual, mas a trilha que levou a ele. Juntas, essas decisões garantem que nada se perca: nem o que foi excluído, nem o que foi alterado.

Excluir sem apagar; consultar só os vivos

-- "Excluir" é marcar a data, não remover a linha.
UPDATE cliente SET deleted_at = now()
WHERE id = 42 AND deleted_at IS NULL;

-- O dado continua no banco. Pode voltar a qualquer momento:
UPDATE cliente SET deleted_at = NULL WHERE id = 42;  -- "ressuscita"

-- As consultas normais veem apenas os vivos (e o índice parcial os serve).
SELECT * FROM cliente
WHERE tenant_id = 7 AND deleted_at IS NULL;

-- O histórico registra CADA mudança relevante de um registro.
CREATE TABLE historico_alteracao (
    id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tenant_id    BIGINT      NOT NULL,
    tabela       TEXT        NOT NULL,        -- 'cliente'
    registro_id  BIGINT      NOT NULL,        -- 42
    campo        TEXT        NOT NULL,        -- 'limite_credito'
    valor_antigo TEXT,                            -- '1000'
    valor_novo   TEXT,                            -- '5000'
    autor_id     BIGINT      NOT NULL,        -- quem mudou
    em           TIMESTAMPTZ NOT NULL DEFAULT now()  -- quando
);
-- Estado atual vive em 'cliente'; a TRILHA até ele vive aqui.

A Verificação

final class SoftDeleteTest extends TestCase
{
    public function test_excluido_some_das_consultas_mas_existe(): void
    {
        $id = $this->repo->criar('Cliente');
        $this->repo->excluir($id);  // soft delete

        // Some das consultas normais...
        $this->assertNull($this->repo->buscarVivo($id));
        // ...mas continua existindo no banco.
        $this->assertNotNull($this->repo->buscarIncluindoExcluidos($id));
    }

    public function test_pode_ser_recuperado(): void
    {
        $id = $this->repo->criar('Cliente');
        $this->repo->excluir($id);
        $this->repo->recuperar($id);  // volta à vida

        $this->assertNotNull($this->repo->buscarVivo($id));
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Tudo o que importa numa plataforma é, em essência, um fato que aconteceu: um cliente foi criado, um pedido foi emitido, um documento fiscal eletrônico foi importado. O Capítulo II estabeleceu como esses fatos são anunciados — os eventos de domínio e o outbox transacional. Mas falta uma peça: onde esses fatos vivem de forma permanente, e quem é o dono da verdade sobre o que aconteceu.

Sem um repositório único de fatos, cada consumidor acaba reconstruindo a história à sua maneira. A auditoria monta sua própria visão do que ocorreu; as integrações inferem os fatos a partir do estado atual; a camada de IA reconstrói uma sequência a partir de outra fonte. O resultado são várias versões da verdade, sutilmente divergentes — a auditoria diz uma coisa, a integração diz outra, e ninguém sabe qual está certa. Quando há mais de uma fonte de verdade sobre os fatos, não há nenhuma.

A Decisão

O Event Store é um repositório que persiste todos os eventos de domínio (§Cap II) como fatos imutáveis, em ordem. Um evento, uma vez registrado, nunca é alterado nem apagado — ele é o registro definitivo de algo que aconteceu. Esse repositório é a fonte de verdade dos fatos: a auditoria, as integrações e a camada de IA/analytics todas derivam da mesma sequência de eventos, em vez de cada uma reconstruir o histórico de sua própria fonte. Com uma única verdade sobre o que aconteceu, as divergências desaparecem — todos contam a mesma história, porque todos leem o mesmo registro.

Persistir o fato de forma imutável

-- Os fatos: imutáveis, ordenados, a fonte de verdade.
CREATE TABLE event_store (
    sequencia    BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tenant_id    BIGINT      NOT NULL,
    tipo         TEXT        NOT NULL,        -- 'PedidoCriado'
    agregado     TEXT        NOT NULL,        -- 'pedido'
    agregado_id  BIGINT      NOT NULL,        -- 1001
    dados        JSONB       NOT NULL,        -- o fato em si
    ocorrido_em  TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- IMUTÁVEL: sem UPDATE, sem DELETE. Um fato registrado é definitivo.
REVOKE UPDATE, DELETE ON event_store FROM app_role;

// Só duas operações: registrar um fato e ler a sequência de fatos.
final class EventStore
{
    public function registrar(EventoDeDominio $evento): void
    {
        // Acrescenta o fato. Nunca atualiza nem remove — append-only.
        $this->conexao->inserir('event_store', [
            'tenant_id'   => $evento->tenantId(),
            'tipo'        => $evento->tipo(),
            'agregado'    => $evento->agregado(),
            'agregado_id' => $evento->agregadoId(),
            'dados'       => $evento->paraJson(),
        ]);
    }

    /** A sequência de fatos de um agregado — a verdade, em ordem. */
    public function fatosDe(string $agregado, int $id): array
    {
        return $this->conexao->buscar(
            "SELECT * FROM event_store
              WHERE agregado = :a AND agregado_id = :id
              ORDER BY sequencia",
            ['a' => $agregado, 'id' => $id],
        );
    }
}

A Verificação

final class EventStoreTest extends TestCase
{
    public function test_fatos_sao_lidos_na_ordem_em_que_ocorreram(): void
    {
        $this->store->registrar(new PedidoCriado(1001));
        $this->store->registrar(new PedidoAprovado(1001));

        $fatos = $this->store->fatosDe('pedido', 1001);

        // A ordem dos fatos é a verdade da história do agregado.
        $this->assertSame('PedidoCriado', $fatos[0]->tipo);
        $this->assertSame('PedidoAprovado', $fatos[1]->tipo);
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Uma plataforma madura acumula tabelas — facilmente cento e cinquenta. Elas nascem em momentos diferentes, descritas em documentos diferentes, por pessoas diferentes. Sem um mapa que as organize, esse conjunto vira um território desconhecido: o desenvolvedor que precisa de uma tabela para guardar certo tipo de dado não tem como saber se ela já existe, em que família, com que nome. Na dúvida, ele cria uma nova.

E a tabela duplicada é o início de uma incoerência cara. Agora há dois lugares guardando a mesma coisa, que divergem com o tempo: um é atualizado, o outro não; uma engine usa um, outra usa o outro. O que era para ser uma plataforma coesa fragmenta-se em ilhas de dados redundantes e contraditórios. O problema não é técnico — é de descoberta: sem saber o que existe, reinventa-se o que já estava lá.

A Decisão

O catálogo de tabelas-base é o mapa do território de dados. Ele agrupa as ~100-150 tabelas em famílias coerentes por responsabilidade: identidade (usuários, empresas, papéis), metamodelo (a descrição declarativa do Cap III), regras (o Business Rules Engine), fatos (o Event Store, o histórico), negócio (as tabelas específicas do domínio) e operação (jobs, integrações, observabilidade). Cada tabela tem, no catálogo, sua responsabilidade declarada — o que ela guarda e por quê. Antes de criar qualquer tabela, consulta-se o catálogo: a que você precisa talvez já exista, numa família que você não havia pensado em olhar. O catálogo transforma um amontoado em um mapa navegável.

O catálogo como documento navegável

-- O catálogo é, ele próprio, dado: cada tabela e sua família.
CREATE TABLE catalogo_tabela (
    nome           TEXT PRIMARY KEY,        -- 'core_users'
    familia        TEXT NOT NULL,           -- 'identidade'
    responsabilidade TEXT NOT NULL          -- 'usuários do sistema'
);

-- Antes de criar uma tabela, pergunta-se ao catálogo:
-- "já existe algo nesta família que guarda este dado?"
SELECT nome, responsabilidade FROM catalogo_tabela
WHERE familia = 'identidade';

// O catálogo pode até barrar a criação de tabela duplicada.
final class VerificadorDeCatalogo
{
    public function avisarSeSimilarExiste(string $familia, string $proposito): array
    {
        // Busca tabelas da mesma família com propósito parecido.
        $candidatas = $this->catalogo->daFamilia($familia);

        // Retorna as que talvez já atendam — evita a reinvenção.
        return array_filter(
            $candidatas,
            fn($t) => $this->pareceAtender($t, $proposito),
        );
    }
}

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

Operação e análise são atividades de natureza oposta, e querem coisas opostas do banco de dados. A operação (OLTP — processamento transacional) é feita de muitas escritas e leituras pequenas e rápidas: criar um pedido, atualizar um cadastro, buscar um cliente. Ela vive de latência baixa. A análise (OLAP — processamento analítico) é o oposto: poucas consultas, mas que varrem milhões de linhas para somar, agrupar e cruzar — um dashboard de BI, um relatório com drill down. Ela vive de vazão.

O perigo é concreto e comum: deixar a análise pesada rodar no mesmo banco da operação. Uma única consulta de BI que varre milhões de linhas para montar um painel consome a máquina inteira — e, enquanto roda, as transações do dia a dia travam. O cliente que tentava salvar um pedido espera; a operação inteira engasga porque alguém pediu um relatório. Quando os clientes começarem a querer BI pesado, a operação será a vítima. Operação e análise, na mesma máquina, são inimigas.

A Decisão

A plataforma separa fisicamente os dois mundos. O OLTP — a operação transacional — vive no PostgreSQL, otimizado para muitas transações pequenas e rápidas, onde a latência baixa é tudo. O OLAP — a análise — vive num banco colunar, ClickHouse ou DuckDB, projetado para varrer e agregar enormes volumes com eficiência que um banco operacional jamais teria. Os fatos fluem do OLTP para o OLAP (alimentados pelo Event Store, §4.4), mas as duas cargas nunca competem pela mesma máquina. O relatório mais brutal, a consulta de BI mais pesada, rodam no banco analítico — e a operação do dia a dia segue intocada, porque vive em outro lugar.

Cada carga no banco que a serve

-- OLTP: a operação. Transações pequenas, rápidas, latência baixa.
-- PostgreSQL brilha aqui: ACID, índices, escritas concorrentes.
BEGIN;
  INSERT INTO pedido (tenant_id, cliente_id, valor)
  VALUES (7, 42, 1500.00);

  UPDATE cliente SET updated_at = now()
  WHERE id = 42 AND tenant_id = 7;
COMMIT;
-- Milissegundos. É o que o dia a dia precisa.

-- OLAP: a análise. Varre milhões de linhas, agrega, cruza.
-- Banco COLUNAR (ClickHouse/DuckDB): feito para isto.
SELECT
    toStartOfMonth(ocorrido_em) AS mes,
    count()                     AS pedidos,
    sum(valor)                  AS faturamento,
    avg(valor)                  AS ticket_medio
FROM fatos_pedido             -- milhões de linhas
WHERE tenant_id = 7
GROUP BY mes
ORDER BY mes;
-- No banco colunar: segundos. No operacional: travaria tudo.

Os fatos fluem do operacional para o analítico

# Os fatos do Event Store (§4.4) alimentam o banco analítico.
def sincronizar_fatos_para_olap(desde_sequencia: int) -> int:
    # Lê os novos fatos do OLTP (append-only, ordenados).
    fatos = event_store.ler_desde(desde_sequencia)

    # Carrega em lote no colunar — sem tocar a operação.
    olap.inserir_em_lote('fatos_pedido', fatos)

    # A análise vive de uma cópia dos fatos, não da máquina operacional.
    return fatos[-1].sequencia if fatos else desde_sequencia

Estudo de Caso

Incidente Real

Decisão Arquitetural

Antipadrões

Exercício

O Problema

A identidade visual de um sistema — suas cores, seus espaçamentos, seus cantos arredondados, suas fontes — é variação por natureza. Ela muda entre temas, entre marcas, entre um modo claro e um escuro. Mas quando esses valores estão cravados diretamente em cada componente — um #1A1815 aqui, um 12px ali, repetidos centenas de vezes pelo código —, mudar a identidade visual vira uma operação impossível: é preciso caçar cada ocorrência, em cada arquivo, sem garantia de tê-las encontrado todas.

Essa é exatamente a armadilha que o Capítulo I diagnosticou, agora na camada visual: tratar variação como se fosse código fixo. Uma plataforma que serve múltiplas marcas, ou que precisa de um tema escuro, ou que tem um parceiro white-label, não pode depender de editar centenas de valores espalhados. A aparência precisa ser dado — editável num lugar, refletida em todo o sistema.

A Decisão

Os design tokens são a aplicação da tese metadado/código (Cap III) à camada visual. Cada decisão de aparência — a cor primária, o raio de borda padrão, a escala de espaçamento, a família tipográfica — é definida uma vez como um token nomeado. Os componentes nunca usam valores literais; eles referenciam os tokens. Assim, a aparência inteira do sistema passa a viver num conjunto de tokens, e trocá-la é trocar esses valores num só lugar. Um tema escuro é um conjunto de tokens; uma marca white-label é outro. O código dos componentes permanece idêntico — só os tokens que ele referencia mudam.

Os tokens como fonte da aparência

/* A variação visual definida UMA vez, como dado. */
:root {
  /* cores */
  --cor-primaria: #1A1815;
  --cor-acento: #C8452F;
  /* espaçamento e forma */
  --espaco-base: 8px;
  --raio-borda: 12px;
  /* tipografia */
  --fonte-titulo: 'Outfit', sans-serif;
}

/* Um TEMA é só outro conjunto de tokens — sem tocar componentes. */
[data-tema="parceiro-wl"] {
  --cor-primaria: #7A2E8F;   /* marca do parceiro */
  --cor-acento: #C8452F;
}

/* O componente REFERENCIA tokens. Nunca valores literais. */
.botao-primario {
  /* errado seria: background: #1A1815; (valor cravado) */
  background: var(--cor-primaria);
  border-radius: var(--raio-borda);
  padding: var(--espaco-base) calc(var(--espaco-base) * 2);
  font-family: var(--fonte-titulo);
}
/* Trocar --cor-primaria muda ESTE e TODOS os componentes de uma vez. */

A Verificação

final class TokensDeComponenteTest extends TestCase
{
    public function test_componentes_nao_usam_valores_literais(): void
    {
        // Varre o CSS dos componentes em busca de cores cravadas.
        $violacoes = $this->buscarCoresLiteraisEm('componentes/');

        // Nenhum componente pode ter um #hex no lugar de um token.
        $this->assertSame([], $violacoes,
            'Componentes com cor literal em vez de token: ' . implode(', ', $violacoes));
    }

    public function test_troca_de_tema_muda_a_cor_primaria(): void
    {
        // O mesmo componente, dois temas, cores diferentes — sem mudar código.
        $this->assertNotEquals(
            $this->corPrimariaNoTema('padrao'),
            $this->corPrimariaNoTema('parceiro-wl'),
        );
    }
}