# Planejador Diário de Missões e Sobreaviso

Projeto em Python para gerar a escala diária de missão acionada, missão local e sobreaviso usando Programação Linear Inteira Mista (MILP).

## 1. Estrutura do projeto

```text
dados/                    Arquivos de entrada do planejamento
resultados/               Planilhas geradas pelo planejador
src/planejador_missao/    Código-fonte Python do modelo
scripts/                  Scripts numerados de execução, validação 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          Dependências Python
Abrir Planejador.vbs      Atalho para abrir a interface sem prompt
```

A execução oficial do projeto é feita somente em Python.

## 2. Preparação do ambiente

No PowerShell, a partir da raiz do projeto:

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

A pasta `.venv` não acompanha a entrega oficial. Ela deve ser recriada pelo usuário com os comandos acima.

## 3. Como executar pelo app no navegador

Forma recomendada:

1. Dê 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:

```powershell
python web_app.py
```

O navegador abre automaticamente em `http://127.0.0.1:8050`. Se não abrir, copie esse endereço no Google Chrome.

O app permite:

- editar data e critérios de otimização;
- informar a missão de rota acionada;
- marcar condição das aeronaves;
- selecionar tripulantes disponíveis;
- consultar a aba `Quadrinhos`, com próxima OI, horas do ano, SBV e falta para 50 horas;
- salvar os arquivos de entrada em `dados/`;
- gerar a escala e abrir a última planilha.

A versão final usa Python e interface web local.

## 4. Como executar pelo terminal

Na raiz do projeto:

```powershell
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, qualificações, projetos, soldo e metas de horas. |
| `catalogo_ois.xlsx` | Catálogo de OIs por aeronave, subprograma, ordem e tipo de missão. |
| `indisponibilidades_2026.xlsx` | Períodos em que cada tripulante não pode ser escalado. |
| `parametros_missao.csv` | Data de planejamento e critérios de otimização. |
| `aeronaves_disponiveis.csv` | Condição diária de cada aeronave. |
| `rotas_acionadas.csv` | Missão de rota acionada para atendimento obrigatório. |
| `tripulantes_disponiveis.csv` | Seleção manual dos tripulantes disponíveis no dia. |
| `progresso_ois_2026.xlsx` | OIs já concluídas manualmente. |
| `historico_horas_voadas.csv` | Histórico acumulado gerado automaticamente pelo planejador. |

## 6. Saída gerada

O planejador cria uma planilha em:

```text
resultados/planejamento_diario_YYYY-MM-DD.xlsx
```

Quando já existe arquivo para a mesma data, o sistema acrescenta o horário ao nome para preservar a saída anterior.

A aba `ESCALA DIARIA` contém três blocos:

- `MISSAO ACIONADA`;
- `VOOS LOCAIS`;
- `SOBREAVISO`.

Após a solução, o arquivo `dados/historico_horas_voadas.csv` também é atualizado com horas voadas e sobreavisos registrados.

## 7. Scripts e validação com voos de 2025

O fluxo pelo VS Code pode ser executado com:

```powershell
python scripts\00_main.py --modo diario
```

Para conferir rapidamente o ambiente:

```powershell
python scripts\09_testar_instalacao.py
```

Para validar o modelo com dados históricos, coloque os voos reais de 2025 em:

```text
dados/validacao/voos_2025.csv
```

O arquivo deve ter as colunas:

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

Se a planilha `Quadro de Voo 2025 (2).xlsx` estiver em `dados/`, a validação importa a aba `VOOS` automaticamente:

```powershell
python scripts\00_main.py --validacao 2025
```

Também é possível chamar diretamente:

```powershell
python scripts\07_validacao_2025.py
```

Os relatórios são salvos em:

```text
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 contém:

- `metricas`: comparação entre escala real 2025 e escala otimizada;
- `comparativo_trips`: horas reais, horas otimizadas e delta por tripulante;
- `voos_2025_slots`: voos históricos agregados em slots;
- `escala_otimizada`: redistribuição proposta pelo MILP.

Os scripts antigos de importação/validação foram preservados em `scripts/_arquivados/`.

## 8. Método de otimização

O modelo monta previamente todas as colunas candidatas viáveis. Cada coluna representa uma possível escala de dupla para:

- rota acionada;
- missão local;
- sobreaviso.

Cada coluna recebe uma variável binária no MILP:

```text
x[i] = 1 se a coluna candidata i for escolhida
x[i] = 0 caso contrário
```

A função objetivo maximiza o score operacional, com prioridade para:

1. atender rotas acionadas;
2. aproveitar missões locais para progressão operacional;
3. escolher sobreavisos conforme o critério definido.

Restrições principais:

- cada tripulante aparece no máximo uma vez na escala;
- cada aeronave livre recebe exatamente uma cobertura principal, por rota acionada ou sobreaviso;
- cada aeronave executa no máximo uma rota acionada;
- cada aeronave executa no máximo uma missão local;
- rota acionada e missão local não podem usar a mesma aeronave no mesmo dia;
- toda rota acionada informada deve ser atendida exatamente uma vez.

O resolvedor usado é `scipy.optimize.milp`, um resolvedor exato de programação inteira disponível diretamente em Python.

## 9. Organização do código

O código em `src/planejador_missao/` está dividido por blocos funcionais:

| Arquivo | Responsabilidade |
| --- | --- |
| `data_io.py` | Leitura das planilhas/CSVs e escrita do histórico. |
| `rules.py` | Regras de disponibilidade, qualificação e progresso operacional. |
| `candidates.py` | Geração das colunas candidatas para o MILP. |
| `optimizer.py` | Formulação e solução do modelo MILP. |
| `report.py` | Registro de horas e criação da planilha Excel. |
| `quadrinhos.py` | Resumo operacional da aba Quadrinhos. |
| `validacao.py` | Validação retrospectiva com voos históricos. |
| `main.py` | Orquestração do fluxo completo. |
| `utils.py` | Normalização de textos, datas, booleanos e horas. |

Os comentários no código indicam os blocos do fluxo e as restrições relevantes do modelo, sem repetir conceitos elementares da linguagem.
