# Detecção Automática de Schemas - IA

## 🎯 Como Funciona

Agora a IA detecta automaticamente qual schema usar baseado na pergunta do usuário. Implementei uma estratégia **em 3 camadas**:

---

## 📊 Estratégia 1: Keywords (Rápido - 80% dos casos)

Cada schema tem uma lista de **keywords** associadas:

### fact_posicoes_eventos
```
posição, posicao, localização, rastreamento, parado, velocidade, 
km rodado, ignição, latitude, longitude, cidade, estado, uf,
onde está, quantos veículos, motorista, gestor, cliente, 
mercadoria, viagem, carregamento, descarga
```

### fact_vencimentos  
```
vencimento, vencido, vencer, próximo vencimento, preventiva, revisão,
manutenção, documento, rg, multa, kmvcto, dtvcto, data de vencimento,
ordem de serviço, os, garantia, em atenção, núcleo operação,
filial, programador, cavalo, carreta, equipamento
```

**Quando pergunta contém uma keyword, ela marca ponto!**

---

## 🧠 Estratégia 2: Claude Semântica (Fallback - 15% dos casos)

Se nenhuma keyword bater, a IA chama Claude para análise semântica:

```
Pergunta: "Qual é a manutenção programada dos meus equipamentos?"
→ Sem keywords diretas
→ Claude analisa semanticamente
→ Detecta "manutenção + equipamentos" = fact_vencimentos
```

---

## 🔧 Estratégia 3: Multiplos Schemas (Avançado - 5% dos casos)

Alguns schemas dependem de outros:

```php
'fact_vencimentos' => [
    'tabelas_dependentes' => ['fact_posicoes_eventos']
]
```

Se pergunta é "Qual é a posição dos veículos com vencimento vencido?", ela:
1. Detecta `fact_vencimentos` (keyword: vencimento)
2. Adiciona automaticamente `fact_posicoes_eventos` (dependência)

---

## 💡 Exemplos de Funcionamento

### Exemplo 1: Pergunta Simples
```
Usuário: "Quantos veículos estão parados em SP?"
→ Detecta: "parado" + "SP" = fact_posicoes_eventos ✅
→ IA recebe APENAS schema de posições
```

### Exemplo 2: Pergunta Complexa
```
Usuário: "Quais revisões preventivas estão vencidas para os cavalos?"
→ Detecta: "revisões" + "preventivas" + "vencidas" + "cavalos"
→ IA recebe: fact_vencimentos (primário)
```

### Exemplo 3: Pergunta Semântica
```
Usuário: "Me mostre a frota que precisa de manutenção"
→ Sem keywords = usa Claude
→ Claude identifica "manutenção" = fact_vencimentos
→ IA recebe: fact_vencimentos
```

---

## 🔍 Como Adicionar Novos Schemas

Quando você adicionar uma nova tabela no `schemas.php`, basta:

1. **Adicionar a entrada em `schemas.php`** (já feito)
2. **Adicionar keywords em `detectarSchemasRelevantes()`**:

```php
'sua_nova_tabela' => [
    'keywords' => [
        'palavra-chave1', 'palavra-chave2', 'palavra-chave3',
        // ... mais keywords relacionadas
    ],
    'tabelas_dependentes' => ['outra_tabela_se_necessário']
]
```

**Exemplo completo:**
```php
'fro001_despesas' => [
    'keywords' => [
        'despesa', 'gasto', 'custo', 'combustível', 'pedágio',
        'alimentação', 'hospedagem', 'valor', 'reembolso'
    ],
    'tabelas_dependentes' => []
]
```

---

## ⚙️ Configuração Avançada

### Ajustar Score de Relevância

No arquivo `claude_handler.php`, função `detectarSchemasRelevantes()`:

```php
// Mudar pontuação de keywords
if (strpos($pergunta_lower, $keyword) !== false) {
    $scores[$schema] += 2; // Aumentar de 1 para 3 se for crítico
}
```

### Ativar/Desativar Detecção Semântica

Se quiser apenas keywords (mais rápido):

```php
// Em detectarSchemasRelevantes(), comentar:
// if (max($scores) === 0) {
//     $scores = $this->detectarSchemasComClaude($pergunta, $mapa_keywords);
// }
```

---

## 📋 Fluxo Completo

```
1. Usuário faz pergunta
   ↓
2. processarPergunta() chamado
   ↓
3. getSchemaDescriptionDinamico() chamado
   ↓
4. detectarSchemasRelevantes() analisa
   ├─ Procura por keywords (rápido)
   ├─ Se nada: chama Claude (semântica)
   └─ Ordena por relevância
   ↓
5. Schemas relevantes montados no prompt
   ↓
6. Claude recebe APENAS os schemas necessários
   ↓
7. Claude gera SQL correto baseado nas tabelas recomendadas
   ↓
8. Query executada e resultados formatados
```

---

## ✅ Benefícios

| Aspecto | Antes | Depois |
|--------|--------|----------|
| **Contexto** | Todos os schemas sempre | Apenas relevantes |
| **Precisão** | Às vezes errava de tabela | Raramente erra |
| **Velocidade** | Prompt grande | Prompt compacto |
| **Custo API** | Mais tokens | Menos tokens |
| **Escalabilidade** | Difícil com muitos schemas | Funciona bem |

---

## 🧪 Testar Detecção

Para testar a detecção de um schema específico:

```php
// No index.php ou em um teste:
$handler = new ClaudeHandler($apiKey, $bdcon);

// Ver quais schemas foram detectados
$schemas = $handler->detectarSchemasRelevantes("Quantos vencimentos estão vencidos?");
echo json_encode($schemas, JSON_PRETTY_PRINT);
```

---

## 📝 Checklist para Adicionar Nova Tabela

- [ ] Criar entrada em `schemas.php`
- [ ] Adicionar descrição, colunas e exemplos
- [ ] Adicionar keywords em `detectarSchemasRelevantes()`
- [ ] Testar com perguntas relevantes
- [ ] Adicionar tabelas dependentes se necessário
- [ ] Documentar no README

Pronto! A IA agora é **inteligente demais** para você! 🚀
