Da organização ao requisito verificável

Imagine que a administração de um shopping peça: “faça um aplicativo para abrir e acompanhar ordens de serviço”. Parece uma encomenda de telas. Porém, uma lâmpada queimada, um vazamento e um cheiro de queimado não podem seguir exatamente o mesmo caminho. Um lojista quer resposta rápida; o técnico precisa de localização e risco; o supervisor controla custo; o estoque vive no ERP; a segurança pode exigir contenção imediata; a auditoria precisa saber quem decidiu. Se o processo atual contém dúvidas, uma tela pode apenas fazê-las circular mais depressa.

O caminho profissional começa no resultado organizacional e termina em evidência:

A organização vem antes do software

Uma organização reúne pessoas, responsabilidades, recursos, incentivos e objetivos. Um processo transforma uma entrada ou evento em algum resultado. O processo inclui trabalho, espera, decisão, exceção e retrabalho — não apenas os cliques visíveis na tela.

Dado é uma representação registrada, como OS-1042, 2026-08-09T14:30 ou ALTA. Informação é o significado que alguém obtém ao interpretar dados em um contexto: “a OS-1042 está há 90 minutos parada apesar de ter prioridade alta”. Sem significado, origem e momento, o número não sustenta uma decisão.

Um Sistema de Informação (SI) é sociotécnico: pessoas, processos, dados, tecnologia e governança interagem. O aplicativo é um componente; o banco armazena representações; a API oferece uma interface; o ERP coordena capacidades empresariais. Nenhum deles, isoladamente, é o processo de manutenção. A norma ISO/IEC/IEEE 29148 situa requisitos ao longo do ciclo de vida de sistemas e software; o SWEBOK mantém requisitos como área de conhecimento própria. São referências para estruturar o trabalho, não substitutos para observar a organização real.

Desenhe o “como é” antes do “como deveria ser”

O fluxo atual (as is) pode ser:

Pergunte quanto tempo cada etapa trabalha e quanto tempo espera; quem recebe exceções; quais atalhos existem no plantão; e o que acontece quando ERP, rede ou pessoa responsável não está disponível. A BPMN, padronizada pela OMG, fornece uma notação para processos. Para começar, caixas, setas e decisões bem nomeadas bastam; não use a notação como decoração nem finja precisão que ainda não existe.

Triangule a descoberta. Entrevista revela linguagem e intenção; observação mostra a prática; documentos mostram regras declaradas; dados mostram volume e frequência; um protótipo testa entendimento. Separe no caderno:

Classe	Exemplo	Como confirmar
Fato observado	técnico copia o número para uma planilha	observar uma amostra
Regra declarada	custo acima de R$ 5.000 exige supervisor	política e dono da regra
Hipótese	a cópia causa atraso	dados ou experimento
Decisão	ERP será dono do saldo de estoque	responsáveis e registro de decisão

Contradição é descoberta. Se o procedimento diz uma coisa e o plantão faz outra, investigue restrição e consequência em vez de culpar a pessoa.

Quem participa e quem é afetado

Stakeholder é qualquer pessoa ou grupo que influencia ou sofre efeitos do sistema: lojista, equipe de segurança, jurídico, auditoria e administração. Ator interage com o processo ou sistema: solicitante, técnico, supervisor ou o próprio ERP. Uma mesma pessoa pode ocupar mais de um papel, mas as permissões devem ser avaliadas pelo papel e pelo contexto.

Perguntar apenas à chefia produz um mapa incompleto. O técnico conhece a falta de sinal no subsolo; o operador noturno conhece a exceção; a pessoa que usa teclado ou leitor de tela conhece uma barreira invisível no desenho. A WCAG 2.2 formula critérios testáveis e independentes de tecnologia para acessibilidade web. Privacidade também nasce nos requisitos: finalidade, dados mínimos, acesso, retenção e descarte devem ser definidos; o NIST Privacy Framework trata privacidade como risco organizacional, não como caixa marcada depois do deploy.

Regra, requisito e solução não são sinônimos

Considere: “despesas de manutenção acima de R$ 5.000 precisam da aprovação de um supervisor”.

• Regra de negócio: a exigência de aprovação, com dono, fonte e vigência.
• Requisito funcional: “o sistema deve permitir que um supervisor aprove uma OS pendente da própria unidade e deve negar os demais papéis”.
• Critério de aceite: exemplos observáveis do que deve acontecer ou não acontecer.
• Solução: botão na interface, endpoint POST /ordens/{id}/aprovacao, tabela ou fila. Pode mudar sem mudar a regra.
• Restrição: “a integração deve usar a API oficial do ERP” ou “dados permanecem na região contratada”.

Pedir “um botão de aprovação” salta diretamente para uma solução. Falta perguntar quem aprova, em qual estado, sobre qual unidade, com qual evidência, o que ocorre com duas aprovações e o que fazer se o ERP falhar.

Uma história de usuário é lembrete para conversa, não prova. Complete-a com cenários:

Cenário: supervisor da unidade aprova uma ordem pendente
  Dado que a OS 1042 está PENDENTE_APROVACAO na unidade Norte
  E Ana é supervisora ativa da unidade Norte
  Quando Ana aprovar a OS 1042
  Então o estado deve mudar para APROVADA
  E a auditoria deve registrar ator, instante, ordem e versão

Cenário: técnico não pode aprovar
  Dado que a OS 1042 está PENDENTE_APROVACAO
  E Bruno possui apenas o papel técnico
  Quando Bruno tentar aprová-la
  Então a API deve responder 403
  E o estado e a versão da OS devem permanecer iguais

O segundo cenário é tão importante quanto o primeiro: esconder o botão melhora a experiência, mas a API deve ser a autoridade da autorização.

Estado impede combinações impossíveis

Um evento informa algo que aconteceu: FalhaRelatada, OrdemAprovada. Um comando pede uma mudança: AprovarOrdem. O estado resume em que condição válida a entidade se encontra. Para a OS:

ABERTA → EM_TRIAGEM → ATRIBUÍDA → EM_EXECUÇÃO → CONCLUÍDA
                            ↘ AGUARDANDO_PEÇA ↗       ↓
                                      PENDENTE_APROVAÇÃO → APROVADA

Cada transição tem pré-condições. PENDENTE_APROVAÇÃO → APROVADA é válida para supervisor autorizado; APROVADA → EM_EXECUÇÃO normalmente não é. Vários booleanos, como concluida=true, cancelada=true e aprovada=false, criam combinações sem sentido. Uma máquina de estados pequena torna o erro explícito e testável. O histórico pode registrar transições sem exigir que todo o sistema adote event sourcing.

A integração precisa de dono e comportamento de falha

No exemplo didático, o aplicativo de manutenção é a fonte de verdade da OS operacional; o ERP é a fonte de verdade do saldo de estoque e do lançamento financeiro. Fonte de verdade é a autoridade definida para decidir qual valor prevalece. Uma réplica ou cache não se torna segunda autoridade só porque possui uma cópia.

O contrato deve dizer quais dados atravessam a fronteira, versão, autenticação, erros, timeout, paginação quando aplicável e responsável. A OpenAPI Specification padroniza uma descrição independente de linguagem para APIs HTTP, compreensível por pessoas e ferramentas. Ela descreve a interface; não decide sozinha a regra de negócio.

Falhas são parte do requisito. Se a resposta do ERP some, repetir a chamada não pode baixar a mesma peça duas vezes. Uma chave de idempotência permite reconhecer a repetição da mesma intenção. A reconciliação compara registros posteriormente e encontra pendências ou divergências. “Tentar novamente” sem identidade estável pode multiplicar o efeito; “usar transação” não cria atomicidade mágica entre dois sistemas independentes.

Qualidade precisa de número e contexto

Requisito funcional descreve uma capacidade. Requisito de qualidade descreve quão bem o produto deve se comportar sob condições definidas. A ISO/IEC 25010:2023 oferece um modelo com nove características de qualidade para especificar e avaliar produtos de TIC; a lista ajuda a lembrar dimensões, mas cada projeto ainda precisa escolher medidas relevantes.

“A busca deve ser rápida” não tem oráculo. Transforme-a em cenário com estímulo, ambiente, resposta e medida:

Em homologação equivalente à produção, com 100 usuários concorrentes e consulta retornando até 100 ordens, 95% das respostas da busca filtrada devem terminar em menos de 800 ms, medidas no limite da API durante 15 minutos.

Agora sabemos carga, operação, ambiente, percentil, limiar e janela. A média poderia esconder uma cauda lenta; o percentil 95 indica que 95% ficaram no limiar. O número não deve ser inventado pelo desenvolvedor: resulta da necessidade operacional, baseline, custo e risco.

Outros cenários verificáveis:

• autorização: técnico tenta aprovar; servidor nega, estado não muda e auditoria registra a tentativa;
• disponibilidade: ERP fica fora por 30 minutos; a aprovação local fica pendente e reconcilia uma única vez após o retorno;
• acessibilidade: uma pessoa usando apenas teclado abre a OS, identifica erros e envia sem armadilha de foco;
• recuperação: restauração em ambiente isolado prova os objetivos acordados de perda e tempo.

Critério de aceite é um pequeno experimento

Para cada requisito, procure pelo menos quatro famílias:

1. positivo: usuário correto, estado correto, resultado esperado;
2. negativo: papel ou unidade incorretos, nenhuma alteração;
3. limite: exatamente R$ 5.000 versus R$ 5.000,01;
4. falha: timeout do ERP, repetição, recuperação e diagnóstico.

“Funciona” não basta. Declare entrada, estado inicial, ação, saída, efeitos persistidos e evidência. Critérios não precisam prescrever a implementação interna; precisam eliminar interpretações incompatíveis do comportamento importante.

Rastreabilidade responde “por quê?” e “como sabemos?”

Use IDs e links em vez de copiar texto entre ferramentas:

necessidade → requisito → regra/risco → decisão → ticket → teste → telemetria

Necessidade	Requisito	Risco	Teste	Telemetria
impedir aprovação indevida	FR-01	RISK-AUTH	TEST-AUTH-NEG	approval_denied_total
não duplicar baixa	IR-01	RISK-DUP	TEST-ERP-RETRY	outbox_pending e duplicatas
busca sustenta triagem	QR-01	RISK-LAT	TEST-PERF-P95	latência p95

Se a equipe afirma “somente supervisor aprova”, mas não existe teste negativo nem sinal em produção, a cadeia está incompleta. Rastreabilidade útil permite analisar o impacto de uma mudança e retirar artefatos sem propósito; não é uma planilha ornamental.

Procedimento: da observação à prova

1. Escreva o resultado organizacional e como será observado.
2. Mapeie atores e stakeholders, inclusive turnos, pessoas afetadas e sistemas externos.
3. Observe o fluxo atual, espera, exceções, atalhos e retrabalho.
4. Registre fatos, regras, hipóteses e decisões separadamente.
5. Nomeie eventos, estados, transições válidas e invariantes.
6. Defina o dono de cada dado e o comportamento quando integrações falharem.
7. Escreva requisitos funcionais e cenários de qualidade mensuráveis.
8. Produza critérios positivos, negativos, de limite e de falha.
9. Ligue cada risco importante a teste e telemetria.
10. Valide o mapa com papéis divergentes e implemente uma fatia vertical mínima.

Diagnóstico de especificações fracas

Sintoma	Pergunta de diagnóstico	Correção
“rápido”, “seguro”, “intuitivo”	qual medida, condição e limiar?	cenário de qualidade
dois saldos discordam	qual sistema decide?	uma fonte de verdade e reconciliação
regra sem responsável	quem pode explicá-la e alterá-la?	dono, fonte e vigência
botão oculto como segurança	a API nega a mesma ação?	teste de autorização no servidor
estados impossíveis	quais transições são legais?	máquina de estados e teste negativo
retry duplica efeito	a repetição tem identidade?	idempotência e evidência de deduplicação
requisito sem prova	onde falharia antes da entrega e em produção?	teste e telemetria rastreados

Critérios de domínio e recuperação ativa

Você domina este capítulo quando consegue explicar por que digitalizar um formulário não garante melhorar o SI; transformar “rápido” no cenário p95 completo; e resolver saldos divergentes escolhendo fonte de verdade, mínimo replicado, idempotência e reconciliação.

Sem consultar, reconstrua a cadeia necessidade → requisito → risco → teste → telemetria. Depois responda: quem é ator e quem é stakeholder na aprovação? Qual regra existiria mesmo sem software? Qual é a diferença entre o ERP possuir uma cópia da OS e ser sua fonte de verdade?

Exercícios

1. Desenhe o processo de manutenção incluindo duas filas e três exceções reais.
2. Reescreva “o sistema deve ser fácil e rápido” com tarefa, participantes, carga, medida e limiar.
3. Proponha um estado inválido e o teste que o impede.
4. Para indisponibilidade do ERP, defina chave idempotente, fila, reconciliação e sinais operacionais.
5. Faça um pré-mortem: “em seis meses o sistema causou um incidente”. Inclua incentivo para encerrar OS cedo, acesso entre unidades e duplicação de peças. Transforme cada risco em controle e prova.

O próximo caderno executa esse raciocínio. Ele contém um pacote defeituoso de propósito, um validador didático, uma fatia vertical de aprovação e uma integração falsa que falha antes de reconciliar.