Pular para conteúdo

Google Sheets Tools - Índice Completo

📊 Visão Geral

Este diretório contém a documentação completa das 15 tools de Google Sheets disponíveis no Lumina Flow Builder. Todas as tools utilizam autenticação OAuth2 e seguem o padrão de documentação estabelecido.

🔧 Tools Disponíveis

📖 Operações de Leitura

  1. SHEETS_READ - Ler dados de um range específico
  2. Buscar informações de planilha para uso no fluxo
  3. Casos: CRM, estoque, FAQ, relatórios

  4. Suporta notação A1: Sheet1!A1:B10

  5. SHEETS_GET_VALUES - Buscar múltiplos ranges em uma requisição

  6. Otimização para ler várias áreas dispersas
  7. Casos: dashboards, KPIs, métricas de diferentes abas
  8. Performance: 1 requisição ao invés de múltiplas

✍️ Operações de Escrita

  1. SHEETS_WRITE - Escrever/sobrescrever dados em células
  2. Atualizar valores em posição específica
  3. Casos: atualizar status, registrar timestamps, dashboards

  4. Substitui conteúdo existente

  5. SHEETS_APPEND - Adicionar linhas ao final da tabela

  6. Inserir novos registros sem sobrescrever
  7. Casos: leads, logs, vendas, histórico

  8. Encontra automaticamente última linha

  9. SHEETS_UPDATE - Atualizar células específicas

  10. Similar ao WRITE, com semântica de atualização
  11. Casos: correções, incrementos, status
  12. Uso semântico para modificação de existente

🗑️ Operações de Remoção

  1. SHEETS_CLEAR - Limpar conteúdo mantendo formatação
  2. Remove valores, preserva formato/estrutura
  3. Casos: cache temporário, reset de áreas

  4. NÃO remove formatação

  5. SHEETS_DELETE - Deletar linhas ou colunas inteiras

  6. Remove dimensão completa (dados + formato)
  7. Casos: arquivar processados, limpeza periódica
  8. ⚠️ IRREVERSÍVEL - sempre faça backup

🎨 Operações de Formatação e Estrutura

  1. SHEETS_FORMAT - Aplicar formatação visual
  2. Cores, negrito, bordas, tamanho fonte
  3. Casos: cabeçalhos, destaque, organização

  4. Cores RGB: valores 0-1

  5. SHEETS_CREATE - Criar nova planilha

  6. Gerar planilha do zero programaticamente
  7. Casos: relatórios mensais, templates, backups

  8. Retorna spreadsheetId e URL

  9. SHEETS_COPY - Copiar planilha ou aba

    • Duplicar estrutura inteira
    • Casos: templates, backups, versões
    • Copia dados + formatação + fórmulas

🔢 Operações de Manipulação de Dados

  1. SHEETS_SORT - Ordenar linhas por coluna

    • Classificar dados crescente/decrescente
    • Casos: rankings, alfabético, cronológico
    • Preserva integridade das linhas

  2. SHEETS_FILTER - Aplicar filtros de visualização

    • Ocultar linhas que não atendem critérios
    • Casos: análise focada, segmentação
    • Visual apenas - não remove dados

  3. SHEETS_FORMULA - Inserir fórmulas do Google Sheets

    • Cálculos automáticos e referências
    • Casos: SUM, VLOOKUP, IF, SUMIF, QUERY
    • Sempre começar com "="

  4. SHEETS_CHART - Criar gráficos visuais

    • Visualizar dados: linha, barra, pizza, área
    • Casos: dashboards, relatórios, análise
    • Retorna chartId para manipulação

⚡ Operações Avançadas

  1. SHEETS_BATCH_UPDATE - Múltiplas operações em uma requisição
    • Executar várias ações atomicamente
    • Casos: setup completo, manutenção, relatórios
    • Performance: 10+ operações em 1 chamada API

🔐 Configuração OAuth2

Todas as tools Google Sheets requerem autenticação OAuth2:

Pré-requisitos

  1. Google Cloud Console: Crie projeto em https://console.cloud.google.com
  2. Ativar API: Google Sheets API
  3. Credenciais OAuth 2.0:
  4. Client ID
  5. Client Secret
  6. Redirect URI

Variáveis de Ambiente

GOOGLE_CLIENT_ID=seu_client_id
GOOGLE_CLIENT_SECRET=seu_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback

Obter Tokens

// Fluxo OAuth2 retorna:
{
  "accessToken": "ya29.a0AfB_...",  // Válido ~1h
  "refreshToken": "1//0gABC123..."  // Válido indefinidamente
}

📐 Notação A1 (Range)

Todas as operações usam notação A1 do Google Sheets:

Formatos Comuns

A1              → Célula única
A1:B10          → Range retangular (10 linhas, 2 colunas)
A:A             → Coluna inteira
1:1             → Linha inteira
Sheet1!A1:B10   → Range na aba "Sheet1"
Vendas!A:D      → Colunas A-D da aba "Vendas"

Exemplos

"Clientes!A2:E100"  → Linhas 2-100, colunas A-E da aba Clientes
"Dashboard!B2"       → Célula B2 da aba Dashboard
"Dados!A:Z"          → Todas as colunas de A-Z da aba Dados

🎯 Casos de Uso Completos

1. CRM Automático

READ → Ler lista de clientes
FILTER → Filtrar por status "Ativo"
SORT → Ordenar por última compra
APPEND → Adicionar novo lead
FORMAT → Destacar VIPs em amarelo

2. Controle de Estoque

READ → Verificar estoque disponível
UPDATE → Decrementar após venda
APPEND → Registrar movimentação
FORMULA → Calcular total =SUM(B:B)
CHART → Gráfico de evolução

3. Relatório Mensal

CREATE → Nova planilha "Relatório_Jan_2025"
WRITE → Inserir cabeçalhos
BATCH_UPDATE → Dados + Formatação + Gráficos
FORMAT → Estilizar cabeçalho
COPY → Backup antes de enviar

🛠️ Desenvolvimento

Arquivo Fonte

Todas as implementações estão em: 

/src/whatsapp-flows/executors/google-executors.service.ts
/src/whatsapp-flows/executors/productivity-executors.service.ts
/src/flow-engine/services/google-sheets.service.ts

Implementações Atuais

✅ Implementadas completamente: - sheets_read (linha 756-766) - sheets_write (linha 768-782) - sheets_append (linha 784-798) - sheets_clear (linha 800-809)

⚠️ Documentadas (API disponível): - sheets_update, sheets_delete, sheets_create - sheets_format, sheets_sort, sheets_filter - sheets_formula, sheets_chart, sheets_copy - sheets_get_values, sheets_batch_update

Estas podem ser implementadas seguindo a API do Google Sheets v4.

📚 Recursos Adicionais

🤝 Contribuir

Para adicionar novas tools Google Sheets:

  1. Implemente em google-executors.service.ts
  2. Siga o padrão OAuth2 existente
  3. Documente em arquivo .md seguindo DOCUMENTATION_GUIDE.md
  4. Adicione exemplos práticos reais
  5. Atualize este INDEX.md

Total: 15 tools documentadas ✅

Última atualização: 2025-01-15

Documentação completa: Todas as tools seguem o padrão estabelecido em /docs/DOCUMENTATION_GUIDE.md