How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

gerdor-de-doc - Prompt - OpenSmartRoute

Name: gerdor-de-doc
Author: alexandre-henrique-rp

Prompt file imported from alexandre-henrique-rp/iselftoken (.windsurf/workflows/gerdor-de-doc.md). Copyright stays with the author.

Prompt para Documentação Automática de Rotas e APIs

Objetivo

Analisar estrutura de páginas e APIs para criar/atualizar documentação completa das rotas, verificando requisições, restrições e fluxos de dados.

Etapa 1: Análise da Estrutura de Rotas

1.1 Mapeamento de Páginas

Escanear diretórios:

@src/app/(protected)/ - Rotas autenticadas
@src/app/(public)/ - Rotas públicas
@src/app/api/ - Endpoints da API

Para cada page.tsx encontrada:

Identificar rota baseada na estrutura de pastas
Analisar imports e componentes utilizados
Mapear props e parâmetros recebidos
Identificar hooks e context utilizados
Verificar chamadas para APIs (fetch, axios, etc.)

1.2 Análise de Componentes

Para cada componente referenciado:

Localizar arquivo do componente
Analisar props e interface TypeScript
Identificar estados e efeitos
Mapear eventos e handlers
Verificar validações e restrições
Documentar funcionalidades embarcadas

1.3 Rastreamento de APIs

Para cada chamada de API identificada:

Verificar se é API interna (/api/) ou externa
Localizar endpoint correspondente em @src/app/api/
Analisar método HTTP (GET, POST, PUT, DELETE)
Mapear request body e query parameters
Documentar response structure
Identificar middlewares e validações

Etapa 2: Análise de APIs Internas

2.1 Estrutura de Endpoints

Para cada arquivo em @src/app/api/:

Identificar rota da API
Analisar exports (GET, POST, PUT, DELETE)
Mapear request/response schemas
Verificar autenticação/autorização
Documentar validações de entrada
Identificar conexões com banco de dados

2.2 Fluxo de Dados

Rastrear:

Models/schemas utilizados
Conexões com banco de dados
Middlewares aplicados
Tratamento de erros
Logs e monitoring
Rate limiting

Etapa 3: Verificação de Documentação Existente

3.1 Comparação com `@doc/documentação/`

Processo:

# Listar documentações existentes
ls @doc/documentação/*.md

# Para cada documentação:
# 1. Extrair nome da rota do arquivo
# 2. Verificar se página correspondente existe
# 3. Se não existir → marcar para exclusão
# 4. Se existir → comparar com análise atual

3.2 Ações por Cenário

Documentação existe + Página existe: Atualizar documentação
Documentação existe + Página não existe: Excluir documentação
Documentação não existe + Página existe: Criar nova documentação
Mudanças na API: Atualizar requests/responses

Etapa 4: Template de Documentação

4.1 Estrutura Padrão

# **nome:** [Nome da Página]
# **rota:** [/caminho/da/rota]

## **descrição:**
- [Descrição funcional da página]

## **tipo de acesso:**
- [público/protegido/admin]

## **funcionalidades embarcadas:**
- [Lista de funcionalidades]
- [Componentes principais]
- [Ações disponíveis]

## **restrições:**
- [Regras de acesso]
- [Validações]
- [Limitações]

## **dependências:**
- [Context/Providers utilizados]
- [Hooks customizados]
- [Bibliotecas externas]

## **APIs utilizadas:**

### **API Interna:**
- **Endpoint:** `[METHOD] /api/endpoint`
- **Autenticação:** [sim/não]
- **Request:**
```json
{
  "campo": "tipo (descrição)"
}

Response:

{
  "status": "success",
  "data": {}
}

API Externa:

Serviço: [Nome do serviço]
Endpoint: [URL completa]
Autenticação: [tipo]

Navegação:

Links de entrada: [páginas que redirecionam para esta]
Links de saída: [páginas para onde esta redireciona]
Parâmetros de rota: [se dinâmica]

Estados e Dados:

Estados locais: [useState, useReducer]
Estados globais: [Context, Zustand, Redux]
Cache: [React Query, SWR]
Persistência: [localStorage, sessionStorage]

Validações:

Formulários: [schema de validação]
Inputs: [regras específicas]
Permissões: [baseado em roles]

Tratamento de Erros:

Errors boundaries: [componentes]
Try/catch: [async operations]
Fallbacks: [estados de erro]

Performance:

Loading states: [skeletons, spinners]
Lazy loading: [componentes, imagens]
Memoization: [useMemo, useCallback]

SEO/Meta:

Title: [título da página]
Description: [meta description]
Keywords: [palavras-chave]


## Etapa 5: Análise de Código Automatizada

### 5.1 Padrões de Identificação
**Buscar por:**
```regex
# Chamadas de API
fetch\(['"`]([^'"`]+)['"`]
axios\.(get|post|put|delete)\(['"`]([^'"`]+)['"`]
api\.(get|post|put|delete)\(['"`]([^'"`]+)['"`]

# Hooks de autenticação
useAuth|useUser|useSession

# Redirects e navegação
router\.push|redirect|navigate

# Validações
yup|zod|joi|validate

# Estados globais
useContext|useStore|useSelector

5.2 Extração de Metadados

Para cada página:

Extrair imports e suas origens
Identificar props interface (TypeScript)
Mapear exports e re-exports
Documentar comment blocks existentes
Verificar metadata Next.js

Etapa 6: Automação e Validação

6.1 Script de Análise

// Pseudo-código para análise
const analyzeRoute = async (routePath) => {
  const pageFile = findPageFile(routePath);
  const components = extractComponents(pageFile);
  const apiCalls = extractApiCalls(pageFile, components);
  const restrictions = analyzeRestrictions(routePath);
  
  return {
    route: routePath,
    type: getRouteType(routePath), // public/protected
    components,
    apiCalls,
    restrictions,
    dependencies: extractDependencies(pageFile)
  };
};

6.2 Validação de Documentação

Verificar:

Todas as rotas têm documentação
Documentação órfã (sem página correspondente)
APIs documentadas existem
Schemas estão atualizados
Links internos funcionam

Etapa 7: Manutenção e Sincronização

7.1 Triggers para Atualização

Novos arquivos page.tsx criados
Modificações em APIs existentes
Mudanças em interfaces TypeScript
Alterações em middlewares
Updates em dependências

7.2 Processo de Sincronização

Scan incremental: Detectar mudanças desde última execução
Impact analysis: Identificar documentações afetadas
Auto-update: Atualizar documentações impactadas
Validation: Verificar consistência
Cleanup: Remover documentações órfãs

Etapa 8: Critérios de Qualidade

8.1 Completude

Todas as rotas documentadas
APIs mapeadas completamente
Restrições claramente definidas
Examples de request/response

8.2 Precisão

Schemas atualizados
Endpoints corretos
Tipos TypeScript consistentes
Links funcionais

8.3 Manutenibilidade

Processo automatizado
Documentação versionada
Sincronização contínua
Validação automática

Saída esperada: Documentação completa e atualizada de todas as rotas, com mapeamento preciso de APIs, restrições e fluxos de dados, mantida automaticamente em sincronia com o código.

# Prompt para Documentação Automática de Rotas e APIs ## Objetivo Analisar estrutura de páginas e APIs para criar/atualizar documentação completa das rotas, verificando requisições, restrições e fluxos de dados. ## Etapa 1: Análise da Estrutura de Rotas ### 1.1 Mapeamento de Páginas **Escanear diretórios:** - `@src/app/(protected)/` - Rotas autenticadas - `@src/app/(public)/` - Rotas públicas - `@src/app/api/` - Endpoints da API **Para cada `page.tsx` encontrada:** - Identificar rota baseada na estrutura de pastas - Analisar imports e componentes utilizados - Mapear props e parâmetros recebidos - Identificar hooks e context utilizados - Verificar chamadas para APIs (fetch, axios, etc.) ### 1.2 Análise de Componentes **Para cada componente referenciado:** - Localizar arquivo do componente - Analisar props e interface TypeScript - Identificar estados e efeitos - Mapear eventos e handlers - Verificar validações e restrições - Documentar funcionalidades embarcadas ### 1.3 Rastreamento de APIs **Para cada chamada de API identificada:** - Verificar se é API interna (`/api/`) ou externa - Localizar endpoint correspondente em `@src/app/api/` - Analisar método HTTP (GET, POST, PUT, DELETE) - Mapear request body e query parameters - Documentar response structure - Identificar middlewares e validações ## Etapa 2: Análise de APIs Internas ### 2.1 Estrutura de Endpoints **Para cada arquivo em `@src/app/api/`:** - Identificar rota da API - Analisar exports (GET, POST, PUT, DELETE) - Mapear request/response schemas - Verificar autenticação/autorização - Documentar validações de entrada - Identificar conexões com banco de dados ### 2.2 Fluxo de Dados **Rastrear:** - Models/schemas utilizados - Conexões com banco de dados - Middlewares aplicados - Tratamento de erros - Logs e monitoring - Rate limiting ## Etapa 3: Verificação de Documentação Existente ### 3.1 Comparação com `@doc/documentação/` **Processo:** ```bash # Listar documentações existentes ls @doc/documentação/*.md # Para cada documentação: # 1. Extrair nome da rota do arquivo # 2. Verificar se página correspondente existe # 3. Se não existir → marcar para exclusão # 4. Se existir → comparar com análise atual ``` ### 3.2 Ações por Cenário - **Documentação existe + Página existe:** Atualizar documentação - **Documentação existe + Página não existe:** Excluir documentação - **Documentação não existe + Página existe:** Criar nova documentação - **Mudanças na API:** Atualizar requests/responses ## Etapa 4: Template de Documentação ### 4.1 Estrutura Padrão ```markdown # **nome:** [Nome da Página] # **rota:** [/caminho/da/rota] ## **descrição:** - [Descrição funcional da página] ## **tipo de acesso:** - [público/protegido/admin] ## **funcionalidades embarcadas:** - [Lista de funcionalidades] - [Componentes principais] - [Ações disponíveis] ## **restrições:** - [Regras de acesso] - [Validações] - [Limitações] ## **dependências:** - [Context/Providers utilizados] - [Hooks customizados] - [Bibliotecas externas] ## **APIs utilizadas:** ### **API Interna:** - **Endpoint:** `[METHOD] /api/endpoint` - **Autenticação:** [sim/não] - **Request:** ```json { "campo": "tipo (descrição)" } ``` - **Response:** ```json { "status": "success", "data": {} } ``` ### **API Externa:** - **Serviço:** [Nome do serviço] - **Endpoint:** `[URL completa]` - **Autenticação:** [tipo] ## **Navegação:** - **Links de entrada:** [páginas que redirecionam para esta] - **Links de saída:** [páginas para onde esta redireciona] - **Parâmetros de rota:** [se dinâmica] ## **Estados e Dados:** - **Estados locais:** [useState, useReducer] - **Estados globais:** [Context, Zustand, Redux] - **Cache:** [React Query, SWR] - **Persistência:** [localStorage, sessionStorage] ## **Validações:** - **Formulários:** [schema de validação] - **Inputs:** [regras específicas] - **Permissões:** [baseado em roles] ## **Tratamento de Erros:** - **Errors boundaries:** [componentes] - **Try/catch:** [async operations] - **Fallbacks:** [estados de erro] ## **Performance:** - **Loading states:** [skeletons, spinners] - **Lazy loading:** [componentes, imagens] - **Memoization:** [useMemo, useCallback] ## **SEO/Meta:** - **Title:** [título da página] - **Description:** [meta description] - **Keywords:** [palavras-chave] ``` ## Etapa 5: Análise de Código Automatizada ### 5.1 Padrões de Identificação **Buscar por:** ```regex # Chamadas de API fetch\(['"`]([^'"`]+)['"`] axios\.(get|post|put|delete)\(['"`]([^'"`]+)['"`] api\.(get|post|put|delete)\(['"`]([^'"`]+)['"`] # Hooks de autenticação useAuth|useUser|useSession # Redirects e navegação router\.push|redirect|navigate # Validações yup|zod|joi|validate # Estados globais useContext|useStore|useSelector ``` ### 5.2 Extração de Metadados **Para cada página:** - Extrair imports e suas origens - Identificar props interface (TypeScript) - Mapear exports e re-exports - Documentar comment blocks existentes - Verificar metadata Next.js ## Etapa 6: Automação e Validação ### 6.1 Script de Análise ```javascript // Pseudo-código para análise const analyzeRoute = async (routePath) => { const pageFile = findPageFile(routePath); const components = extractComponents(pageFile); const apiCalls = extractApiCalls(pageFile, components); const restrictions = analyzeRestrictions(routePath); return { route: routePath, type: getRouteType(routePath), // public/protected components, apiCalls, restrictions, dependencies: extractDependencies(pageFile) }; }; ``` ### 6.2 Validação de Documentação **Verificar:** - Todas as rotas têm documentação - Documentação órfã (sem página correspondente) - APIs documentadas existem - Schemas estão atualizados - Links internos funcionam ## Etapa 7: Manutenção e Sincronização ### 7.1 Triggers para Atualização - Novos arquivos `page.tsx` criados - Modificações em APIs existentes - Mudanças em interfaces TypeScript - Alterações em middlewares - Updates em dependências ### 7.2 Processo de Sincronização 1. **Scan incremental:** Detectar mudanças desde última execução 2. **Impact analysis:** Identificar documentações afetadas 3. **Auto-update:** Atualizar documentações impactadas 4. **Validation:** Verificar consistência 5. **Cleanup:** Remover documentações órfãs ## Etapa 8: Critérios de Qualidade ### 8.1 Completude - [ ] Todas as rotas documentadas - [ ] APIs mapeadas completamente - [ ] Restrições claramente definidas - [ ] Examples de request/response ### 8.2 Precisão - [ ] Schemas atualizados - [ ] Endpoints corretos - [ ] Tipos TypeScript consistentes - [ ] Links funcionais ### 8.3 Manutenibilidade - [ ] Processo automatizado - [ ] Documentação versionada - [ ] Sincronização contínua - [ ] Validação automática --- **Saída esperada:** Documentação completa e atualizada de todas as rotas, com mapeamento preciso de APIs, restrições e fluxos de dados, mantida automaticamente em sincronia com o código.

{ "prompt": "# Prompt para Documentação Automática de Rotas e APIs\n\n## Objetivo\nAnalisar estrutura de páginas e APIs para criar/atualizar documentação completa das rotas, verificando requisições, restrições e fluxos de dados.\n\n## Etapa 1: Análise da Estrutura de Rotas\n\n### 1.1 Mapeamento de Páginas\n**Escanear diretórios:**\n- `@src/app/(protected)/` - Rotas autenticadas\n- `@src/app/(public)/` - Rotas públicas\n- `@src/app/api/` - Endpoints da API\n\n**Para cada `page.tsx` encontrada:**\n- Identificar rota baseada na estrutura de pastas\n- Analisar imports e componentes utilizados\n- Mapear props e parâmetros recebidos\n- Identificar hooks e context utilizados\n- Verificar chamadas para APIs (fetch, axios, etc.)\n\n### 1.2 Análise de Componentes\n**Para cada componente referenciado:**\n- Localizar arquivo do componente\n- Analisar props e interface TypeScript\n- Identificar estados e efeitos\n- Mapear eventos e handlers\n- Verificar validações e restrições\n- Documentar funcionalidades embarcadas\n\n### 1.3 Rastreamento de APIs\n**Para cada chamada de API identificada:**\n- Verificar se é API interna (`/api/`) ou externa\n- Localizar endpoint correspondente em `@src/app/api/`\n- Analisar método HTTP (GET, POST, PUT, DELETE)\n- Mapear request body e query parameters\n- Documentar response structure\n- Identificar middlewares e validações\n\n## Etapa 2: Análise de APIs Internas\n\n### 2.1 Estrutura de Endpoints\n**Para cada arquivo em `@src/app/api/`:**\n- Identificar rota da API\n- Analisar exports (GET, POST, PUT, DELETE)\n- Mapear request/response schemas\n- Verificar autenticação/autorização\n- Documentar validações de entrada\n- Identificar conexões com banco de dados\n\n### 2.2 Fluxo de Dados\n**Rastrear:**\n- Models/schemas utilizados\n- Conexões com banco de dados\n- Middlewares aplicados\n- Tratamento de erros\n- Logs e monitoring\n- Rate limiting\n\n## Etapa 3: Verificação de Documentação Existente\n\n### 3.1 Comparação com `@doc/documentação/`\n**Processo:**\n```bash\n# Listar documentações existentes\nls @doc/documentação/*.md\n\n# Para cada documentação:\n# 1. Extrair nome da rota do arquivo\n# 2. Verificar se página correspondente existe\n# 3. Se não existir → marcar para exclusão\n# 4. Se existir → comparar com análise atual\n```\n\n### 3.2 Ações por Cenário\n- **Documentação existe + Página existe:** Atualizar documentação\n- **Documentação existe + Página não existe:** Excluir documentação\n- **Documentação não existe + Página existe:** Criar nova documentação\n- **Mudanças na API:** Atualizar requests/responses\n\n## Etapa 4: Template de Documentação\n\n### 4.1 Estrutura Padrão\n```markdown\n# **nome:** [Nome da Página]\n# **rota:** [/caminho/da/rota]\n\n## **descrição:**\n- [Descrição funcional da página]\n\n## **tipo de acesso:**\n- [público/protegido/admin]\n\n## **funcionalidades embarcadas:**\n- [Lista de funcionalidades]\n- [Componentes principais]\n- [Ações disponíveis]\n\n## **restrições:**\n- [Regras de acesso]\n- [Validações]\n- [Limitações]\n\n## **dependências:**\n- [Context/Providers utilizados]\n- [Hooks customizados]\n- [Bibliotecas externas]\n\n## **APIs utilizadas:**\n\n### **API Interna:**\n- **Endpoint:** `[METHOD] /api/endpoint`\n- **Autenticação:** [sim/não]\n- **Request:**\n```json\n{\n \"campo\": \"tipo (descrição)\"\n}\n```\n- **Response:**\n```json\n{\n \"status\": \"success\",\n \"data\": {}\n}\n```\n\n### **API Externa:**\n- **Serviço:** [Nome do serviço]\n- **Endpoint:** `[URL completa]`\n- **Autenticação:** [tipo]\n\n## **Navegação:**\n- **Links de entrada:** [páginas que redirecionam para esta]\n- **Links de saída:** [páginas para onde esta redireciona]\n- **Parâmetros de rota:** [se dinâmica]\n\n## **Estados e Dados:**\n- **Estados locais:** [useState, useReducer]\n- **Estados globais:** [Context, Zustand, Redux]\n- **Cache:** [React Query, SWR]\n- **Persistência:** [localStorage, sessionStorage]\n\n## **Validações:**\n- **Formulários:** [schema de validação]\n- **Inputs:** [regras específicas]\n- **Permissões:** [baseado em roles]\n\n## **Tratamento de Erros:**\n- **Errors boundaries:** [componentes]\n- **Try/catch:** [async operations]\n- **Fallbacks:** [estados de erro]\n\n## **Performance:**\n- **Loading states:** [skeletons, spinners]\n- **Lazy loading:** [componentes, imagens]\n- **Memoization:** [useMemo, useCallback]\n\n## **SEO/Meta:**\n- **Title:** [título da página]\n- **Description:** [meta description]\n- **Keywords:** [palavras-chave]\n```\n\n## Etapa 5: Análise de Código Automatizada\n\n### 5.1 Padrões de Identificação\n**Buscar por:**\n```regex\n# Chamadas de API\nfetch\\(['\"`]([^'\"`]+)['\"`]\naxios\\.(get|post|put|delete)\\(['\"`]([^'\"`]+)['\"`]\napi\\.(get|post|put|delete)\\(['\"`]([^'\"`]+)['\"`]\n\n# Hooks de autenticação\nuseAuth|useUser|useSession\n\n# Redirects e navegação\nrouter\\.push|redirect|navigate\n\n# Validações\nyup|zod|joi|validate\n\n# Estados globais\nuseContext|useStore|useSelector\n```\n\n### 5.2 Extração de Metadados\n**Para cada página:**\n- Extrair imports e suas origens\n- Identificar props interface (TypeScript)\n- Mapear exports e re-exports\n- Documentar comment blocks existentes\n- Verificar metadata Next.js\n\n## Etapa 6: Automação e Validação\n\n### 6.1 Script de Análise\n```javascript\n// Pseudo-código para análise\nconst analyzeRoute = async (routePath) => {\n const pageFile = findPageFile(routePath);\n const components = extractComponents(pageFile);\n const apiCalls = extractApiCalls(pageFile, components);\n const restrictions = analyzeRestrictions(routePath);\n \n return {\n route: routePath,\n type: getRouteType(routePath), // public/protected\n components,\n apiCalls,\n restrictions,\n dependencies: extractDependencies(pageFile)\n };\n};\n```\n\n### 6.2 Validação de Documentação\n**Verificar:**\n- Todas as rotas têm documentação\n- Documentação órfã (sem página correspondente)\n- APIs documentadas existem\n- Schemas estão atualizados\n- Links internos funcionam\n\n## Etapa 7: Manutenção e Sincronização\n\n### 7.1 Triggers para Atualização\n- Novos arquivos `page.tsx` criados\n- Modificações em APIs existentes\n- Mudanças em interfaces TypeScript\n- Alterações em middlewares\n- Updates em dependências\n\n### 7.2 Processo de Sincronização\n1. **Scan incremental:** Detectar mudanças desde última execução\n2. **Impact analysis:** Identificar documentações afetadas\n3. **Auto-update:** Atualizar documentações impactadas\n4. **Validation:** Verificar consistência\n5. **Cleanup:** Remover documentações órfãs\n\n## Etapa 8: Critérios de Qualidade\n\n### 8.1 Completude\n- [ ] Todas as rotas documentadas\n- [ ] APIs mapeadas completamente\n- [ ] Restrições claramente definidas\n- [ ] Examples de request/response\n\n### 8.2 Precisão\n- [ ] Schemas atualizados\n- [ ] Endpoints corretos\n- [ ] Tipos TypeScript consistentes\n- [ ] Links funcionais\n\n### 8.3 Manutenibilidade\n- [ ] Processo automatizado\n- [ ] Documentação versionada\n- [ ] Sincronização contínua\n- [ ] Validação automática\n\n---\n\n**Saída esperada:** Documentação completa e atualizada de todas as rotas, com mapeamento preciso de APIs, restrições e fluxos de dados, mantida automaticamente em sincronia com o código.", "variables": [], "notes": "gerar documentação da rota", "metadata": { "source": { "provider": "github-windsurf-workflows", "repository": "https://github.com/alexandre-henrique-rp/iselftoken", "path": ".windsurf/workflows/gerdor-de-doc.md", "ref": "afef48651f79336bda097cf4aa33ce53bc28ae96", "url": "https://github.com/alexandre-henrique-rp/iselftoken/blob/afef48651f79336bda097cf4aa33ce53bc28ae96/.windsurf/workflows/gerdor-de-doc.md", "key": "alexandre-henrique-rp/iselftoken/.windsurf/workflows/gerdor-de-doc.md" } } }