manual
do sistema
Guia completo do ClubTour — plataforma de destinos turísticos por verticais de interesse construída sobre
Cloudflare Workers e D1. Cada vertical roda no mesmo motor (clubtour-engine),
detectado automaticamente pelo hostname.
o que é o clubtour
visão geralO ClubTour é uma engine replicável de destinos turísticos por verticais de interesse — pense num Shopify para hubs turísticos temáticos. Um único worker (clubtour-engine) detecta o hostname e serve o vertical correto, com marca, agente IA, paleta e vocabulário próprios.
Toda a infraestrutura roda em Cloudflare (Workers + D1 + ASSETS), sem servidores próprios. O banco é SQLite via D1, com uma única tabela mapa particionada por coluna vertical — a mesma query serve os três verticais.
O comprador do ClubTour não é o turista — é a associação, secretaria ou prefeitura que quer um hub digital para o seu produto regional. A Rota da Cachaça, a Rota do Vinho e a Simple Malt são as primeiras instâncias públicas da engine.
números do sistema
métricas · jun 2026| métrica | valor | observação |
|---|---|---|
| Alambiques mapeados (Rota da Cachaça) | 8.000+ | Brasil — maior base digital de alambiques do país |
| Vinícolas mapeadas (Rota do Vinho) | 3.100+ | Brasil + Argentina |
| Destilarias (Simple Malt) | 3.100+ | Escócia 780 · EUA 2.156 · Japão 112 · Brasil 143+ |
| Verticais ativas | 3 | cachaca · vinho · whisky |
| Países com cobertura (whisky) | 20+ | Escócia, EUA, Japão, Irlanda, Canadá, Brasil… |
| Workers em produção | 2 | clubtour-engine · upg-engine |
| Bancos D1 | 2 | clubtour-bebidas-db · agentlink-db |
| Pipeline Maestro | 6 agentes | Router → Concierge → Interceptor → Curador → Validador → Apresentador |
infraestrutura
cloudflare stack| worker | domínios | responsabilidade |
|---|---|---|
clubtour-engine | rotadacachaca.clubtour.app · rotadovinho.clubtour.app · simplemalt.clubtour.app | Motor unificado — detecta vertical por hostname, serve hub/mapa/chat/passaporte, pipeline Maestro de 6 agentes |
upg-engine | clubtour.app · passaporte.clubtour.app · gramado.clubtour.app · passaportegramado.com | Worker da rede: página manifesto ClubTour, Copa 2026 splash, hubs regionais (Gramado, Vinhedos, Caxias), passaporte PWA |
| banco | worker | conteúdo principal |
|---|---|---|
clubtour-bebidas-db | clubtour-engine | tabela mapa (todos os estabelecimentos, particionada por vertical), tabela estabelecimentos (dados enriquecidos), passaportes, carimbos, links, conhecimento do agente |
agentlink-db | clubtour-engine | histórico de conversas, sessões, métricas de interação do pipeline Maestro |
A função getVertical(request) no index.js do clubtour-engine lê o host header e retorna o vertical:
// src/index.js — clubtour-engine function getVertical(request) { const host = request.headers.get('host') || ''; if (host.includes('cachaca') || host.includes('pinga')) return 'cachaca'; if (host.includes('whisky') || host.includes('malt')) return 'whisky'; if (host.includes('vinho') || host.includes('wine')) return 'vinho'; return request.headers.get('X-Vertical') || 'cachaca'; }
3 verticais ativas
engine replicávelCada vertical é uma instância completa da engine com identidade própria: nome, cor, emoji, agente IA, vocabulário e conteúdo. O motor é sempre o mesmo clubtour-engine — o que muda é o VERTICAL_CONFIG[vertical].
#6B2D0F.#8B1A2E.#C9A646.hub / catálogo
spa · descobertaCada vertical tem uma página hub — SPA com duas views: viewHome (cards de estados/países com contagem) e viewResults (lista de estabelecimentos com filtros e paginação 12/página).
Filtros disponíveis: por envelhecimento (cachaça), por varietal (vinho) ou por estilo (whisky). Segundo filtro: contato (site / telefone / Instagram). Ordenação: A→Z, por cidade, com site primeiro.
Busca com typeahead de 280ms de debounce — busca em tempo real via /api/search?q=. Cada card tem botão "mestre" que abre o chat flutuante diretamente contextualizado no estabelecimento.
mapa interativo
leaflet · globalCada vertical tem um mapa Leaflet 1.9.4 com tiles CartoCDN (dark night + voyager day, toggle). O mapa da cachaça e do vinho foca no Brasil (centro [-15.5, -47.9], zoom 5). O mapa do whisky é mundial (centro [30, 0], zoom 2).
Sidebar 300px com lista de estabelecimentos, filtro por estado/país e busca em tempo real. Cada pin é um L.divIcon colorido por estado/país. Popup com nome, cidade, links (site/insta/tel) e botão "mestre" que abre o chat flutuante.
Coordenadas: usa lat/lng do banco quando disponível, ou jitter determinístico em torno do centro do estado/país (seed baseado no id) para evitar sobreposição.
agente ia por vertical
chat · contextualCada vertical tem um agente especializado com nome, escopo e personalidade próprios. O chat pode ser aberto na home, no hub ou no mapa — sempre contextualizado no estabelecimento selecionado via estab_id.
| vertical | agente | escopo |
|---|---|---|
| cachaca | Mestre Cachaçeiro | alambiques, destilação, envelhecimento, harmonizações, roteiros de cachaça — recusa off-topic |
| vinho | Sommelier Digital | vinícolas, varietais, visitas, roteiros, harmonizações — recusa off-topic |
| whisky | Mestre Malteiro | destilarias, estilos, casks, envelhecimento, Copa 2026 Whisky, harmonizações — recusa off-topic |
O chat usa a orquestra Maestro (6 mini-agentes) quando recebe uma mensagem via POST /api/chat. O histórico da conversa é mantido no cliente e passado a cada turn via history[]. O estab_id carrega a base de conhecimento específica do estabelecimento do banco D1.
Age gate: modal de verificação de idade injetado em todas as páginas do clubtour-engine. Bots (Googlebot, Bingbot etc.) são detectados por User-Agent e pulam o gate automaticamente.
orquestra maestro
pipeline · 6 agentesO pipeline Maestro é composto por 6 mini-agentes sequenciais — cada um recebe um envelope de dados, processa e passa para o próximo. Resolve 5 falhas crônicas do worker monolítico: alucinação, dedupe, substituição silenciosa, loop e ortografia.
O Curador usa o Listening Pattern: lê os 50 registros mais recentes do D1 + faz busca LIKE pela intenção detectada — garantindo que o contexto mais fresco sempre entra na resposta. Estatuto e regimento são tratados como domínio separado com busca por artigo (Art. N°).
passaporte
gamificação · pwaO passaporte ClubTour é o motor de gamificação e fidelização. O usuário coleciona carimbos a cada visita a estabelecimentos parceiros. Níveis progressivos por vertical: Pingunçu Iniciante → Mestre → Grão-Pingunçu (cachaça); equivalentes para vinho e whisky.
Fluxo: usuário chega no hub → cria passaporte (nome + WhatsApp, zero senha) → faz check-in na visita → acumula carimbos → desbloqueia benefício na próxima visita ao estabelecimento.
Circuitos: cada roteiro de parceiro tem N paradas. Completar todas desbloqueia prêmio. O painel do dono mostra em tempo real quem completou e permite enviar benefício por WhatsApp.
copa do mundo do whisky · 2026
conteúdo especialA Simple Malt tem uma página especial que cruza as 11 cidades-sede da Copa 2026 (Dallas, NY/NJ, LA, Philly, Boston, Seattle, Atlanta, SF, Kansas City, Miami + Toronto/Vancouver) com destilarias próximas em cada cidade.
A página worldcup.html é ativada também via splash de 8 segundos em clubtour.app — visitantes da marca-mãe são redirecionados para a experiência Copa.
Também inclui seção do Bourbon Trail (8 destilarias históricas do Kentucky), passaporte visual com slots por país e painel de estatísticas do whisky mundial.
api endpoints
referência técnicaTodos os endpoints auto-detectam o vertical pelo hostname — sem parâmetro ?vertical=. Basta chamar de dentro do mesmo domínio ou passar o header Host correto.
Authorization: Bearer <token>. Requisições sem token válido recebem 403 Forbidden. Tokens são gerados por cliente e armazenados no D1.Exemplo de requisição autenticada:
# Chamada autenticada via cURL curl -H "Authorization: Bearer <seu-token-256bits>" https://rotadacachaca.clubtour.app/api/stats # Resposta sem token ou token inválido HTTP/2 403 { "error": "unauthorized" }
| método | endpoint | descrição |
|---|---|---|
| GET | /api/stats | total, com_site, por_estado — stats do vertical detectado |
| GET | /api/estabelecimentos?estado=®iao=&limit= | lista paginada por estado/país, limite até 300 |
| GET | /api/search?q=&limit= | busca fulltext por nome, cidade, estado — limite padrão 8 (typeahead) ou 200 (lista) |
| POST | /api/chat | envia mensagem ao pipeline Maestro; body: { estab_id, message, history[] } |
| GET | /api/passaporte | retorna passaporte do usuário pela sessão/cookie |
| POST | /api/checkin | registra carimbo: body { passaporte_id, mapa_id } |
| GET | /api/ping?page=&action= | analytics 1st-party — registra pageview/evento sem PII |
| GET | /api/conhecimento?estab_id= | retorna base de conhecimento do estabelecimento para o agente |
deploy e operações
wrangler · cloudflareDeploy do clubtour-engine via Wrangler CLI a partir de D:AgentLinkAgentesclubtour.appclubtour-engine. Cada deploy publica para os 3 domínios customizados simultaneamente.
# Deploy principal (clubtour-engine) cd D:/AgentLink/Agentes/clubtour.app/clubtour-engine npx wrangler deploy # Deploy do upg-engine (clubtour.app + passaporte + gramado) cd D:/AgentLink/Agentes/PassaporteGramado/upg-engine npx wrangler deploy # Query no D1 de estabelecimentos npx wrangler d1 execute clubtour-bebidas-db --command "SELECT vertical, COUNT(*) FROM mapa GROUP BY vertical" --remote --json
Regra de ouro: toda mudança de arquitetura no worker atualiza o Changelog do .md correspondente. Tripbier e ClubTour são contas/negócios separados — nunca cruzar workers, dados ou credenciais.
Assets estáticos: HTML das páginas do hub, mapa e worldcup ficam em clubtour-engine/html/ e são servidos via binding ASSETS. O index.js faz rewrite de URL para servir versões por vertical (ex: /index.html → /index-whisky.html no simplemalt).
lgpd
privacidade · complianceBanner de cookies injetado em todas as páginas dos verticais. Consentimento armazenado em localStorage. Analytics 1st-party via /api/ping — hash SHA1 de IP+UA, sem PII. Endpoints /legal/privacidade e /legal/termos disponíveis em todos os domínios.
Age gate modal em todos os verticais de bebidas — detecta bots por User-Agent e pula o gate automaticamente (Googlebot, Bingbot, WhatsApp, Twitterbot etc.).