aplimoramento de agent

DOCUMENTACAO/templates/contrato-api.md.template

@@ -0,0 +1,72 @@
+---
+type: template
+name: contrato-api
+description: Template canônico para especificação de contratos de API e schemas Zod
+updatedAt: "2026-09-02"
+---
+
+<!--
+DESTINO CANÔNICO NO PROJETO:
+- Rota Dinâmica de IA (Pilar 5): servido dinamicamente pelo backend em /llm.md ou <modulo-caminho>llm.md
+- Wiki de Desenvolvimento (Pilar 4): ../../wiki/dev/<modulo-id>/contratos/{servico}.contrato.md
+-->
+
+# Contrato de API — [Nome do Serviço / Endpoint]
+
+- **Módulo:** `<modulo-id>`
+- **Base URL:** `<modulo-caminho>api/v1/`
+- **Autenticação:** Bearer Token JWT (Header `Authorization: Bearer <token>`)
+
+---
+
+## Tabela de Endpoints
+
+| Método | Endpoint | Descrição | Permissão Requerida |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/recurso` | Listar recursos com paginação | Leitura |
+| `POST` | `/recurso` | Criar novo registro | Escrita |
+| `GET` | `/recurso/:id` | Obter detalhes por ID | Leitura |
+| `PUT` | `/recurso/:id` | Atualizar registro completo | Escrita |
+| `DELETE` | `/recurso/:id` | Excluir logicamente o registro | Admin |
+
+---
+
+## Detalhamento: `POST /recurso`
+
+### Request Body (Schema Zod: `zRecursoCriar`)
+```typescript
+import { z } from "zod";
+
+export const zRecursoCriar = z.object({
+  nome: z.string().min(3).max(100),
+  tipo: z.enum(["TIPO_A", "TIPO_B"]),
+  ativo: z.boolean().default(true),
+});
+
+export type RecursoCriar = z.infer<typeof zRecursoCriar>;
+```
+
+### Exemplo de Payload (JSON)
+```json
+{
+  "nome": "Monitoramento Trimestral",
+  "tipo": "TIPO_A",
+  "ativo": true
+}
+```
+
+### Resposta de Sucesso (`201 Created`)
+```json
+{
+  "id": "uuid-v4-gerado",
+  "nome": "Monitoramento Trimestral",
+  "tipo": "TIPO_A",
+  "ativo": true,
+  "criadoEm": "2026-09-02T10:00:00Z"
+}
+```
+
+### Respostas de Erro
+- `400 Bad Request`: Payload não satisfaz o schema Zod (retorna array `erros: [{ campo, mensagem }]`).
+- `401 Unauthorized`: Token ausente ou expirado.
+- `403 Forbidden`: Usuário sem perfil de acesso para esta operação.