# Casos de uso ## Propósito Uma página de caso de uso transforma uma entrada do catálogo de casos de uso em uma configuração que alguém consegue construir e verificar. A entrada dá à página o título, o cenário, os produtos e as arquiteturas de referência que ela pode construir. A página nunca inventa um caso de uso próprio. O catálogo é mantido pela Azion. Quem precisa de uma entrada, ou encontra uma errada, pede antes de escrever a página. O pedido vai pelos templates de issue do repositório, ou pelo dono do catálogo dentro da Azion. O leitor chega com uma situação, não com uma tarefa: uma loja que fica lenta durante uma promoção, um evento ao vivo que precisa alcançar mais uma região. Um caso de uso é uma especificação, não um artigo. Ele carrega em uma página tudo de que o implementador precisa: os produtos que o cenário exige, a arquitetura, a configuração, as verificações e as métricas que mostram o resultado funcionando. Esse implementador muitas vezes é um agente, então a página é escrita para ser executada, não para ser lida. Casos de uso vivem na seção Guias, nunca dentro de um produto, na área da solução da sua entrada no catálogo. O rótulo da área é o nome da solução. ## Quando usar **Reconheça um caso de uso por:** - Um título que é o nome de um caso de uso do catálogo, sem alteração, traduzido na página em português: uma frase verbal no imperativo que nomeia um workload, sem nomes de produto. - Um leitor que chegou com uma situação de negócio, e não com uma tarefa. - Uma tabela de requisitos ligando cada necessidade de negócio ao produto que a atende. - Um resultado que continua mensurável depois que a configuração funciona. - Uma especificação completa o bastante para um agente executar sem fazer perguntas. **Continua sendo um caso de uso quando:** - Configura quatro coisas ou menos. Mais de quatro significa que a entrada é larga demais para uma página. - Aponta para o procedimento genérico em vez de repeti-lo aqui. - É publicado sem demo, porque nenhuma existe. Nunca descreva uma demo que não roda. **Escreva outra coisa quando:** - Não há nada a configurar. A página explica um design, então escreva uma [página de arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura/). - A configuração é uma tarefa só. Isso é um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/). - O catálogo não tem entrada para ele, e o objetivo não precisa de uma situação de cliente. Isso é um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). Uma entrada faz da página um caso de uso, qualquer que seja a redação do objetivo. - O leitor não tem cenário, só o produto. Isso é um [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/). ## Registro Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: preciso, claro, objetivo, sóbrio. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras. ## Estrutura **Componentes obrigatórios** - **Cenário**: três a cinco frases tiradas do Cenário da entrada do catálogo. Elas nomeiam o ator, o workload e a situação em que ele está, o que esta página configura e o resultado mensurável. Seguidas de uma linha declarando o que o caso de uso não cobre, a exclusão da própria entrada. - **Pré-requisitos**: uma seção `## Pré-requisitos`, cada item um link ou um comando de uma linha quando existe um. - **Produtos exigidos**: a tabela de requisitos. Uma linha por requisito, nomeando a necessidade técnica, o produto que a atende e a página que a documenta. A coluna Produto contém os produtos da entrada do catálogo. Uma dependência que a documentação do produto confirma e a entrada omite também entra na tabela, e a lacuna é informada ao catálogo. A necessidade técnica nomeia o recurso da plataforma que o leitor configura. - **Arquitetura de referência**: uma seção `## Arquitetura de referência`. Ela abre nomeando qual das arquiteturas de referência da entrada esta página constrói, e depois traz um diagrama em `mermaid` e um `### Fluxo de dados` numerado. As outras arquiteturas de referência da entrada viram links para páginas de arquitetura, quando existem. - **Configuração**: uma seção `## Configure ` por requisito cuja configuração é específica deste caso de uso, no máximo quatro. Cada uma tem um procedimento que termina com sua frase de resultado. Um requisito atendido por um procedimento genérico não ganha seção. A tabela de requisitos aponta o guia que o documenta, e a checagem fica na seção de verificação. - **Verificação**: uma seção `## Verifique a configuração` com uma checagem por requisito e o resultado esperado. - **Medição de resultados**: uma seção `## Medindo resultados` nomeando as métricas que mostram a configuração funcionando, e onde ler cada uma. - **Best practices**: uma seção `## Best practices` com as recomendações e o raciocínio por trás de cada uma. - **Próximos passos**: um fechamento `## Próximos passos`, um `DocCardGroup` com um card por destino: o título, o link e o motivo como texto do card. **Componentes opcionais** - **Demo**: uma seção `## Demo` apontando para um exemplo em execução, um template ou um repositório. Omita quando não existir; nunca descreva uma demo que não roda. As seções mantêm essa ordem. O que governa a página é a proporção, não o comprimento. Um caso de uso é mais longo do que os outros tipos por definição: ele é uma especificação, e quem implementa a partir dele não pode preencher uma lacuna perguntando. O peso da página fica nas seções que quem implementa executa: - **As seções de configuração sustentam a página.** No máximo quatro, e juntas elas são a maior parte dela. Se não são, a página está descrevendo um cenário em vez de construir um. - **Cenário, pré-requisitos, demo e próximos passos ficam curtos.** Cada um orienta e encaminha. Um cenário que passa de dois parágrafos está vendendo. - **Arquitetura de referência, verificação, medição e best practices ficam entre os dois.** Cada uma carrega conteúdo real — um diagrama, uma verificação que roda, um sinal a observar — e nenhuma delas é lugar para expandir. O limite que mantém um caso de uso honesto é o teto de quatro seções em `## Configure`, não um comprimento. Comprimir nunca é a solução, porque o que se comprime é o diagrama, o output do comando e o valor concreto — as partes sem as quais quem implementa não consegue seguir. ## Template Copie o template e substitua cada ``: ````mdx import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' ## Pré-requisitos - --- ## Produtos exigidos | Requisito | Necessidade técnica | Produto | Documentado em | | --- | --- | --- | --- | | | | | [](/caminho/) | --- ## Arquitetura de referência ```mermaid flowchart LR ``` ### Fluxo de dados 1. 2. 3. --- ## Configure Para : 1. 2. ## Configure <...> --- ## Verifique a configuração - --- ## Demo - [](/caminho/) - . --- ## Medindo resultados | Métrica | Onde ler | Como é quando funciona | | --- | --- | --- | | | | | --- ## Best practices - ****: . --- ## Próximos passos ```` ## Regras - **Escreva uma especificação, não um artigo.** Todo valor é concreto, todo comando roda, e nenhum passo diz "dependendo da sua configuração". O leitor pode ser um agente, e um agente não resolve uma ambiguidade perguntando. - **Mostre o output depois de cada comando.** O leitor vê como o sucesso se parece antes que o próximo passo dependa dele. A regra está em [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/). - **Reduza o cenário a uma configuração construível.** Declare assim: `Um