🍺 Cervejaria Dogma - Agente de Atendimento Inteligente

Sistema de atendimento ao cliente com IA, integrado com Shopify e alimentado por Gemini AI.

📋 Funcionalidades Implementadas

✅ Completas

• ✅ Chat Inteligente: Interface de chat com design personalizado da Cervejaria Dogma
• ✅ Integração Gemini AI: Respostas contextualizadas usando Google Gemini 2.5 Flash
• ✅ 📚 RAG (Retrieval-Augmented Generation) (NOVO! 🚀):
  • Aprendizado com Histórico: IA aprende com 8 meses de emails do Gmail
  • Busca Semântica: Encontra casos similares resolvidos anteriormente
  • Cloudflare Vectorize: Banco vetorial para embeddings (768 dimensões)
  • Zero Custo: Gemini embeddings + Vectorize no free tier
  • Atualização Incremental: Fácil adicionar novos casos ao histórico
  • Documentação Completa: COMO_USAR_RAG.md
• ✅ 🔀 SELETOR HÍBRIDO DE LLM (NOVO! 💎):
  • Detector de Complexidade: Analisa 10+ critérios para classificar mensagens
  • Gemini para Casos Simples: 85-90% dos casos (grátis)
  • Claude para Casos Complexos: 10-15% dos casos (ameaças legais, reembolsos, etc)
  • 3 Modos de Operação: test (grátis, mock), free (API limitada), paid (produção)
  • Threshold Ajustado: Score 12+ usa Claude (otimizado para 10 atendimentos/dia)
  • Custo Otimizado: R$ 5-8/mês (vs R$ 188/mês com Claude 100%)
  • Documentação: DETECTOR_COMPLEXIDADE.md
• ✅ 🧠 RACIOCÍNIO AVANÇADO DA IA:
  • Chain-of-Thought (CoT): Raciocínio passo a passo para perguntas complexas
  • Self-Consistency: Validação cruzada com múltiplas respostas
  • Reflection Pattern: Auto-validação e correção de respostas
  • Memória de Longo Prazo: Aprendizado contínuo com interações anteriores
  • Confidence Scoring: Score de 0-100% em cada resposta
  • Reasoning Analysis: Classificação automática de complexidade (simple/moderate/complex)
  • Documentação Completa: AI_REASONING_GUIDE.md
• ✅ Integração Shopify Completa:
  • Busca automática de clientes e pedidos
  • Catálogo de Produtos: Sincronização e busca de produtos com preços
  • Promoções Ativas: Integração com cupons de desconto e price rules
• ✅ Integração Tiny ERP:
  • Rastreamento Preciso: Dados reais de envio e rastreamento
  • Status de Entrega: Informações atualizadas sobre código de rastreamento, transportadora e datas
  • Cache Inteligente: Sincronização automática com atualização a cada 6 horas
  • Endpoints Admin: /api/admin/sync-shipping e /api/admin/shipping/:orderNumber
• ✅ Treinamento da IA em Tempo Real:
  • Via Chat: Adicionar conhecimento diretamente na conversa com senha de admin
  • Via API: Endpoints REST completos para CRUD de treinamentos
  • Formato Simples: TREINAR:[senha]:CATEGORIA:[cat]:PERGUNTA:[q]:RESPOSTA:[r]
  • Gestão Completa: Listar, adicionar, atualizar e deletar treinamentos
  • Documentação: Guia completo em TRAINING_GUIDE.md
• ✅ Métricas e Monitoramento de IA (NOVO!):
  • Dashboard de Métricas: Total de queries, taxa de sucesso, confiança média
  • Insights de Conversas: Resoluções bem-sucedidas, escalonamentos, lacunas de dados
  • Padrões de Memória: Interações mais reutilizadas, taxa de sucesso por padrão
  • APIs de Analytics: Endpoints REST para visualização de métricas
• ✅ Base de Conhecimento Expandida:
  • 35+ FAQs sobre produtos, entregas, pagamentos, devoluções
  • Informações de Preços: Respostas com valores reais dos produtos
  • Cupons e Promoções: Códigos de desconto e condições
• ✅ Histórico de Conversas: Persistência de conversas em banco de dados D1
• ✅ Detecção Inteligente:
  • Identifica perguntas sobre pedidos, reclamações e produtos
  • Detecta menções a preços, promoções, descontos e rastreamento
• ✅ Cache Avançado: Sistema de cache para produtos, promoções, clientes, pedidos e rastreamento
• ✅ Extração de Informações: Detecta emails e números de pedido nas mensagens

🔄 Em Desenvolvimento

• 🔄 Integração Gmail: Receber e responder emails (próxima fase)
• 🔄 Sistema de Tickets: Gestão formal de atendimentos
• 🔄 Dashboard Admin: Interface para visualizar conversas e métricas
• 🔄 Widget Embarcável: Versão do chat para incorporar no site Shopify

🌐 URLs e Endpoints

Produção (Sandbox)

• Interface Chat: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai
• API Health: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/health
• API Chat: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/chat
• API Cliente: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/customer/:email
• API Pedido: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/order/:orderNumber
• API Produtos: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/products
• API Busca Produtos: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/products/search?q=ipa
• API Promoções: https://3000-imdh80nwds4480jh77bt7-2b54fc91.sandbox.novita.ai/api/promotions

🗄️ Arquitetura de Dados

Banco de Dados D1 (SQLite)

customers                - Cache de clientes Shopify
orders                  - Cache de pedidos Shopify
products                - Cache de produtos Shopify (títulos, preços, descrições)
price_rules             - Cache de promoções/cupons de desconto
shipping_tracking       - Dados de rastreamento do Tiny ERP
conversations           - Histórico de conversas
messages                - Mensagens individuais
training_data           - Base de conhecimento (FAQs)
ai_memory              - Memória de longo prazo da IA (NOVO! 🧠)
conversation_insights  - Insights e padrões de conversas (NOVO! 📊)
ai_metrics             - Métricas diárias de performance da IA (NOVO! 📈)
tickets                - Sistema de tickets (futuro)

Integrações

• Gemini AI: Google Generative AI (gemini-2.5-flash-preview-05-20) + text-embedding-004
• Claude AI: Claude 3.5 Haiku (casos complexos, opcional)
• Cloudflare Vectorize: Banco vetorial para RAG (768 dimensões, cosine similarity)
• Shopify Admin API: v2024-10
• Tiny ERP API: v2 (rastreamento e envios)
• Cloudflare D1: Banco de dados distribuído

📚 Base de Conhecimento

O sistema possui 35+ entradas de treinamento cobrindo:

Categorias

• FAQ: Perguntas frequentes sobre produtos
• products: Catálogo de produtos com preços específicos
• promotions: Cupons de desconto e promoções ativas
• beer_info: Informações técnicas sobre cervejas
• shipping_policy: Políticas e prazos de entrega
• returns: Devoluções e trocas
• payment: Formas de pagamento
• subscription: Programa de assinantes
• general: Informações gerais da cervejaria

🎨 Design

Paleta de Cores (Cervejaria Dogma)

--dogma-black: #0B0B0B    /* Cor primária - títulos e CTAs */
--dogma-dark: #1E1E1E     /* Fundos escuros */
--dogma-gold: #FFB800     /* Accent cervejeiro */
--dogma-green: #2ECC71    /* Descontos/assinantes */
--dogma-gray: #6E6E6E     /* Textos secundários */
--dogma-light: #F2F2F2    /* Fundos claros */

Características

• Tipografia: Sans-serif moderna (Helvetica/Inter)
• Botões: Uppercase, preto com hover dourado
• Estilo: Minimalista, contrastado, premium

🚀 Como Usar

Para Clientes

1. Acesse o chat na URL pública
2. Digite sua mensagem (pode incluir seu email para consultar pedidos)
3. O assistente responderá com base na base de conhecimento
4. Se mencionar um número de pedido, o sistema busca automaticamente

Exemplos de Perguntas

"Meu email é cliente@email.com, quero saber sobre meu pedido #1234"
"Onde está meu pedido? Código de rastreamento AC484135204BR"
"Meu pedido já foi enviado? Quando chega?"
"Quais tipos de cerveja vocês têm?"
"Quanto custa a IPA? Tem promoção?"
"Vocês têm cupom de desconto?"
"Qual o preço do pack degustação?"
"Qual o prazo de entrega para São Paulo?"
"Posso trocar um produto com defeito?"
"Como funciona o clube de assinantes?"
"Qual cerveja harmoniza com chocolate?"

Treinamento da IA (Admin)

TREINAR:dogma2025:CATEGORIA:products:PERGUNTA:Qual o teor alcoólico da Cosmic Latte?:RESPOSTA:A Cosmic Latte possui 7.2% de ABV...

📚 Guia Completo: TRAINING_GUIDE.md

🛠️ Desenvolvimento

Comandos Locais

# Build do projeto
npm run build

# Banco de Dados
npm run db:migrate:local          # Aplicar migrations
npm run db:seed                   # Popular banco com FAQs
npm run db:reset                  # Reset completo

# RAG (Novo! 📚)
npm run rag:process-emails        # Processar emails do Gmail (.mbox)
npm run rag:generate-embeddings   # Gerar embeddings com Gemini
npm run rag:create-index          # Criar índice Vectorize
npm run rag:upload-vectors        # Upload vetores para Vectorize

# Servidor
pm2 start ecosystem.config.cjs    # Iniciar
pm2 logs dogma-support --nostream # Ver logs
pm2 restart dogma-support         # Reiniciar
pm2 delete dogma-support          # Parar

Estrutura do Projeto

webapp/
├── src/
│   ├── index.tsx               # App principal com rotas + endpoints de métricas
│   ├── ai.ts                   # Serviço Gemini AI + Raciocínio + RAG (🧠📚)
│   ├── complexity-detector.ts  # Detector de complexidade para seleção de LLM (NOVO! 💎)
│   ├── claude-service.ts       # Wrapper Claude API com 3 modos (NOVO! 💎)
│   ├── rag-service.ts          # RAG com Vectorize (NOVO! 📚)
│   ├── shopify.ts              # Cliente Shopify API
│   ├── tiny.ts                 # Cliente Tiny ERP API
│   ├── database.ts             # Operações D1 + Memória e Métricas
│   └── types.ts                # TypeScript types
├── scripts/
│   ├── process-gmail-mbox.ts   # Processador de emails do Google Takeout (NOVO! 📧)
│   └── generate-embeddings.ts  # Gerador de embeddings com Gemini (NOVO! 🔢)
├── public/static/
│   └── app.js                  # Frontend do chat
├── migrations/
│   ├── 0001_initial_schema.sql
│   ├── 0002_training_knowledge.sql
│   ├── 0003_shipping_tracking.sql
│   └── 0004_long_term_memory.sql
├── seed.sql                    # Dados de treinamento
├── .dev.vars                   # Secrets (não commitado)
├── wrangler.jsonc              # Config Cloudflare + Vectorize
├── TRAINING_GUIDE.md           # Guia de treinamento da IA
├── AI_REASONING_GUIDE.md       # Guia de raciocínio avançado
├── DETECTOR_COMPLEXIDADE.md    # Guia do seletor híbrido de LLM (NOVO! 💎)
├── COMO_USAR_RAG.md            # Guia completo de RAG (NOVO! 📚)
└── ROADMAP.md                  # Roadmap de 10 fases

🔐 Variáveis de Ambiente

Configuradas (.dev.vars)

# APIs principais
GEMINI_API_KEY=<configurado>
SHOPIFY_STORE_DOMAIN=dogmacervejaria.myshopify.com
SHOPIFY_ACCESS_TOKEN=<configurado>
SHOPIFY_API_VERSION=2024-10
TINY_API_TOKEN=<configurado>
ADMIN_TRAINING_PASSWORD=dogma2025

# Claude (Seletor Híbrido - NOVO!)
CLAUDE_MODE=test              # test (grátis) | free | paid
# CLAUDE_API_KEY=sk-ant-...  # Só necessário em free/paid

# Vectorize (RAG - configurado via wrangler.jsonc)
# binding: VECTORIZE, index: dogma-support-kb

⚠️ Importante: Em produção, use npx wrangler secret put para armazenar secrets de forma segura.

📦 Tecnologias Utilizadas

Backend

• Hono: Framework web lightweight
• Cloudflare Workers: Runtime edge
• Cloudflare D1: Banco de dados distribuído
• Google Gemini AI: Modelo de linguagem
• Shopify Admin API: Integração e-commerce

Frontend

• Vanilla JavaScript: Sem frameworks pesados
• TailwindCSS: Estilização via CDN
• Font Awesome: Ícones
• Axios: HTTP client

🎯 Próximos Passos Recomendados

Alta Prioridade

1. Widget Embarcável: Criar versão para incorporar no site Shopify

   • Script de instalação
   • Botão flutuante no canto da tela
   • Customização de cores/posição

2. Integração Gmail: Sistema de email

   • Receber emails no Gmail
   • Processar com IA
   • Responder automaticamente
   • Sincronizar com conversas do chat

3. Sistema de Tickets: Gestão formal

   • Criar ticket automaticamente
   • Encaminhar para atendente humano
   • Status e prioridade
   • Notificações

Média Prioridade

4. Dashboard Admin

   • Listar conversas ativas
   • Métricas de atendimento
   • Gerenciar base de conhecimento
   • Assumir conversas manualmente

5. Monitoramento Avançado (✅ IMPLEMENTADO!)

   • ✅ Dashboard de métricas de IA
   • ✅ Confidence scoring em respostas
   • ✅ Insights de conversas
   • ✅ Memória de longo prazo
   • 🔄 Interface visual (próxima fase)

6. Analytics

   • Perguntas mais frequentes
   • Taxa de resolução
   • Tempo médio de resposta
   • Satisfação do cliente

Baixa Prioridade

7. Multicanal: WhatsApp, Instagram, Facebook
8. Multilíngua: Suporte a inglês/espanhol
9. Chatbot Voice: Integração de voz

📊 Status do Projeto

• Ambiente: Desenvolvimento (Sandbox)
• Status: ✅ Operacional com IA Avançada + RAG
• Versão: 3.0.0 (📚 RAG + 💎 Hybrid LLM Update)
• Última Atualização: 08/11/2025
• Tech Stack: Hono + Gemini/Claude Hybrid + RAG (Vectorize) + Shopify + Tiny ERP + Cloudflare D1
• Novidades v3.0:
  • 📚 RAG com histórico de 8 meses do Gmail
  • 💎 Seletor híbrido Gemini/Claude (custo otimizado)
  • 🔢 Embeddings semânticos (Gemini text-embedding-004)
  • 🗄️ Cloudflare Vectorize (busca vetorial)
  • 💰 Redução de 95% no custo (R$ 5-8/mês vs R$ 188/mês)
• Features Anteriores:
  • 🧠 Chain-of-Thought Reasoning
  • 🔄 Self-Consistency Validation
  • 🎯 Reflection Pattern
  • 💾 Long-Term Memory
  • 📊 AI Metrics & Analytics

🔗 Links Úteis

• Site Cervejaria Dogma: https://cervejariadogma.com.br
• Documentação Gemini AI: https://ai.google.dev/docs
• Documentação Shopify API: https://shopify.dev/docs/api/admin-rest
• Cloudflare D1 Docs: https://developers.cloudflare.com/d1

📝 Notas Técnicas

Performance

• Cache de clientes/pedidos reduz chamadas API
• D1 distribui dados globalmente
• Edge runtime para latência mínima

Segurança

• Secrets gerenciados via .dev.vars (local) e Wrangler Secrets (produção)
• CORS configurado apenas para origens necessárias
• Validação de inputs em todas as rotas

Escalabilidade

• Cloudflare Workers escala automaticamente
• D1 suporta milhões de requisições
• Gemini AI gerencia rate limits automaticamente

---

Desenvolvido para Cervejaria Dogma 🍺 Powered by Gemini AI + Shopify + Cloudflare