@maestro-ai/cli 1.0.0

package/content/prompts/apis/design-api-rest.md

@@ -0,0 +1,303 @@
+# Prompt: Design de API REST
+
+> **Quando usar**: Fase de arquitetura, antes de implementar endpoints
+> **Especialista**: [Arquitetura de Software](../../02-especialistas/Especialista%20em%20Arquitetura%20de%20Software.md)
+> **Nível**: Médio
+
+---
+
+## Fluxo de Contexto
+
+Antes de usar este prompt, tenha em mãos:
+- `docs/CONTEXTO.md` - Entendimento do projeto
+- `docs/02-requisitos/requisitos.md` - Requisitos funcionais
+- `docs/04-modelo/modelo-dominio.md` - Entidades do sistema
+
+Após gerar, salve o resultado em:
+- `docs/06-api/api-design.md`
+- `docs/06-api/openapi.yaml` (especificação)
+
+---
+
+## Prompt Completo
+
+```text
+Atue como arquiteto de APIs especializado em REST e OpenAPI.
+
+## Contexto do Projeto
+
+[COLE O CONTEÚDO DE docs/CONTEXTO.md]
+
+## Requisitos Funcionais
+
+[COLE RFs DE docs/02-requisitos/requisitos.md]
+
+## Modelo de Domínio
+
+[COLE ENTIDADES DE docs/04-modelo/modelo-dominio.md]
+
+## Configurações
+
+Versionamento: [URL path: /v1 | Header: X-API-Version | Query: ?version=1]
+Autenticação: [JWT Bearer | API Key | OAuth 2.0 | Session]
+Formato: [JSON | JSON:API | HAL]
+Base URL: [https://api.exemplo.com]
+
+---
+
+## Sua Missão
+
+Projete uma API REST completa seguindo boas práticas:
+
+### 1. Recursos e Endpoints
+
+Para cada recurso (baseado nas entidades):
+
+**Recurso: /recursos**
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | /recursos | Listar (paginado) | Sim/Não |
+| GET | /recursos/:id | Obter por ID | Sim/Não |
+| POST | /recursos | Criar | Sim/Não |
+| PUT | /recursos/:id | Atualizar completo | Sim/Não |
+| PATCH | /recursos/:id | Atualizar parcial | Sim/Não |
+| DELETE | /recursos/:id | Remover | Sim/Não |
+
+### 2. Padrões de Nomenclatura
+
+- Recursos no plural: /users, /orders
+- Kebab-case para multi-palavras: /order-items
+- IDs como path parameter: /users/:id
+- Relacionamentos: /users/:id/orders
+- Ações especiais: POST /orders/:id/cancel
+
+### 3. Query Parameters
+
+Padronize:
+- **Paginação**: page, limit (ou cursor)
+- **Ordenação**: sort=field:asc,field2:desc
+- **Filtros**: filter[field]=value
+- **Campos**: fields=id,name,email
+- **Expands**: include=orders,profile
+
+### 4. Request/Response Schemas
+
+Para cada endpoint principal, defina:
+
+**Request Body (POST/PUT)**
+```json
+{
+  "campo1": "tipo",
+  "campo2": "tipo"
+}
+```
+
+**Response Body (Sucesso)**
+```json
+{
+  "data": { ... },
+  "meta": { ... }
+}
+```
+
+**Response Body (Lista)**
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### 5. HTTP Status Codes
+
+| Código | Quando Usar |
+|--------|-------------|
+| 200 | Sucesso (GET, PUT, PATCH) |
+| 201 | Criado (POST) |
+| 204 | Sem conteúdo (DELETE) |
+| 400 | Request inválido |
+| 401 | Não autenticado |
+| 403 | Não autorizado |
+| 404 | Não encontrado |
+| 409 | Conflito (duplicação) |
+| 422 | Erro de validação |
+| 429 | Rate limit exceeded |
+| 500 | Erro interno |
+
+### 6. Formato de Erros
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Mensagem amigável",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email inválido"
+      }
+    ],
+    "traceId": "abc-123"
+  }
+}
+```
+
+### 7. Headers
+
+**Request Headers**
+- Authorization: Bearer {token}
+- Content-Type: application/json
+- Accept: application/json
+- X-Request-ID: {uuid}
+
+**Response Headers**
+- X-Request-ID: {uuid}
+- X-RateLimit-Limit: 100
+- X-RateLimit-Remaining: 95
+- X-RateLimit-Reset: timestamp
+
+### 8. Versionamento
+
+Estratégia escolhida e como deprecar versões antigas.
+
+### 9. Segurança
+
+- Rate limiting por endpoint
+- Validação de input
+- CORS configuration
+
+### 10. OpenAPI Specification
+
+Gere a especificação OpenAPI 3.0 em YAML para os endpoints principais.
+```
+
+---
+
+## Exemplo de Uso
+
+```text
+Atue como arquiteto de APIs especializado em REST e OpenAPI.
+
+## Contexto do Projeto
+
+Sistema de agendamento para salões de beleza.
+
+## Requisitos Funcionais
+
+- RF-001: Listar horários disponíveis
+- RF-002: Criar agendamento
+- RF-003: Cancelar agendamento
+- RF-004: Listar agendamentos do dia
+
+## Modelo de Domínio
+
+- Cliente (id, nome, telefone, email)
+- Servico (id, nome, duracao, preco)
+- Profissional (id, nome, especialidades)
+- Agendamento (id, clienteId, servicoId, profissionalId, dataHora, status)
+
+## Configurações
+
+Versionamento: URL path /v1
+Autenticação: JWT Bearer (admin) / Público (cliente agendando)
+Formato: JSON
+Base URL: https://api.salao.com
+```
+
+---
+
+## Resposta Esperada
+
+### Recursos
+
+**Recurso: /agendamentos**
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | /v1/agendamentos | Listar (admin) | JWT |
+| GET | /v1/agendamentos/:id | Obter | JWT |
+| POST | /v1/agendamentos | Criar | Público |
+| DELETE | /v1/agendamentos/:id | Cancelar | JWT ou Token |
+
+**Recurso: /disponibilidade**
+
+| Método | Endpoint | Descrição | Auth |
+|--------|----------|-----------|------|
+| GET | /v1/profissionais/:id/disponibilidade | Horários livres | Público |
+
+### Request/Response
+
+**POST /v1/agendamentos**
+
+Request:
+```json
+{
+  "profissionalId": "uuid",
+  "servicoId": "uuid",
+  "dataHora": "2024-01-15T14:00:00Z",
+  "cliente": {
+    "nome": "Maria Silva",
+    "telefone": "11999998888"
+  }
+}
+```
+
+Response (201):
+```json
+{
+  "data": {
+    "id": "uuid",
+    "status": "CONFIRMADO",
+    "dataHora": "2024-01-15T14:00:00Z",
+    "profissional": { "id": "uuid", "nome": "Ana" },
+    "servico": { "id": "uuid", "nome": "Corte", "duracao": 30 }
+  }
+}
+```
+
+### OpenAPI (Resumo)
+
+```yaml
+openapi: 3.0.3
+info:
+  title: API Salão de Beleza
+  version: 1.0.0
+  
+paths:
+  /v1/agendamentos:
+    post:
+      summary: Criar agendamento
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CriarAgendamento'
+      responses:
+        '201':
+          description: Agendamento criado
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgendamentoResponse'
+```
+
+---
+
+## Checklist Pós-Geração
+
+- [ ] Todos os recursos mapeados das entidades
+- [ ] Verbos HTTP corretos para cada ação
+- [ ] Paginação padronizada
+- [ ] Formato de erro consistente
+- [ ] Status codes documentados
+- [ ] Headers de request/response definidos
+- [ ] Rate limiting especificado
+- [ ] Versionamento definido
+- [ ] OpenAPI spec gerada
+- [ ] Salvar em `docs/06-api/api-design.md`

package/content/prompts/apis/idempotencia.md

@@ -0,0 +1,254 @@
+# Prompt: Idempotência em APIs
+
+> **Prioridade**: 🔴 CRÍTICA  
+> **Aplicável a**: Projetos Nível 2 (Médio) e Nível 3 (Complexo)
+
+---
+
+## Por que é Crítico?
+
+Sem idempotência, operações podem ser duplicadas em caso de:
+- Retry automático de clientes
+- Timeout de rede seguido de retry manual
+- Falha de conexão após processamento
+
+**Consequências em produção:**
+- Cobranças duplicadas em pagamentos
+- Pedidos duplicados em e-commerce
+- Criação de recursos duplicados
+- Inconsistência de dados
+
+---
+
+## Conceito
+
+> **Idempotência**: Uma operação que pode ser executada múltiplas vezes produzindo o mesmo resultado.
+
+| Método HTTP | Naturalmente Idempotente? |
+|-------------|---------------------------|
+| GET | ✅ Sim |
+| PUT | ✅ Sim (substitui recurso) |
+| DELETE | ✅ Sim (recurso já deletado = ok) |
+| POST | ❌ **Não** - Requer implementação |
+| PATCH | ⚠️ Depende da implementação |
+
+---
+
+## Prompt Base
+
+```text
+Atue como arquiteto de APIs com foco em resiliência.
+
+Preciso implementar idempotência no seguinte endpoint:
+- Método: [POST/PATCH]
+- Rota: [ex: /api/v1/payments]
+- Operação: [ex: criar pagamento, processar pedido]
+
+Stack: [ex: Node.js + Express + Redis / Java + Spring + PostgreSQL]
+
+Gere uma implementação completa com:
+
+1. **Estratégia de Idempotency Key**
+   - Via header `Idempotency-Key`
+   - Formato: UUID v4
+   - Validação de formato
+
+2. **Armazenamento de Estado**
+   - Schema para Redis ou tabela em banco
+   - Estados: PROCESSING, COMPLETED, FAILED
+   - TTL apropriado (mínimo 24h)
+
+3. **Fluxo de Processamento**
+   - Verificar se key já existe
+   - Se PROCESSING: retornar 409 Conflict
+   - Se COMPLETED: retornar resposta cacheada
+   - Se nova: processar e armazenar resultado
+
+4. **Middleware/Interceptor**
+   - Código reutilizável para decorar endpoints
+
+5. **Testes**
+   - Request normal (200)
+   - Request duplicada (resposta cached)
+   - Request durante processamento (409)
+   - Request com key inválida (400)
+
+Inclua:
+- Código completo e comentado
+- Schema de armazenamento
+- Exemplos de uso
+```
+
+---
+
+## Padrões Obrigatórios
+
+### Header Padrão
+
+```http
+POST /api/v1/orders HTTP/1.1
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Content-Type: application/json
+
+{
+  "product_id": "123",
+  "quantity": 1
+}
+```
+
+### Respostas
+
+| Cenário | Status Code | Body |
+|---------|-------------|------|
+| Primeira execução com sucesso | 200/201 | Recurso criado |
+| Key já processada com sucesso | 200/201 | Resposta cacheada (idêntica) |
+| Key em processamento | 409 Conflict | `{"error": "Request already in progress"}` |
+| Key inválida/ausente | 400 Bad Request | `{"error": "Invalid Idempotency-Key"}` |
+| Primeira execução com erro | 4xx/5xx | Erro original (cachear também) |
+
+### Schema Redis
+
+```plaintext
+Key: idempotency:{idempotency_key}
+TTL: 86400 (24 horas)
+Value: {
+  "status": "PROCESSING" | "COMPLETED" | "FAILED",
+  "response_code": 201,
+  "response_body": {...},
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### Schema SQL (Alternativa)
+
+```sql
+CREATE TABLE idempotency_keys (
+    key VARCHAR(36) PRIMARY KEY,
+    status VARCHAR(20) NOT NULL DEFAULT 'PROCESSING',
+    response_code INT,
+    response_body JSONB,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_idempotency_created ON idempotency_keys(created_at);
+
+-- Job para limpar keys antigas (> 24h)
+DELETE FROM idempotency_keys WHERE created_at < NOW() - INTERVAL '24 hours';
+```
+
+---
+
+## Exemplo de Implementação (Node.js + Express + Redis)
+
+```typescript
+import { Redis } from 'ioredis';
+import { Request, Response, NextFunction } from 'express';
+
+const redis = new Redis();
+const TTL_SECONDS = 86400; // 24 horas
+
+interface IdempotencyRecord {
+  status: 'PROCESSING' | 'COMPLETED' | 'FAILED';
+  responseCode?: number;
+  responseBody?: any;
+  createdAt: string;
+}
+
+export function idempotent() {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const idempotencyKey = req.headers['idempotency-key'] as string;
+
+    // Validar presença e formato
+    if (!idempotencyKey) {
+      return res.status(400).json({ error: 'Idempotency-Key header required' });
+    }
+
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(idempotencyKey)) {
+      return res.status(400).json({ error: 'Invalid Idempotency-Key format' });
+    }
+
+    const redisKey = `idempotency:${idempotencyKey}`;
+
+    // Verificar se já existe
+    const existing = await redis.get(redisKey);
+    
+    if (existing) {
+      const record: IdempotencyRecord = JSON.parse(existing);
+      
+      if (record.status === 'PROCESSING') {
+        return res.status(409).json({ 
+          error: 'Request already in progress',
+          idempotency_key: idempotencyKey
+        });
+      }
+      
+      // Retornar resposta cacheada
+      return res.status(record.responseCode!).json(record.responseBody);
+    }
+
+    // Marcar como em processamento
+    const processingRecord: IdempotencyRecord = {
+      status: 'PROCESSING',
+      createdAt: new Date().toISOString()
+    };
+    
+    await redis.setex(redisKey, TTL_SECONDS, JSON.stringify(processingRecord));
+
+    // Interceptar a resposta para cachear
+    const originalJson = res.json.bind(res);
+    res.json = (body: any) => {
+      const completedRecord: IdempotencyRecord = {
+        status: res.statusCode >= 400 ? 'FAILED' : 'COMPLETED',
+        responseCode: res.statusCode,
+        responseBody: body,
+        createdAt: processingRecord.createdAt
+      };
+      
+      redis.setex(redisKey, TTL_SECONDS, JSON.stringify(completedRecord));
+      
+      return originalJson(body);
+    };
+
+    next();
+  };
+}
+
+// Uso no router
+app.post('/api/v1/orders', idempotent(), createOrderHandler);
+```
+
+---
+
+## Prompt para Revisar Idempotência Existente
+
+```text
+Tenho este endpoint que realiza operações que não podem ser duplicadas:
+[COLE O CÓDIGO DO ENDPOINT]
+
+Analise:
+1. O endpoint é idempotente? Se não, por quê?
+2. Quais operações podem causar problemas se duplicadas?
+3. Sugira como adicionar idempotência mantendo compatibilidade.
+```
+
+---
+
+## Checklist de Implementação
+
+- [ ] Header `Idempotency-Key` definido
+- [ ] Validação de formato (UUID v4)
+- [ ] Armazenamento de estado configurado (Redis/DB)
+- [ ] TTL mínimo de 24 horas
+- [ ] Tratamento de requisição em andamento (409)
+- [ ] Cache de resposta para requests duplicadas
+- [ ] Testes automatizados cobrindo todos os cenários
+- [ ] Documentação na OpenAPI/Swagger
+
+---
+
+## Referências
+
+- [Stripe - Idempotent Requests](https://stripe.com/docs/api/idempotent_requests)
+- [Idempotency Patterns](https://blog.bitsrc.io/design-patterns-for-microservices-idempotency/)