# HANDOFF IA — gf_combustivelanalise (status em 2026-03-07)

## 1) Objetivo geral deste ciclo
Evolução da página `gf_combustivelanalise/index.php` para:
- corrigir consistência visual e filtros de tabela;
- corrigir origem de dados (principalmente motorista);
- reorganizar seções e remover bloco de bomba antigo;
- redesenhar Rentabilidade e Tendências;
- manter auditoria de odômetro/discrepância;
- adicionar comparação histórica no topo com **Telemetria + Bomba**.

---

## 2) Estado atual (resumo executivo)
- Página principal: `gf_combustivelanalise/index.php`.
- Backend principal de dados: `gf_combustivelanalise/select.php`.
- Layout principal já reestruturado.
- Comparação de períodos está no topo (Seção 2).
- Gráfico novo no topo adicionado: **Litros — Bomba x Telemetria (Acumulado)**.
- Seção antiga “Bomba vs Telemetria” foi removida.
- Motorista deixou de depender de `tms001_viagem` e passou a usar `tel006_deltatelemetria` diretamente.
- Fallback para Sascar adicionado para consumo por faixa RPM (quando `consumofaixa*` vier zerado).
- Lint PHP validado sem erros em `index.php` e `select.php`.

---

## 3) Estrutura atual das seções em `index.php`
Ordem atual confirmada:
1. SEÇÃO 1: KPIs RESUMO DO PERÍODO
2. SEÇÃO 2: COMPARAÇÃO DE PERÍODOS
3. SEÇÃO 3: GRÁFICOS POR TECNOLOGIA
4. SEÇÃO 4: ANÁLISE POR VEÍCULO
5. SEÇÃO 5: ANÁLISE POR MOTORISTA
6. SEÇÃO 6B: RENTABILIDADE — Faturamento vs Custo Combustível
7. SEÇÃO 7: TENDÊNCIA POR VEÍCULO
8. SEÇÃO 8: TENDÊNCIA POR MOTORISTA
9. SEÇÃO 9: AUDITORIA DE KM DISCREPANTE
10. SEÇÃO 10: EXPLICAÇÃO — MPO

Observação: seção “SEÇÃO 6: BOMBA VS TELEMETRIA” foi removida intencionalmente.

---

## 4) Alterações técnicas já feitas

### 4.1 `select.php` (dados)

#### A) Análise por motorista
- Antes: consulta dependia de `tms001_viagem`.
- Agora: consulta usa `tel006_deltatelemetria` diretamente.
- Benefício: evita vazio quando há telemetria e não há viagens em `tms001_viagem` no período.
- Filtro de conjunto aplicado via `$exists_conjunto_td`.

#### B) Fallback Sascar para “Consumo por Faixa RPM (litros)”
- Problema observado: para Sascar, campos `consumofaixa*` podem vir zerados, deixando gráfico em branco.
- Solução: quando `usa_tempo_faixa=true`, consumo por faixa total <= 0, litros totais > 0 e tempo total > 0:
  - rateia `litros_tel` proporcional ao tempo em cada faixa.
- Impacto: gráfico de consumo por faixa deixa de ficar vazio quando só há tempo por faixa disponível.

#### C) Comparação histórica com bomba
- Função `queryPeriodoResumo(...)` foi expandida.
- Além de `litros_tel`, agora retorna `litros_bomba` por período,
  calculado via subquery em `ft_controleabs` com filtro de conjunto equivalente.

---

### 4.2 `index.php` (render/layout/charts)

#### A) Reordenação
- “Comparação de Períodos” movida para cima (antes da análise gráfica por tecnologia).

#### B) Comparação de períodos (topo)
- Cards acumulados (`$periodos`) agora incluem também `litros_bomba`.
- Cards mostram:
  - km;
  - litros telemetria;
  - litros bomba;
  - % eco e veículos.
- Gráficos no topo agora em grade com 2 boxes:
  1. `chart_comparacao` (média km/l)
  2. `chart_comparacao_bomba` (litros bomba x telemetria)

#### C) Bomba vs Telemetria (seção antiga)
- Removido:
  - bloco de seção dedicado;
  - tabela de bomba por veículo nessa seção;
  - fábrica JS do gráfico antigo `chart_bomba_tel`;
  - trecho explicativo “Bomba vs Telemetria” da seção de explicação MPO.

#### D) Análise por motorista (tabela)
- Coluna renomeada de “Viagens” para “Ignições” para refletir origem em telemetria.

#### E) Rentabilidade (redesenho)
- Visual redesenhado para painel mais executivo:
  - bloco principal escuro com faturamento/margem/custo;
  - barra visual de composição margem x combustível;
  - mini-cards de indicadores ao lado do gráfico mensal.
- Mantidos:
  - gráfico mensal (`chart_rent_mensal`);
  - top 10 veículos por margem (`chart_rent_top10`);
  - tabela de rentabilidade com filtros.
- Removido donut antigo (`chart_rent_pct`).

#### F) Tendências (redesenho)
- Veículo e Motorista migrados para layout com:
  - gráfico à esquerda;
  - sidebar à direita com itens selecionáveis.
- Estado inicial: só 1 item marcado por padrão.
- Atualização dinâmica por checkbox (sem reload), datasets recriados em JS.

#### G) DataTables/header-filter
- Mantidos para tabelas ativas:
  - `tbl_veiculos`
  - `tbl_motoristas`
  - `tbl_rentabilidade`
  - `tbl_discrepantes_veiculos`
  - `tbl_discrepantes_eventos`
- `tbl_bomba_veic` removida da inicialização (pois seção foi removida).

---

## 5) Ajustes visuais e comportamento feitos antes (relevantes)
- Desalinhamento de colunas resolvido removendo `scrollX` de DataTables.
- Ordenação por clique desativada (`ordering: false`) para não conflitar com header-filter.
- Bordas de colunas + zebra + centralização forçada com `!important`.
- Filtros por coluna inicializados explicitamente após DataTables (`HeaderFilter.init(...)`).

---

## 6) Pontos de atenção / dívida técnica
1. Comentário de cabeçalho no topo de `select.php` ainda menciona motorista via `tms001_viagem` (desatualizado em relação à implementação atual).
2. Existem arquivos alternativos/backups no módulo (`index_backup.php`, `index_conjunto_hotfix_bkp.php`, `select_conjunto_hotfix_bkp.php`) que podem não refletir 100% das mudanças visuais recentes.
3. A query histórica agora usa subquery de bomba por período; em bases grandes pode exigir atenção de performance (índices em `ft_controleabs` por `empresa`, `datatransacao`, `placa`).

---

## 7) Como validar rapidamente (checklist)
1. Abrir dashboard e aplicar filtros de conjunto.
2. Conferir Seção 2 (topo):
   - cards com `l tel` e `Bomba`;
   - 2 gráficos lado a lado (média km/l + litros bomba x telemetria).
3. Conferir Seção 3 (tecnologia):
   - Sascar com gráfico de consumo por faixa preenchido (não branco quando há dados de tempo/litros).
4. Conferir Seção 5 (motorista):
   - tabela com registros;
   - coluna “Ignições”.
5. Conferir Seções 7 e 8:
   - sidebar à direita;
   - somente 1 item marcado inicialmente;
   - marcar/desmarcar atualiza linhas do gráfico.
6. Conferir ausência da seção antiga “Bomba vs Telemetria”.

---

## 8) Comandos de validação já executados
- `C:\xampp\php\php.exe -l "...\gf_combustivelanalise\select.php"`
- `C:\xampp\php\php.exe -l "...\gf_combustivelanalise\index.php"`

Status: sem erros de sintaxe.

---

## 9) Próximos passos sugeridos para a próxima IA
1. Revisar performance da subquery de `litros_bomba` em `queryPeriodoResumo` e, se necessário, otimizar com CTE/joins + índices.
2. Sincronizar (ou documentar a divergência) dos arquivos backup/hotfix.
3. Atualizar comentários desatualizados no topo de `select.php` para refletir regra atual de motorista.
4. Fazer validação funcional com dados reais em períodos com e sem Sascar para confirmar consistência do fallback.

---

## 10) Arquivo de referência anterior
Já existia: `gf_combustivelanalise/HANDOFF_IA_CONJUNTOFROTA.md`.
Este arquivo (`HANDOFF_IA_STATUS_ATUAL_2026-03-07.md`) é o snapshot mais recente do estado atual.

---

## 11) Inventário completo de métodos (adendo 2026-03-11)

Objetivo deste adendo: listar todos os métodos/funções atualmente usados nos arquivos principais da tela.

### 11.1 Métodos em `select.php` (backend)

1. `$temDelimitadorFiltro($texto)`
- Detecta se um filtro textual veio em formato de lista (vírgula, ponto e vírgula, pipe, quebra de linha).

2. `$parseFiltroLista($texto, $tipo = 'texto')`
- Converte texto de filtro em lista normalizada e sem duplicidade.
- Suporta normalização para `placa` e `numero`.

3. `$normalizarPlacasFiltro($texto)`
- Normaliza entradas de inclusão/exclusão de placas para formato alfanumérico maiúsculo.

4. `gerarPeriodoAnterior($dtinicio, $dtfim, $meses)`
- Calcula janela deslocada para comparação histórica.

5. `queryPeriodoResumo($bdcon, $codempresa, $ini, $fim, $tipoCombustivel = 1)`
- Query resumida do período (telemetria + bomba).
- Retorna km, litros telemetria, litros bomba, valor bomba, qtd abastecimentos, eventos, média, % eco.
- Agora aceita tipo de combustível para separar Diesel/Arla.

6. `$carregarRentabilidadePeriodo($ini, $fim)`
- Consolida receita, custo diesel, custo arla, litros e abastecimentos por período para comparativo rentabilidade.

7. `$calcVarPct($atual, $anterior)`
- Calcula variação percentual entre período atual e anterior, com tratamento para base zero.

8. `usort($rentabilidade_veiculos, function($a, $b){...})`
- Ordena rentabilidade por margem (desc).

9. `gf_num($v, $dec = 0)`
- Formata número no padrão pt-BR.

10. `gf_moeda($v)`
- Formata moeda no padrão `R$`.

11. `gf_pct($v)`
- Formata percentual com 1 casa.

12. `gf_score_cor($s)`
- Define cor do score por faixa de desempenho.

13. `gf_score_label($s)`
- Define rótulo textual do score (Excelente/Bom/Regular/Crítico).

14. `gf_tendencia_icon($val)`
- Renderiza indicador visual de tendência para métricas em que subir é positivo.

15. `gf_tendencia_icon_invertida($val)`
- Renderiza indicador visual de tendência para métricas em que cair é positivo.

### 11.2 Métodos em `index.php` (render/frontend)

#### A) PHP inline

1. `$splitFiltroLista($valor, $placa = false, $numerico = false)`
- Quebra filtros multi-select salvos em string para lista normalizada.

2. `$montarPeriodoAcumulado(array $lista, int $janela, string $label, string $cor)`
- Monta cartões acumulados da seção de comparação de períodos.

3. `$fmtVarRent($valor, $bomQuandoCai = false)`
- Formata variação de rentabilidade com seta, cor semântica e texto.

#### B) JavaScript global/utilitário

4. `animateValue(el, end, dur = 1200)`
- Anima contadores de KPI.

5. `calcPct(value, total)`
- Calcula percentual para labels/tooltips de gráficos.

6. `legendLabelsWithPct(labels, values, colors)`
- Gera legenda de gráfico com percentual por categoria.

#### C) Fábricas de gráficos (`chartFactories`)

7. `chartFactories[cfg.id]`
- Cria doughnut de faixas RPM por tecnologia.

8. `chartFactories[cfg.idConsumo]`
- Cria bar de consumo por faixa RPM por tecnologia.

9. `chartFactories['chart_comparacao']`
- Gráfico de comparação de média km/l por períodos acumulados.

10. `chartFactories['chart_comparacao_bomba']`
- Gráfico de litros Diesel Bomba vs Telemetria por períodos acumulados.

11. `chartFactories['chart_rent_mensal']`
- Gráfico mensal Receita vs Custo de combustível.

12. `chartFactories['chart_rent_top10']`
- Gráfico top 10 placas por rentabilidade.

13. `chartFactories['chart_tend_veic']`
- Gráfico de tendência por veículo (controlado por sidebar).

14. `chartFactories['chart_tend_mot']`
- Gráfico de tendência por motorista (controlado por sidebar).

#### D) Tendências (datasets dinâmicos)

15. `buildDatasets()` (bloco tendência veículo)
- Reconstrói datasets conforme checkboxes marcados.

16. `buildDatasets()` (bloco tendência motorista)
- Reconstrói datasets conforme checkboxes marcados.

#### E) Atalhos de período

17. `setHoje()`
- Aplica hoje em início/fim e submete filtro.

18. `setOntem()`
- Aplica ontem em início/fim e submete filtro.

19. `setMes()`
- Aplica mês atual e submete filtro.

#### F) Multi-select customizado

20. `ensureTodosOption(filtro)`
- Injeta opção “Todos” no dropdown, quando ausente.

21. `getChecksNormais(filtro)`
- Retorna checkboxes reais (exclui item “Todos”).

22. `syncTodosState(filtro)`
- Sincroniza estado de “Todos” com os itens da lista.

23. `resetBusca(filtro)`
- Limpa campo de busca do multi-select e restaura itens.

24. `fecharTodos()`
- Fecha todos os dropdowns multi-select.

25. `normalizarLista(valores)`
- Remove vazios/duplicados da seleção e normaliza saída.

26. `atualizarResumo(filtro)`
- Atualiza texto do botão e campo hidden de cada filtro multi-select.

#### G) Navegação/layout/exportação

27. `smartGoBack()`
- Volta para página anterior ou home.

28. `ajustarScroll()`
- Ajusta altura máxima da área rolável conforme viewport.

29. `exportTableToExcel(tableId, filename)`
- Exporta tabela HTML para Excel via SheetJS.

### 11.3 Inicializações e listeners relevantes

1. `IntersectionObserver` dos charts
- Criação lazy de gráficos ao entrar na viewport.

2. `IntersectionObserver` de fade/entrada
- Animação de entrada de cards, tabelas e boxes.

3. `$(document).ready(...)`
- Inicializa DataTables e `HeaderFilter` para todas as tabelas visíveis.

4. Listeners de `change`, `click`, `input`, `keydown`
- Controlam seleção dinâmica de tendências e comportamento dos filtros multi-select.

---

## 12) Observação de manutenção

- Este inventário cobre o estado atual dos arquivos principais:
  - `gf_combustivelanalise/select.php`
  - `gf_combustivelanalise/index.php`
- Em novas mudanças, atualizar esta seção para manter rastreabilidade técnica.
