# Handoff - Reprocessamento Manual de Abastecimentos

## Objetivo

Foi iniciada a implementação de uma ação manual em `fro003_abastecimento/index.php` para permitir que o usuário reprocese abastecimentos por empresa, informando:

- `data/hora inicial`
- quantidade de dias para rodar (`1` a `5`)

A `data/hora final` é calculada automaticamente na tela, sem edição manual, e a execução é quebrada em janelas fixas de `10 horas`, porque a API bloqueia períodos maiores.

## O que foi entregue

### Tela

Arquivo: `fro003_abastecimento/index.php`

Foi adicionado:

- botão `Reprocessar Abastecimentos`
- modal para informar período
- cálculo automático da data final
- preview das tecnologias ativas da empresa
- painel de acompanhamento na própria tela
- polling de status
- cronômetro visual da execução

### Endpoints PHP

Arquivos:

- `fro003_abastecimento/reprocess_lib.php`
- `fro003_abastecimento/reprocess_meta.php`
- `fro003_abastecimento/reprocess_start.php`
- `fro003_abastecimento/reprocess_status.php`

Responsabilidades:

- centralizar helpers do reprocessamento
- consultar tecnologias ativas em `dim_apiabastecimento`
- iniciar execução em background via Python
- manter status por usuário/empresa
- expor metadados e status para a tela

### Worker Python

Arquivo:

- `fro003_abastecimento/python/reprocessar_abastecimento.py`

Responsabilidades:

- ler o payload de execução gerado pelo PHP
- dividir o período em janelas de `10h`
- rodar as tecnologias ativas da empresa
- inserir/tratar dados das APIs
- popular `ft_controleabs`
- recalcular `kmrodado`
- fazer pós-tratamentos equivalentes ao ETL, sem atualizar `tempohr`

## Tecnologias cobertas no Python

O script já contempla:

- `Connect`
- `Pro-Frotas`
- `Veloe`
- `Ticketlog`

O carregamento das tecnologias vem de `dim_apiabastecimento where status = 0`.

## Regras respeitadas

Na implementação atual:

- não usa `acao` de `apiabastecimento`
- não altera `dim_apiabastecimento.tempohr`
- executa por empresa
- processa em blocos de `10h`
- permite até `5 dias`

## Fluxo resumido

1. Usuário abre `fro003_abastecimento/index.php`.
2. Clica em `Reprocessar Abastecimentos`.
3. A tela consulta `reprocess_meta.php`.
4. O usuário informa `data_inicio` e `dias`.
5. `reprocess_start.php`:
   - valida a solicitação
   - carrega as tecnologias ativas
   - cria os arquivos de controle
   - dispara `python/reprocessar_abastecimento.py` em background
6. A tela fica consultando `reprocess_status.php`.
7. O Python atualiza o status até concluir.

## Pontos que ainda merecem validação em ambiente real

- validar o mapeamento final contra o schema real das tabelas `fro002_*` e `ft_controleabs`
- validar execução ponta a ponta com banco e APIs reais
- validar se todos os nomes de colunas no banco estão exatamente como o Python espera
- validar tempos de processamento maiores e concorrência real por empresa/usuário

## Validações já feitas

- `py_compile` do Python: OK
- revisão estrutural do fluxo PHP + JS: OK

## Arquivos temporários do reprocessamento

### Pasta de runtime da feature

Quando a rotina rodar pela primeira vez, o PHP cria automaticamente:

- `arquivos_temporarios/fro003_abastecimento_reprocess`

Nesta máquina, essa pasta ainda **não existe**, então nenhum reprocessamento real foi disparado aqui ainda.

### O que vai aparecer lá

Para cada execução, podem existir:

- `<run_id>_status.json`
  - arquivo principal de status da execução
  - a tela lê esse arquivo para mostrar progresso, logs e situação final

- `<run_id>.log`
  - log bruto do processo Python
  - útil para diagnóstico quando houver erro

- `<run_id>_config.json`
  - payload temporário gerado pelo PHP para o Python iniciar
  - contém período, empresa, usuário, conexão e serviços
  - o Python tenta apagar esse arquivo no final porque `cleanup_config = true`

- `latest_<empresa>_<usuario>.json`
  - ponteiro para a última execução daquele usuário naquela empresa
  - é usado para a tela voltar a acompanhar o último processamento

### Arquivos `.tmp`

Durante a gravação dos JSONs, o helper usa escrita atômica:

- grava primeiro em `arquivo.json.tmp`
- depois renomeia para o nome final

Então:

- `.tmp` é normal durante a escrita
- se sobrar `.tmp`, normalmente indica que o processo foi interrompido no meio da gravação

### Pode apagar?

Em geral:

- `*_config.json`: pode ser apagado após o término, e o Python já tenta fazer isso
- `*.log`: pode ser mantido para auditoria ou apagado depois
- `*_status.json`: pode ser apagado depois que não precisar mais acompanhar aquela execução
- `latest_<empresa>_<usuario>.json`: não é bom apagar se quiser manter o último vínculo de acompanhamento na tela

Se for fazer limpeza manual, o ideal é só remover arquivos de execuções já finalizadas.

## Outro temporário que existe hoje

Hoje existe também:

- `arquivos_temporarios/pycache`

Esse **não é da feature de reprocessamento em produção**. Ele apareceu porque foi feita uma validação local com:

- `python -m py_compile`

Então esse `pycache` é só cache de compilação do Python, usado na checagem de sintaxe. Pode ser apagado sem impacto funcional.

## Arquivos principais para continuar

- `fro003_abastecimento/index.php`
- `fro003_abastecimento/reprocess_lib.php`
- `fro003_abastecimento/reprocess_meta.php`
- `fro003_abastecimento/reprocess_start.php`
- `fro003_abastecimento/reprocess_status.php`
- `fro003_abastecimento/python/reprocessar_abastecimento.py`

## Observação final

O ETL Pentaho usado como referência foi:

- `C:\Users\Lenovo\Documents\projetos\etl\transformacao\dellmar\abastecimento\abastecimento.kjb`

Mas a implementação atual foi direcionada para o que você pediu:

- tratar a carga das APIs em Python
- inserir/tratar dados
- reprocessar `ft_controleabs`
- recalcular `kmrodado`
- sem mexer em `tempohr`
