# HANDOFF PARA IA - Adequação da tela `gf_combustivelanalise` para `dim_conjuntofrota`

## 1) Contexto do problema

Na tela `gf_combustivelanalise`, existem casos de veículos em abastecimento (`ft_controleabs`) que não aparecem de forma consistente na telemetria / análise, porque o filtro base atual ainda depende muito de `dim_veiculostelemetria` e cruzamentos indiretos.

Foi criado no outro projeto o serviço `int_base_conjuntoveic` para garantir consistência histórica em `dim_conjuntofrota`.

A partir de agora, **a base mestra da tela deve ser o conjunto**.

---

## 2) Objetivo funcional (obrigatório)

1. **Veículo só entra na análise se existir em `dim_conjuntofrota`** para a empresa e período analisado.
2. **Filtros da tela devem refletir o conjunto no período** (inclusive motorista, centro de custo etc.).
3. A análise deve conversar com a vigência histórica (`dtinicio`/`dtfim`) da `dim_conjuntofrota`.
4. Manter o layout e comportamento geral da página, mudando a camada de seleção de dados.

---

## 3) Arquivos-alvo desta tela

- `gf_combustivelanalise/select.php` (principal: SQLs e filtros)
- `gf_combustivelanalise/filtro.php` (labels/ajustes de entendimento dos filtros)
- `gf_combustivelanalise/index.php` (se precisar ajustar rótulos explicativos no topo)

Arquivos `*_backup.php` podem ser ignorados.

---

## 4) Estado atual que precisa mudar

Hoje em `select.php`:
- Base de telemetria usa `tel006_deltatelemetria td` + `dim_veiculostelemetria dv`.
- Filtros adicionais (`placa`, `centrocusto`, `classificacao`) são aplicados em `dv`.
- Bloco de motorista usa `jor005_jornada` para mapear motorista x veículo.
- Bloco de bomba (`ft_controleabs`) não está ancorado na vigência do conjunto.

Isso gera inconsistência com o objetivo novo.

---

## 5) Regra de negócio nova para a tela

### Regra mestra
Criar uma CTE base do período, por empresa:
- `conjunto_periodo`: linhas da `dim_conjuntofrota` que intersectam o período filtrado.

Interseção de período:
- `dc.dtinicio <= :dtfim_fim_do_dia`
- `COALESCE(dc.dtfim, '9999-12-31') >= :dtinicio_inicio_do_dia`

### Filtro principal
Todas as análises devem usar **somente veículos presentes em `conjunto_periodo`**.

### Filtros da UI
Aplicar preferencialmente no conjunto do período:
- placa: via `dim_veiculostelemetria` (apenas para exibição e busca textual)
- motorista: via `dim_conjuntofrota.idmotorista` + `dim_motorista.nome`
- centro de custo: via `dim_conjuntofrota.idcentrocusto` + `dim_centrocusto.descricao`
- classificação: continua em `dim_veiculostelemetria.classificacao`

### Bloco de motorista
Trocar lógica que hoje vem da jornada para basear no conjunto:
- motorista deve ser aquele vigente no `dim_conjuntofrota` no período da análise.
- Evitar usar `jor005_jornada` como fonte principal nesta tela.

### Bloco de abastecimento (bomba)
`ft_controleabs` deve ser restringido a veículos que existam no conjunto vigente para a data da transação.

Sugestão segura (evita duplicidade): usar `EXISTS` com subquery em `dim_conjuntofrota` correlacionando por veículo/empresa/data.

---

## 6) Implementação sugerida (passo a passo)

## Passo A - CTE base do conjunto
No topo de `select.php`, montar CTE lógica reaproveitável (ou SQL string base):

- `conjunto_periodo` com colunas mínimas:
  - `empresa`, `idveiculo`, `idmotorista`, `idcentrocusto`, `idgestor`, `tiporastreador`, `dtinicio`, `dtfim`
- joins auxiliares para filtros:
  - `dim_veiculostelemetria dv` (placa/classificação)
  - `dim_motorista dm`
  - `dim_centrocusto dcc`

Aplicar os filtros de UI nesse contexto.

## Passo B - Telemetria por veículo
Nos SQLs que usam `tel006_deltatelemetria td`, incluir:
- join/exists com `conjunto_periodo` por `td.idveiculo` e vigência de `td.dtinicio` dentro da janela do conjunto.
- remover dependência de `dv` como filtro mestre.

## Passo C - Bloco motorista
Substituir seção atual (jornada) por agregação a partir do conjunto:
- construir mapa `motorista -> veículos` via `conjunto_periodo`.
- agregar telemetria por esse mapa (como já é feito hoje, mas sem jornada).

## Passo D - Bloco bomba
Nos SQLs de `ft_controleabs`:
- manter data/empresa/status,
- adicionar restrição para considerar somente transações de veículos presentes no conjunto para a data do abastecimento.
- quando preciso casar por placa, passar por `dim_veiculostelemetria` e validar com `conjunto_periodo`.

## Passo E - Filtro.php / Index.php
Ajustar textos para deixar claro:
- análise é baseada no conjunto histórico vigente no período.
- filtro de motorista refere-se ao motorista de `dim_conjuntofrota`.

---

## 7) Critérios de aceite

1. Veículo sem histórico em `dim_conjuntofrota` não aparece em nenhum KPI/tabela da tela.
2. Filtro de motorista reflete dados do conjunto no período, não da jornada.
3. Filtro de centro de custo reflete `idcentrocusto` do conjunto.
4. Abastecimentos considerados na análise pertencem a veículos válidos no conjunto (na data).
5. Quantidades entre painéis (veículos, motorista, bomba) ficam coerentes com o mesmo universo base.
6. Performance aceitável para período mensal.

---

## 8) Query de validação rápida (manual)

Depois da mudança, validar universo da tela com algo como:

```sql
WITH conjunto_periodo AS (
    SELECT dc.idveiculo
    FROM dim_conjuntofrota dc
    WHERE dc.empresa = :empresa
      AND dc.dtinicio <= :dtfim_fim
      AND COALESCE(dc.dtfim, '9999-12-31'::timestamp) >= :dtinicio_ini
    GROUP BY dc.idveiculo
)
SELECT COUNT(*) AS total_veiculos_base
FROM conjunto_periodo;
```

E comparar com o total de veículos realmente usados pelos blocos principais da página.

---

## 9) Observações importantes para a IA aplicadora

- Não quebrar o front (KPIs, gráficos e tabelas devem continuar funcionando).
- Priorizar consistência de base antes de micro-otimizações.
- Evitar mudanças fora de `gf_combustivelanalise` neste primeiro ciclo.
- Manter compatibilidade com os filtros já persistidos (`filtros_db.php`).

---

## 10) Resultado esperado final

Tela `gf_combustivelanalise` totalmente consistente com `dim_conjuntofrota`, usando conjunto como filtro maior de veículos e como referência de atributos no período (especialmente motorista), reduzindo divergências entre abastecimento, telemetria e cadastros.
