ENGENHARIA / UM CASO DO INÍCIO AO ENCERRAMENTO / FABRÍCIO CASTRO
A tela confirmou.
Mas a regra foi respeitada?
Dois gestores aprovam a mesma compra quase ao mesmo tempo. A interface parece funcionar — mas o estado, a política e o ERP concordam? Este estudo acompanha uma necessidade da primeira conversa à retirada segura, distinguindo conhecimento herdado de prova específica para cada projeto.
01 / UM CENÁRIO DIDÁTICO, NÃO UM CLIENTE
O botão é a solução pedida. Qual é o problema real?
Uma empresa registra compras por mensagens e planilhas. O pedido inicial é criar uma tela para aprovar. Ainda não sabemos se o caminho adequado é reorganizar o processo, configurar o ERP ou desenvolver um módulo. O cenário é fictício; não representa projeto implantado, métrica real, código executado ou experiência específica de cliente. Sua função é ensinar a investigar hipóteses plausíveis.
Uma decisão não deve ser duplicada.
Duas pessoas veem um pedido pendente. Ambas tentam aprová-lo. O sistema deve preservar a política e evitar efeitos divergentes. Precisamos compreender consequências de negócio antes de desenhar o banco.
Nem sempre desenvolver é necessário.
Comparar processo manual corrigido, configuração do ERP e construção própria, considerando valor, custo, prazo, segurança, manutenção e quem será responsável. A conclusão pode ser não construir.
02 / O PROJETO DEPENDE DE PESSOAS
Quem conhece a regra que não podemos violar?
O solicitante conhece o trabalho; gestores conhecem alçadas; financeiro conhece o efeito contábil; suporte conhece reclamações; segurança e operações conhecem acesso e recuperação. Em um projeto individual, funções se acumulam, mas a pessoa que escreve código não adquire automaticamente essas competências.
PERGUNTAS DE DESCOBERTA
Escutar, confrontar e registrar.
Entrevistas, observação do processo e revisão das exceções devem ser validadas pelos responsáveis; uma conversa isolada não equivale a acordo.
USUÁRIOS Quem solicita, consulta e contesta?
GESTÃO Qual limite exige outra alçada e quem decide?
FINANCEIRO Há reserva, centro de custo ou segregação?
SEGURANÇA Pode alguém aprovar o próprio pedido?
INTEGRAÇÃO Como reconhecer confirmação do ERP?
SUPORTE Quem investiga e reconcilia divergências?
03 / REGRAS QUE PODEMOS VERIFICAR
Da primeira conversa ao teste do mesmo requisito.
A rastreabilidade abaixo é um conjunto de identificadores didáticos. O limite financeiro, o prazo de retenção e as metas de qualidade dependem do negócio e da lei aplicável — não devem ser inventados para preencher documentação.
UMA NECESSIDADE, VÁRIAS PROVAS
Cada elo precisa ser demonstrável.
Um RF ou ADR escrito não é prova de código funcionando; um build verde não comprova comportamento de produção.
NEED-01 Evitar aprovações contraditórias.
RF-01 Registrar decisão e ator autorizado.
RN-01 Exigir segunda alçada quando a política determinar.
RNF-01 Impedir acesso entre organizações.
ADR-01 Escolher fronteiras e persistência por contexto.
API-01 Transição versionada e idempotente.
T-01–T-10 Casos de acesso, concorrência, integração e retirada.
REL-01 Commit, CI, release e smoke pelo mesmo SHA.
INC-01 Impacto, diagnóstico e prevenção.
RET-01 Exportação, retenção e encerramento.
Aceite proposto: dada uma compra pendente, duas tentativas simultâneas sobre a mesma versão não podem confirmar duas transições do mesmo estágio. Os efeitos de auditoria e integração não podem ser duplicados; isso ainda exige teste real.
04 / ADR-01 — NÃO COPIAR ARQUITETURAS
Monólito ou serviços? Quais forças justificam a escolha?
Uma solução modular pode preservar transação local e simplificar o primeiro incremento. Serviços podem atender fronteiras e equipes independentes, mas trazem latência, duplicações e novos riscos operacionais. Parnas e o debate Fowler/Tilkov ajudam a formular perguntas; não oferecem a resposta automática para esta organização.
Menor coordenação distribuída.
Módulos de Solicitação, Política e Integração com contratos definidos, testes e banco transacional. Observar acoplamento, mudança das regras e limites de carga antes de escolher.
Autonomia tem um preço técnico.
Exige contratos de rede, consistência entre serviços, versões, rastreabilidade e operação especializada. Só se justifica quando os benefícios superam os riscos e custos reais.
Decisão didática: investigar uma arquitetura modular primeiro, mantendo critérios explícitos para revisão. Estudar alternativas e ADRs. Nenhuma dessas arquiteturas foi implantada neste exemplo.
05 / CONCORRÊNCIA E INTEGRIDADE
Duas aprovações em paralelo. Quem altera o estado?
O servidor obtém a organização e o ator do contexto autenticado, valida política e alçada e exige a versão esperada. O SQL PostgreSQL abaixo é ilustrativo, não migração nem consulta executada. Uma linha modificada indica uma transição do estado esperado; zero linhas requer investigar conflito ou acesso, sem revelar dados de outro tenant.
UPDATE purchase_request
SET status = CASE
WHEN $4::boolean THEN 'WAITING_SECOND_APPROVAL'
ELSE 'APPROVED'
END, version = version + 1
WHERE tenant_id = $1 AND id = $2
AND status = 'PENDING' AND version = $3
RETURNING id, tenant_id, status, version;Contrato: $1 = tenant autorizado, $2 = pedido, $3 = versão anterior, $4 = exigência de segunda alçada calculada no servidor. A política precisa ser coerente com a mesma transação; a validação de identidade nunca pode depender de um ID informado pelo cliente. A atualização, a auditoria e a outbox devem ocorrer na mesma transação ou ser revertidas. A segunda aprovação requer outro estágio e segregação de funções.
Mesmo estágio, uma única transição.
Executar transações simultâneas num PostgreSQL descartável e verificar estado, auditoria e respostas de conflito. A teoria do controle de versão não substitui essa execução.
Uma pessoa não ocupa dois papéis incompatíveis.
Quando a política exigir segunda aprovação, verificar ator distinto, regra atualizada, versionamento e efeitos de revogação de acesso.
06 / A REDE TAMBÉM FALHA
O ERP respondeu com timeout. Reenviar é seguro?
Talvez o ERP tenha concluído o processamento e a resposta tenha se perdido. Repetir sem verificar pode duplicar uma compra. A aplicação precisa de identificação estável de intenção, confirmação ou reconciliação no destino e estados explícitos para desfechos indeterminados.
Uma chave corresponde a uma intenção.
Associar chave ao tenant, ator, operação e conteúdo. Tentativa repetida pode recuperar o resultado registrado; conteúdo diferente com a mesma chave deve ser rejeitado. Definir retenção e limites do contrato.
A fila não promete entrega única.
Registrar estado e intenção de publicar atomicamente. A entrega de eventos ainda pode ser repetida, exigindo consumidores idempotentes, logs e reconciliação. Diferenciar gravação local, mensagem entregue e efeito no ERP.
07 / PLANO DE TESTES ADVERSARIAIS
Testar o caminho feliz não é testar os riscos.
Os dez testes a seguir são uma especificação didática, não resultados executados. Testes unitários validam regras puras; integração confirma transações e contratos; E2E, acessibilidade e revisão humana validam a jornada completa.
- 01T-01 — Decisão válida
Alçada, estado, trilha e responsável corretos.
- 02T-02 — Tenant diferente
Negar acesso sem revelar dados de terceiros.
- 03T-03 — Aprovação concorrente
Uma transição válida por estágio/versão.
- 04T-04 — Dupla alçada
Atores distintos quando exigido pela política.
- 05T-05 — Chave repetida
Mesma intenção coerente; carga divergente rejeitada.
- 06T-06 — Timeout após commit externo
Reconciliar antes de repetir efeito.
- 07T-07 — Evento duplicado
Consumo idempotente e correlação.
- 08T-08 — Erro acessível
Teclado, foco, mensagens e conexão instável.
- 09T-09 — Restauração
Confrontar RPO/RTO acordados, sem prometer perda zero.
- 10T-10 — Retirada
Exportação, retenção legal, revogação e evidência.
PROVAS NO REPOSITÓRIO / CÓDIGO DIDÁTICO VERIFICÁVEL
Os padrões estão no código. Quais limites continuam abertos?
O Atlas já contém módulos TypeScript e arquivos de teste correspondentes. Eles são artefatos reais do repositório, diferentes da simulação integral descrita acima. A presença dos testes não significa que a aprovação concorrente tenha sido executada em PostgreSQL, nem que exista integração operacional com um ERP.
Valores, estado e transição de solicitação.
O módulo de compras calcula valores em centavos, recusa dados inválidos e emite um evento ao submeter um rascunho. Seus testes verificam invariantes e acesso por organização. Não implementa aprovação de segunda alçada.
Strategy e State para autorização didática.
Outro módulo compara estratégias de alçada e transições permitidas. Os testes exercitam valores, papéis e eventos inválidos. Essa lógica pura não autentica usuários, grava decisões nem executa transações.
Um caso de uso com repositório substituível.
A aplicação usa um contrato de persistência, com adaptador em memória para testar conflito de versão, isolamento e evento quando a gravação é aceita. O fake não demonstra bloqueio ou isolamento transacional do PostgreSQL.
Retries, leases e confirmação ambígua.
Um relay didático separa publicação, falha, nova tentativa e ACK desconhecido. Os testes exploram duplicidade potencial e mensagens de outro tenant. Não há broker real ou atomicidade de banco comprovada por esse módulo.
Procedência: os links apontam para arquivos reais fixados no commit 5abc0492. Os testes são parte do código-fonte, não uma certificação da execução no SHA atual. A integração PostgreSQL, a aprovação em duas etapas e o fluxo completo de T-01 a T-10 seguem como hipóteses a implementar e comprovar.
08 / DEVOPS, RELEASE E OPERAÇÃO
Build verde não é produção. Publicação não é qualidade automática.
O release deve conectar requisitos a commits, testes realizados no SHA exato, migration, artefato, ambiente e smoke HTTP, com possibilidade de reversão e monitoramento. Um check verde de commit anterior não valida uma revisão nova.
REL-01 / GATES
Evidências que faltariam obter.
Itens propostos, não homologação desse cenário: considerar criticidade, segurança e capacidade operacional.
ESCOPO RF/RN/ADR e PR aprovadas.
TESTES Node, Jest, PostgreSQL real, E2E, acesso e concorrência.
SEGURANÇA Segredos, dependências e autorizações.
DADOS Migrações ensaiadas e recuperação.
RELEASE SHA, destino, aprovação e versão.
OPERAÇÃO Smoke, alertas, traces, suporte e runbook.
09 / INC-01 — FALHAR COM RESPONSABILIDADE
Houve duplicidade. Como investigar sem procurar culpados?
Incidente simulado: o ERP processou duas tentativas. A equipe deve conter novos envios, identificar impacto, preservar auditoria, comparar IDs e estado remoto e decidir reconciliação ou compensação. Não afirmar restauração sem prova nem supor que toda perda é recuperável.
Reconstruir o que realmente aconteceu.
Correlacionar API, banco, outbox, filas e ERP por identificadores, com observabilidade e privacidade. Separar hipóteses de fatos.
Uma lição precisa mudar testes ou controles.
Registrar causas contribuintes, ação, responsável, prazo e cenário capaz de prevenir reincidência. “Ter mais atenção” não é uma medida verificável.
10 / O DOMÍNIO NÃO PARA DE MUDAR
A solução anterior funcionou. Ela ainda é adequada?
Novas alçadas, integrações, volume e restrições alteram o projeto. Antes de migrar para serviços ou reescrever o banco, revisitar ADR, modelo de domínio, riscos, custos, contratos e capacidade da equipe. Migrações precisam preservar consumidores existentes e permitir transição progressiva.
Expandir, migrar e só então remover.
Introduzir compatibilidade quando necessário, acompanhar erros, mover consumidores gradualmente e evitar remoção prematura de dados e contratos.
Persistência não é insistência cega.
Comparar valor, custo total, continuidade, restrições e aprendizagem. Uma opção pode se tornar inviável, exigindo revisão ou abandono.
11 / RET-01 — ENCERRAR TAMBÉM É ENGENHARIA
Desligar a aplicação não encerra a responsabilidade.
Comunicar pessoas afetadas, exportar informações, confirmar integridade, respeitar retenção legal, revogar integrações, segredos e acessos e comprovar o encerramento. Aposentar um sistema não é apagar dados arbitrariamente; as obrigações dependem de cada organização e jurisdição.
- 01Decisão e aviso
Responsáveis, prazo, alternativas e critérios de parada.
- 02Exportação e migração
Formatos, reconciliação e validação pelo destino.
- 03Retenção e privacidade
Regras verificadas com responsáveis jurídicos.
- 04Revogar e desligar
Tokens, webhooks, jobs, usuários e consumidores órfãos.
- 05Evidência final
Comprovantes de verificação, pendências e responsáveis.
12 / APRENDER COM FONTES E EXEMPLOS
Qual conhecimento usamos? O que ainda depende de prova?
A norma do ciclo de vida, a documentação PostgreSQL e as práticas Google SRE ajudam a formular critérios. Não comprovam que este caso hipotético foi implantado ou testado.
ISO/IEC/IEEE 12207:2026
Concepção, desenvolvimento, operação, manutenção e retirada.
Consultar ISOPostgreSQL — UPDATE RETURNING
Atualização condicional e valores retornados de linhas modificadas.
Documentação oficialGoogle SRE — Postmortem Culture
Aprender com falhas e ações corretivas verificáveis.
Consultar Google SRECONHECIMENTO NÃO É RECEITA
Mesmo problema. Decisões diferentes conforme o contexto.
Requisitos, arquitetura e operação são conhecimentos conectados, mas nenhum padrão substitui investigação, pessoas e teste.