# 🎯 Projeção de Vendas - INÍCIO RÁPIDO

## Arquivos Criados

1. **`app/classes/ProjecaoVendas.php`** ← Classe principal (core logic)
2. **`app/classes/ProjecaoVendas_Helpers.php`** ← Funções auxiliares (calendário, integração)
3. **`app/classes/ProjecaoVendas_Exemplos.php`** ← Exemplos de uso
4. **`docs/PROJECAO_VENDAS_DOCUMENTACAO.md`** ← Documentação completa

---

## 🚀 Uso Básico (1 Minuto)

```php
<?php
require_once(__DIR__ . '/app/classes/ProjecaoVendas.php');

// Simples assim:
$resultado = ProjecaoVendas::projetarMes(
    realizadoMTD: 45000,
    metaMes: 100000,
    uteisMes: 22,
    fdsMes: 8,
    feriadosMes: 1,
    uteisRestantes: 4,
    fdsRestantes: 2,
    feriadosRestantes: 0
);

echo "Projeção: R$ " . number_format($resultado['proj_fechamento_mes'], 2);
echo "Status: " . $resultado['status'];      // 'risco', 'alerta' ou 'ok'
echo "Percentual: " . round($resultado['proj_perc_mes'] * 100, 1) . "%";
echo "Cor CSS: " . $resultado['cor'];         // 'text-danger', 'text-warning', 'text-success'
```

---

## 📊 Fórmula (Simplificada)

```
1. Dias Ponderados Total = (uteis * 1.0) + (fds * 1.25) + (feriados * 1.35)
2. Meta Diária = meta_mes / dias_ponderados_total
3. Dias Ponderados Restantes = (uteis_rest * 1.0) + (fds_rest * 1.25) + (feriados_rest * 1.35)
4. Projeção = realizado_mtd + (meta_diaria * dias_ponderados_restantes)
5. % Projetado = projeção / meta_mes

Cores:
  ≥ 100% → Verde (text-success)
  95-99.9% → Amarelo (text-warning)
  < 95% → Vermelho (text-danger)
```

---

## 🔧 Integração com Home.php

### Opção A: Adicionar em `home_service.php`

```php
<?php
require_once(__DIR__ . '/../classes/ProjecaoVendas.php');
require_once(__DIR__ . '/../classes/ProjecaoVendas_Helpers.php');

// Dentro da função obterDadosDashboard() ou após ela:
foreach ($kpisVariaveis as &$kpi) {
    $projecao = calcularProjecaoVariavel(
        $pdo,
        $kpi,
        date('n'),      // mês atual
        date('Y')       // ano atual
    );
    
    $kpi['projecao'] = $projecao;
}
?>
```

### Opção B: Mostrar em Template (`home.php`)

```html
<?php foreach ($kpisVariaveis as $kpi): ?>
    <?php if (isset($kpi['projecao'])): ?>
        <div class="projecao-card">
            <h5><?= $kpi['nome'] ?></h5>
            <p>Realizado: R$ <?= number_format($kpi['projecao']['realizado_mtd'], 2) ?></p>
            <p>Meta: R$ <?= number_format($kpi['projecao']['meta_mes'], 2) ?></p>
            
            <!-- PROJEÇÃO -->
            <div class="<?= $kpi['projecao']['cor'] ?>">
                <strong>Projeção: R$ <?= number_format($kpi['projecao']['proj_fechamento_mes'], 2) ?></strong>
                <span><?= round($kpi['projecao']['proj_perc_mes'] * 100, 1) ?>%</span>
                <span class="badge <?= $kpi['projecao']['status'] === 'ok' ? 'bg-success' : ($kpi['projecao']['status'] === 'alerta' ? 'bg-warning' : 'bg-danger') ?>">
                    <?= strtoupper($kpi['projecao']['status']) ?>
                </span>
            </div>
            
            <small class="text-muted">
                Meta diária: R$ <?= number_format($kpi['projecao']['meta_diaria_equiv'], 2) ?><br>
                Dias ponderados restantes: <?= round($kpi['projecao']['dias_ponderados_restantes'], 2) ?>
            </small>
        </div>
    <?php endif; ?>
<?php endforeach; ?>
```

---

## 📅 Configurar Feriados (Opcional)

Se quiser automatizar feriados, rode uma vez no banco:

```sql
-- Criar tabela
CREATE TABLE `back`.`feriados` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `data_feriado` DATE NOT NULL,
    `nome_feriado` VARCHAR(100) NOT NULL,
    UNIQUE KEY `uk_data` (`data_feriado`)
) ENGINE=InnoDB;

-- Inserir feriados 2026
INSERT INTO `back`.`feriados` (`data_feriado`, `nome_feriado`) VALUES
('2026-01-01', 'Ano Novo'),
('2026-02-17', 'Carnaval'),
('2026-04-21', 'Tiradentes'),
('2026-05-01', 'Dia do Trabalho'),
('2026-09-07', 'Independência'),
('2026-10-12', 'Nossa Senhora Aparecida'),
('2026-11-02', 'Finados'),
('2026-11-20', 'Consciência Negra'),
('2026-12-25', 'Natal');
```

A função `obterCalendarioMes()` buscará automaticamente da tabela.

---

## 🎯 Casos de Uso

### 1️⃣ Varejo (Loja Física)
```php
pesos: ['util' => 0.95, 'fds' => 1.50, 'feriado' => 0.00]
// Fins de semana vendem mais, feriado a loja fecha
```

### 2️⃣ B2B (Vendas)
```php
pesos: ['util' => 1.20, 'fds' => 0.50, 'feriado' => 0.20]
// Dias úteis são TOP, fins de semana pouco vende
```

### 3️⃣ SaaS/Assinatura
```php
pesos: ['util' => 1.00, 'fds' => 1.00, 'feriado' => 1.00]
// Todos os dias iguais (serviço 24/7)
```

---

## 📈 Gráfico Simples

Mostrar realizado vs projeção vs meta:

```javascript
const ctx = document.getElementById('graficoProjecao').getContext('2d');
const chart = new Chart(ctx, {
    type: 'line',
    data: {
        labels: ['Hoje', 'Projeção'],
        datasets: [
            {
                label: 'Realizado',
                data: [45000, 45000],
                borderColor: '#16a34a',
                fill: false
            },
            {
                label: 'Projeção',
                data: [45000, 64495],
                borderColor: '#dc2626',
                borderDash: [5, 5],
                fill: false,
                tension: 0.4
            },
            {
                label: 'Meta',
                data: [100000, 100000],
                borderColor: '#6b7280',
                fill: false
            }
        ]
    }
});
```

---

## ✅ Checklist

- [ ] Copiar `ProjecaoVendas.php` para `app/classes/`
- [ ] Copiar `ProjecaoVendas_Helpers.php` para `app/classes/`
- [ ] (Opcional) Criar tabela `feriados` no banco
- [ ] Adicionar require em `home_service.php`
- [ ] Chamar `calcularProjecaoVariavel()` no loop de KPIs
- [ ] Mostrar no template de KPI
- [ ] Testar com dados reais
- [ ] Ajustar pesos conforme seu negócio

---

## 🆘 Dúvidas?

- Consulte `docs/PROJECAO_VENDAS_DOCUMENTACAO.md` para detalhes completos
- Exemplos em `ProjecaoVendas_Exemplos.php`
- Helpers em `ProjecaoVendas_Helpers.php`

**Versão:** 1.0  
**Não altera:** Nenhuma tabela existente, nenhum cálculo do dashboard  
**Dependências:** PDO (se usar calendário com feriados do banco)
