Escalante-Pastor/README.md

Planejador Diario de Missoes e Sobreaviso

Projeto em Python para gerar a escala diaria de missao acionada, missao local e sobreaviso usando Programacao Linear Inteira Mista (MILP).

1. Estrutura do projeto

dados/                    Arquivos de entrada do planejamento
resultados/               Planilhas geradas pelo planejador
src/planejador_missao/    Codigo-fonte Python do modelo
scripts/                  Scripts numerados de execucao, validacao e teste
.vscode/                  Arquivos de workspace do VS Code
web_app.py                Interface web HTML para abrir no navegador
run_planner.py            Ponto de entrada para executar o planejamento
requirements.txt          Dependencias Python
Abrir Planejador.vbs      Atalho para abrir a interface sem prompt

A execucao oficial do projeto e feita somente em Python.

2. Preparacao do ambiente

No PowerShell, a partir da raiz do projeto:

cd "C:\caminho\para\planejador_missao_limpo_milp"
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt

A pasta .venv nao acompanha a entrega oficial. Ela deve ser recriada pelo usuario com os comandos acima.

3. Como executar pelo app no navegador

Forma recomendada:

1. De dois cliques em Abrir Planejador.vbs.
2. Aguarde o navegador abrir em http://127.0.0.1:8050.

Se preferir executar manualmente pelo PowerShell, use:

Na raiz do projeto:

python web_app.py

O navegador abre automaticamente em http://127.0.0.1:8050. Se nao abrir, copie esse endereco no Google Chrome.

O app permite:

• editar data e criterios de otimizacao;
• informar a missao de rota acionada;
• marcar condicao das aeronaves;
• selecionar tripulantes disponiveis;
• consultar a aba Quadrinhos, com proxima OI, horas do ano, SBV e falta para 50 horas;
• salvar os arquivos de entrada em dados/;
• gerar a escala e abrir a ultima planilha.

A versao final usa Python e interface web local.

4. Como executar pelo terminal

Na raiz do projeto:

python scripts\00_main.py

Ao final, o programa informa:

• data de planejamento usada;
• caminho da planilha Excel gerada;
• quantidade de colunas candidatas criadas;
• quantidade de escalas selecionadas pelo MILP.

5. Arquivos de entrada

Os arquivos de entrada ficam em dados/.

Arquivo	Finalidade
Modelagem_C98_ETA2_local.xlsx ou Modelagem C98 ETA2.xlsx	Cadastro base de tripulantes, qualificacoes, projetos, soldo e metas de horas.
catalogo_ois.xlsx	Catalogo de OIs por aeronave, subprograma, ordem e tipo de missao.
indisponibilidades_2026.xlsx	Periodos em que cada tripulante nao pode ser escalado.
parametros_missao.csv	Data de planejamento e criterios de otimizacao.
aeronaves_disponiveis.csv	Condicao diaria de cada aeronave.
rotas_acionadas.csv	Missao de rota acionada para atendimento obrigatorio.
tripulantes_disponiveis.csv	Selecao manual dos tripulantes disponiveis no dia.
progresso_ois_2026.xlsx	OIs ja concluidas manualmente.
historico_horas_voadas.csv	Historico acumulado gerado automaticamente pelo planejador.

6. Saida gerada

O planejador cria uma planilha em:

resultados/planejamento_diario_YYYY-MM-DD.xlsx

Quando ja existe arquivo para a mesma data, o sistema acrescenta o horario ao nome para preservar a saida anterior.

A aba ESCALA DIARIA contem tres blocos:

• MISSAO ACIONADA;
• VOOS LOCAIS;
• SOBREAVISO.

Apos a solucao, o arquivo dados/historico_horas_voadas.csv tambem e atualizado com horas voadas e sobreavisos registrados.

7. Scripts e validacao com voos de 2025

O fluxo pelo VS Code pode ser executado com:

python scripts\00_main.py --modo diario

Para conferir rapidamente o ambiente:

python scripts\09_testar_instalacao.py

Para validar o modelo com dados historicos, coloque os voos reais de 2025 em:

dados/validacao/voos_2025.csv

O arquivo deve ter as colunas:

data,aeronave,tipo_escala,tripulante,funcao,oi,horas_voadas,sbv

Se a planilha Quadro de Voo 2025 (2).xlsx estiver em dados/, a validacao importa a aba VOOS automaticamente:

python scripts\00_main.py --validacao 2025

Tambem e possivel chamar diretamente:

python scripts\07_validacao_2025.py

Os relatorios sao salvos em:

resultados/validacao/validacao_2025_resumo.xlsx
resultados/validacao/validacao_2025_detalhada.xlsx
resultados/validacao/validacao_2025_metricas.csv
resultados/validacao/validacao_2025_barras.png

Ele contem:

• metricas: comparacao entre escala real 2025 e escala otimizada;
• comparativo_trips: horas reais, horas otimizadas e delta por tripulante;
• voos_2025_slots: voos historicos agregados em slots;
• escala_otimizada: redistribuicao proposta pelo MILP.

Os scripts antigos de importacao/validacao foram preservados em scripts/_arquivados/.

8. Metodo de otimizacao

O modelo monta previamente todas as colunas candidatas viaveis. Cada coluna representa uma possivel escala de dupla para:

• rota acionada;
• missao local;
• sobreaviso.

Cada coluna recebe uma variavel binaria no MILP:

x[i] = 1 se a coluna candidata i for escolhida
x[i] = 0 caso contrario

A funcao objetivo maximiza o score operacional, com prioridade para:

1. atender rotas acionadas;
2. aproveitar missoes locais para progressao operacional;
3. escolher sobreavisos conforme o criterio definido.

Restricoes principais:

• cada tripulante aparece no maximo uma vez na escala;
• cada aeronave livre recebe exatamente uma cobertura principal, por rota acionada ou sobreaviso;
• cada aeronave executa no maximo uma rota acionada;
• cada aeronave executa no maximo uma missao local;
• rota acionada e missao local nao podem usar a mesma aeronave no mesmo dia;
• toda rota acionada informada deve ser atendida exatamente uma vez.

O resolvedor usado e scipy.optimize.milp, um resolvedor exato de programacao inteira disponivel diretamente em Python.

9. Organizacao do codigo

O codigo em src/planejador_missao/ esta dividido por blocos funcionais:

Arquivo	Responsabilidade
data_io.py	Leitura das planilhas/CSVs e escrita do historico.
rules.py	Regras de disponibilidade, qualificacao e progresso operacional.
candidates.py	Geracao das colunas candidatas para o MILP.
optimizer.py	Formulacao e solucao do modelo MILP.
report.py	Registro de horas e criacao da planilha Excel.
quadrinhos.py	Resumo operacional da aba Quadrinhos.
validacao.py	Validacao retrospectiva com voos historicos.
main.py	Orquestracao do fluxo completo.
utils.py	Normalizacao de textos, datas, booleanos e horas.

Os comentarios no codigo indicam os blocos do fluxo e as restricoes relevantes do modelo, sem repetir conceitos elementares da linguagem.