Template — fluxo E2E¶
Escopo: backend e infraestrutura associada, conforme a governança; consumidores aparecem somente como atores externos.
Modelo editorial para etapa futura. Não descreve um fluxo implementado específico.
Objetivo, atores e pré-condições¶
Operação, atores, estado anterior, tenant/owner, dependências e permissões. Registrar repositórios/commits e ambiente.
Entrada¶
Começar na fronteira HTTP do backend. Para administração, identificar o endpoint exposto pelo BFF. Para APIs públicas consumidas diretamente por sistemas externos, identificar a entrada real pelo Ingress/Broker, sem pressupor passagem pelo BFF. Descrever somente o contrato recebido do consumidor externo. Informar o ambiente e a fonte da configuração de borda. Não presumir controller, política ou mecanismo corporativo a partir do ambiente local; se ausentes, declarar não confirmados. Experimentos de exposição não são pressupostos dos fluxos oficiais.
Endpoint inicial completo, método, path/query, headers obrigatórios/opcionais, autenticação, conteúdo e resposta inicial esperada. Exemplo JSON extraído de DTO/contrato/teste real, com fonte e sanitização. Se não houver body JSON, explicar o formato real.
Passos e contratos¶
Numerar cada passo: entrada → validação → transformação → chamada/consulta → resultado. Referenciar classe e método. Incluir uma tabela de campo de origem, campo de destino, regra e fonte para transformações relevantes.
Documentar ordem de validação, short-circuit, regras de negócio e cada contrato interno: método/path/headers/tenant, payload e erro. Não atribuir validação ao BFF se ela pertence ao serviço de domínio.
Persistência e estados intermediários¶
Consultas/filtros, alterações, ownership, transações, estados e marcos observáveis. Referenciar modelos canônicos sem duplicar seu catálogo.
Processamento assíncrono¶
Quando aplicável: exchange/fila/routing key, envelope, correlação, publicação, consumo, ack, retry/DLQ, deduplicação e retomada. Separar resposta HTTP inicial, conclusão da operação e ativação/publicação, se forem marcos distintos. Descrever como o cliente acompanha o resultado.
Respostas e erros¶
Status e payload finais; status/código de domínio/exceção por falha; traduções entre serviços; efeitos parciais. Exemplos devem ser reais e sanitizados. Não assumir 202 para todo fluxo assíncrono.
Retry, idempotência e compensação¶
Quem pode repetir, chave/escopo/prazo, efeitos repetíveis, locks/leases, timeout após efeito remoto, compensações e intervenção manual. Marcar ausência de garantia explicitamente.
Diagrama de sequência Mermaid¶
Criar sequenceDiagram com os mesmos participantes e passos documentados, incluindo resposta inicial e processamento assíncrono em blocos distintos. Usar alt/opt somente para alternativas comprovadas; não inserir exemplos fictícios de endpoints.
Evidências e validação¶
Relacionar endpoints, DTOs, classes/métodos, mensagens, repositórios e testes por commit. Registrar limitações funcionais e resultados de testes tecnicamente relevantes. Incertezas da análise ficam no relatório final da tarefa.