aircraftrouting_arara/README.md

# OARMP — Aircraft Routing & Maintenance Planning

Sistema de otimização de roteamento de aeronaves com planejamento integrado de manutenção, desenvolvido para o Curso de Especialização em Administração de Organizações (CEAO 809).

## Visão geral

O OARMP resolve o problema de atribuição de aeronaves a fragmentos de voo (OFRAGs) respeitando as restrições de **Time to Maintenance (TTM)** de cada aeronave, minimizando as horas perdidas de TTM ao longo do planejamento.

### Formulação matemática

**Set Partitioning com Column Generation + Branch & Bound**

```
Minimizar   Σ_r  c_r · x_r                          (perda total de TTM)
s.a.        Σ_{r: j∈r}  x_r  = 1   ∀ j ∈ OFRAGs   (cada OFRAG coberto exatamente uma vez)
            Σ_{r: a(r)=a} x_r ≤ 1  ∀ a ∈ Aeronaves (uma rota por aeronave)
            x_r ∈ {0, 1}
```

O subproblema de precificação (pricing) é resolvido por **programação dinâmica (label-setting DP)** sobre o DAG de OFRAGs ordenados por horário de partida.

## Estrutura do projeto

```
arara_oarmp/
├── app/
│   └── dashboard.py          # Interface Streamlit (entrada de dados + resultados)
├── raw/                      # Dados de entrada (CSV)
│   ├── AERONAVES.csv
│   ├── CHECKS.csv
│   ├── AIRPORTS.csv
│   └── ESCALA DE VOO MODELO 1.csv
├── src/
│   └── routing_engine/
│       ├── config.py         # Parâmetros e caminhos
│       ├── ingest.py         # Leitura e normalização dos dados
│       ├── inspect_files.py  # Detecção automática de colunas (sinônimos)
│       ├── network_generator.py  # Grafo de adjacência entre OFRAGs
│       ├── optimizer.py      # CG + B&B (PuLP/CBC)
│       ├── maintenance_monitor.py  # Validação TTM e eventos de manutenção
│       ├── metrics.py        # Tabelas e sumários de saída
│       ├── pipeline.py       # Orquestração end-to-end
│       └── quality.py        # Verificações de qualidade dos dados
├── scripts/                  # Scripts auxiliares de inspeção e execução
├── outputs/                  # Resultados gerados pelo pipeline
│   ├── schedules/
│   └── exports/
├── requirements.txt
└── run_pipeline.bat
```

## Instalação

```bash
# Criar ambiente virtual
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/Mac

# Instalar dependências
pip install -r requirements.txt
```

### Dependências principais

| Pacote | Uso |
|--------|-----|
| `pulp` | Formulação e resolução do MIP (solver CBC) |
| `pandas` / `numpy` | Manipulação de dados |
| `streamlit` | Dashboard interativo |
| `plotly` | Gráficos (Gantt, barras) |
| `folium` + `streamlit-folium` | Mapa interativo de rotas |
| `airportsdata` | Coordenadas geográficas de aeroportos por ICAO |
| `networkx` | Grafo de adjacência entre OFRAGs |

## Execução

### Via dashboard (recomendado)

```bash
streamlit run app/dashboard.py
```

### Via script de linha de comando

```bash
python scripts/03_run_optimization_pipeline.py
# ou
run_pipeline.bat
```

## Dados de entrada

Todos os arquivos ficam em `raw/` com separador `;`:

### AERONAVES.csv
| Campo | Descrição |
|-------|-----------|
| MATRICULA | Indicativo da aeronave |
| MODELO | Modelo (ex: C105) |
| FH TOTAIS | Horas de voo totais acumuladas |

### CHECKS.csv
| Campo | Descrição |
|-------|-----------|
| CHECKS | Nome do check |
| FH | Threshold cumulativo de FH para o check |
| TEMPO DE EXECUCAO (DIAS) | Duração do check em dias |
| LOCAL DE EXECUCAO | Código ICAO da base de manutenção |

### AIRPORTS.csv
| Campo | Descrição |
|-------|-----------|
| AIRPORT_CODE | Código ICAO |
| AIRPORT_NAME | Nome do aeroporto |
| IS_MAINTENANCE_BASE | 1 = base de manutenção |

### ESCALA DE VOO MODELO 1.csv
Escala de missões com colunas: `DATA`, `ETAPA`, `DEP`, `ARR`, `HORA_DEP`, `HORA_ARR`, `TEMPO_VOO`, `SEGMTO`, `MISSAO`, `OFRAG`.  
Formato de data aceito: `DD/MM/AAAA` ou `DD/mon` (ex: `15/jan`).

## Dashboard — abas

### Entrada (📥 Input)
- **Escala de Voo**: tabela editável com adição/remoção de linhas
- **Aeronaves**: frota com FH totais e TAT mínimo
- **Checks**: thresholds e durações de manutenção
- **Bases de Manutenção**: aeroportos habilitados para check

### Saída (📤 Output)
- **Resumo**: métricas gerais + diagrama de Gantt
- **Escala com Atribuição**: escala original com aeronave atribuída por OFRAG
- **Manutenção e Aeronaves**: eventos de manutenção, gráfico de FH por aeronave (FH iniciais + planejadas antes/após manutenção + TTM disponível)
- **Frota**: utilização percentual do TTM por aeronave
- **Mapa**: rotas por aeronave em mapa interativo (satélite Esri / CartoDB)

## Conceitos-chave

**OFRAG** — Fragmento de voo: conjunto de etapas que sai e retorna à base de manutenção. Unidade de alocação do problema.

**TTM (Time to Maintenance)** — Horas de voo disponíveis até o próximo check obrigatório. Cada ciclo de check tem seu próprio TTM.

**TTM Loss** — Horas de TTM não utilizadas quando a manutenção é realizada antes de esgotar o ciclo (inevitável quando o próximo OFRAG excederia o limite).

**TAT (Turnaround Time)** — Tempo mínimo entre o pouso de um OFRAG e a decolagem do seguinte na mesma aeronave.