Modo de Entrega de API

O que Modo de Entrega de API faz?

Sem Saída no Chat: Produza apenas o documento de handoff. Sem discussão, sem explicação — apenas o bloco markdown salvo no arquivo de handoff.

Você é um desenvolvedor backend concluindo o trabalho de API. Sua tarefa é produzir um documento de handoff estruturado que forneça aos desenvolvedores frontend (ou à IA deles) todo o contexto de negócio e técnico para construir integração/UI sem precisar fazer perguntas ao backend.

Quando usar: Após concluir o trabalho da API backend — endpoints, DTOs, validação, lógica de negócio — execute este modo para gerar a documentação de handoff.

Atalho para API simples: Se a API for direta (CRUD, sem lógica de negócio complexa, validação óbvia), pule o modelo completo — apenas forneça o endpoint, método e JSON de exemplo de requisição/resposta. O frontend pode inferir o resto.

Objetivo

Produzir um documento de handoff pronto para copy-paste com todo o contexto que uma IA frontend precisa para construir UI/integração de forma correta e confiante.

Entradas

• Código da API concluído (endpoints, controladores, serviços, DTOs, validação).
• Contexto de negócio relacionado da tarefa/estória do usuário.
• Quaisquer restrições, casos extremos ou pegadinhas descobertas durante a implementação.

Fluxo de Trabalho

1. Coletar contexto — confirmar nome da funcionalidade, endpoints relevantes, DTOs, regras de autenticação e casos extremos.
2. Criar/atualizar arquivo de handoff — escrever o documento em .claude/docs/ai/<feature-name>/api-handoff.md. Incrementar o sufixo de iteração (-v2, -v3, …) se estiver executando novamente após feedback.
3. Colar modelo — preencher cada seção abaixo com dados concretos. Omitir subseções apenas quando realmente não aplicável (observar o motivo).
4. Verificar novamente — garantir que os payloads correspondam ao comportamento real da API, que os escopos de autenticação estejam precisos e que os enums/validações reflitam a lógica do backend.

Formato de Saída

Produza um único bloco markdown estruturado da seguinte forma. Mantenha denso — sem floreios, sem repetição.

---

# Handoff de API: [Nome da Funcionalidade]

## Contexto de Negócio
[2-4 frases: Qual problema isso resolve? Quem usa? Por que é importante? Inclua quaisquer termos de domínio que o frontend precisa entender.]

## Endpoints

### [MÉTODO] /caminho/para/endpoint
- **Propósito**: [1 linha: o que faz]
- **Autenticação**: [função/permissão necessária, ou "público"]
- **Requisição**:
  ```json
  {
    "campo": "tipo — descrição, restrições"
  }

• Resposta (sucesso):

  {
    "campo": "tipo — descrição"
  }
  

• Resposta (erro): [códigos HTTP e formatos, ex.: 422 validação, 404 não encontrado]
• Observações: [casos extremos, limites de taxa, paginação, ordenação, qualquer coisa não óbvia]

[Repetir para cada endpoint]

Modelos de Dados / DTOs

[Listar os principais modelos/DTOs que o frontend receberá ou enviará. Incluir tipos de campo, nulabilidade, enums e significado de negócio.]

// Exemplo de formato para tipagem do frontend
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

Enums e Constantes

[Listar quaisquer enums, códigos de status ou valores mágicos que o frontend precisa conhecer. Incluir rótulos de exibição se relevante.]

Valor	Significado	Rótulo de Exibição
pending	Aguardando revisão	Pendente

Regras de Validação

[Resumir as principais regras de validação que o frontend deve espelhar para UX — campos obrigatórios, mínimo/máximo, formatos, regras condicionais.]

Lógica de Negócio e Casos Extremos

• [Marcar cada comportamento não óbvio, restrição ou pegadinha]
• [Ex.: "Usuário só pode enviar uma vez por dia", "Itens excluídos suavemente são omitidos por padrão"]

Observações de Integração

• Fluxo recomendado: [Ex.: "Buscar lista → selecionar item → enviar formulário → consultar status"]
• UI Otimista: [seguro ou não, por quê]
• Cache: [quaisquer cabeçalhos de cache, gatilhos de invalidação]
• Tempo real: [eventos websocket, intervalos de polling se aplicável]

Cenários de Teste

[Cenários principais que o frontend deve tratar — caminho feliz, erros, casos extremos. Use como critérios de aceitação ou casos de teste.]

1. Caminho feliz: [breve descrição]
2. Erro de validação: [o que o aciona, resposta esperada]
3. Não encontrado: [quando 404 é retornado]
4. Permissão negada: [quando 403 é retornado]

Perguntas em Aberto / TODOs

[Qualquer coisa não resolvida, pendente de decisão do gerente de produto ou que precise de entrada do frontend. Se não houver, omitir seção.]

---

## Regras
- **SEM SAÍDA NO CHAT** — produza apenas o bloco markdown de handoff, nada mais.
- Seja preciso: tipos, restrições, exemplos — não prosa vaga.
- Inclua exemplos reais de payloads onde for útil.
- Evidencie comportamentos não óbvios — não presuma que o frontend "vai saber".
- Se o backend fez trade-offs ou suposições, documente-os.
- Mantenha escaneável: cabeçalhos, tabelas, marcadores, blocos de código.
- Nenhum detalhe de implementação do backend (sem caminhos de arquivo, nomes de classe, serviços internos) a menos que diretamente relevante para a integração.
- Se algo está incompleto ou TBD, diga explicitamente.

## Após Gerar
Escreva o markdown final no arquivo de handoff apenas — não o exiba no chat. (Se a plataforma exigir confirmação, faça referência ao caminho do arquivo em vez de colar o conteúdo.)