Add OARMP routing engine, dashboard and documentation

- Complete routing engine: ingest, optimizer (CG+B&B), maintenance
  monitor, metrics, pipeline, quality checks
- Streamlit dashboard with Input/Output tab structure, editable data
  editors, interactive Folium map with satellite layer and maintenance
  base highlights, FH stacked bar chart with TTM availability
- CSV data files: AERONAVES, CHECKS, AIRPORTS, ESCALA DE VOO
- README, CONTEXTO and CHANGELOG added
- Remove legacy pre_process scripts and raw binary files (PDFs/xlsx)
- Update .gitignore to exclude outputs/, data/, raw/*.pdf, raw/*.xlsx

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CONTEXTO.md

@@ -1,50 +1,64 @@
-# Contexto do Projeto
+# Contexto do Projeto — OARMP
 
-## Objetivo
+## Origem e motivação
 
-Organizar, preservar e processar documentos relacionados ao projeto `arara_oarmp`, mantendo rastreabilidade das alterações e separando arquivos originais, intermediários e processados.
+O OARMP nasceu da necessidade de apoiar o planejamento de emprego da frota de aeronaves C-105 Amazonas no âmbito do CEAO 809. A gestão manual da escala de voo — realizada em planilhas — não garante o respeito sistemático aos intervalos de manutenção (TTM), o que pode resultar em aeronaves com check vencido, indisponibilidade não planejada ou perda desnecessária de horas de TTM.
 
-## Estrutura de Pastas
+O sistema automatiza a atribuição de aeronaves a missões, respeitando os checks programados e minimizando o desperdício de horas de vida útil de manutenção.
 
-- `raw/`: arquivos originais, sem alteração.
-- `pre_process/`: scripts e saídas intermediárias de pré-processamento.
-- `processed/`: dados finais limpos, consolidados ou prontos para análise.
-- `docs/`: documentação técnica, autoria e histórico de versões.
+## Contexto operacional
 
-## Arquivos de Documentação
+### Aeronaves
 
-- `README.md`: guia inicial para colaboradores e uso básico do repositório.
-- `CONTEXTO.md`: orientações permanentes e combinados de trabalho.
-- `LOG.md`: diário operacional detalhado, com data, hora, autor, ação, arquivos e observações.
-- `docs/about.md`: documentação técnica do projeto, fluxo de dados, limitações e oportunidades de melhoria.
-- `docs/authors.md`: autoria, colaboradores e regras de contribuição.
-- `docs/changelog.md`: histórico resumido de versões significativas.
+A frota considerada é composta por aeronaves **C-105 Amazonas** (Embraer KC-390 regional), operadas no transporte logístico e de pessoal na região amazônica. Cada aeronave possui um histórico acumulado de horas de voo (FH Totais) que determina a proximidade ao próximo check.
 
-## Colaboradores
+### Checks de manutenção
 
-- `VTO`: Vitor Cesa.
-- `GNR`: Generoso.
-- `JOM`: João Marcos.
+Os checks são definidos por **thresholds cumulativos de FH** (ex: 300 h, 400 h, 600 h, 900 h). Quando uma aeronave atinge o threshold de seu ciclo atual, ela deve ser submetida ao check correspondente antes de continuar voando. A manutenção é realizada exclusivamente nas **bases habilitadas** (campo `IS_MAINTENANCE_BASE = 1` em AIRPORTS.csv).
 
-## Orientações de Trabalho
+### OFRAGs
 
-- Manter documentos originais sempre em `raw/`.
-- Não alterar arquivos dentro de `raw/`; quando necessário, gerar cópias ou saídas em `pre_process/`.
-- Registrar no `LOG.md` toda entrada, alteração, processamento ou decisão relevante.
-- Registrar em `docs/changelog.md` mudanças significativas de versão, como novo parser, novo conjunto de dados, mudança estrutural ou nova funcionalidade.
-- Usar o formato de log com data, hora, tag do colaborador e descrição objetiva da ação.
-- Registrar a origem de cada documento, quando conhecida.
-- Informar scripts executados e parâmetros importantes.
-- Registrar quantidade de registros extraídos, descartados, corrigidos ou validados.
-- Registrar problemas encontrados nos arquivos originais, como erros de digitação, páginas ilegíveis, campos ausentes ou tabelas quebradas.
-- Registrar decisões de padronização, por exemplo nomes de colunas, unidades, formatos de data e tratamento de acentos.
-- Explicitar os critérios usados para mover dados de `pre_process/` para `processed/`.
-- Atualizar `docs/about.md` quando o fluxo técnico, campos extraídos ou limitações conhecidas mudarem.
+Um OFRAG (fragmento de voo) é um conjunto de etapas que **parte da base de manutenção e retorna a ela**. Essa restrição é fundamental: apenas OFRAGs com início e fim na base podem ser alocados no problema de otimização, pois garantem que a aeronave pode ser submetida a check entre missões.
 
-## Formato Recomendado do Log
+### Escala de voo
 
-```text
-| Data | Hora | Autor | Ação | Arquivos | Observações |
-| --- | --- | --- | --- | --- | --- |
-| 2026-06-15 | 15:41 | VTO | Pré-processou PDF de inspeções | raw/documento.pdf; pre_process/saida.csv | 18 inspeções extraídas |
-```
+A escala é fornecida no formato da planilha operacional da unidade, com etapas identificadas por data, aeroportos de partida/chegada, horários e número de OFRAG. O sistema aceita datas no formato `DD/MM/AAAA` ou no formato legado `DD/mon` (ex: `15/jan`).
+
+## Problema de otimização
+
+O problema é modelado como **Set Partitioning** sobre o conjunto de OFRAGs:
+
+- Cada OFRAG deve ser coberto por exatamente uma aeronave
+- Cada aeronave executa no máximo uma rota (sequência de OFRAGs)
+- A rota deve ser TTM-viável: a qualquer ponto, as FH acumuladas desde o último check não excedem o TTM do ciclo atual
+- A função objetivo minimiza a **perda total de TTM** (horas de TTM não utilizadas quando a manutenção é antecipada)
+
+A solução é obtida por **Column Generation** (geração de colunas) combinada com **Branch & Bound** (PuLP/CBC), permitindo explorar um espaço de rotas potencialmente exponencial de forma eficiente.
+
+## Decisões de projeto
+
+| Decisão | Justificativa |
+|---------|---------------|
+| Set Partitioning (ao invés de Set Covering) | Garante que cada missão seja atribuída a exatamente uma aeronave, sem ambiguidade |
+| Column Generation | O número de rotas viáveis é exponencial; CG constrói apenas colunas lucrativas |
+| Pricing por DP (label-setting) | Subproblema é um shortest-path com restrições de recursos (TTM), adequado para DP em DAG |
+| TAT mínimo (padrão 60 min) | Garante tempo mínimo de preparação entre OFRAGs consecutivos na mesma aeronave |
+| Penalidade Big-M por OFRAG descoberto | Permite solução mesmo quando a cobertura total é inviável (ex: mais OFRAGs do que aeronaves disponíveis) |
+
+## Limitações conhecidas
+
+- O modelo considera apenas um evento de manutenção por ciclo de check; múltiplos checks consecutivos são tratados como ciclos independentes
+- A duração da manutenção é fixa por tipo de check; variações logísticas (falta de peças, disponibilidade de hangar) não são modeladas
+- OFRAGs que não partem e chegam à base de manutenção são excluídos do problema (não podem ser alocados)
+- O solver CBC tem desempenho limitado para instâncias muito grandes; o parâmetro `mip_time_limit_seconds` controla o tempo máximo
+
+## Arquivos de referência
+
+| Arquivo | Conteúdo |
+|---------|----------|
+| `raw/AERONAVES.csv` | Frota com FH acumuladas |
+| `raw/CHECKS.csv` | Thresholds e durações dos checks |
+| `raw/AIRPORTS.csv` | Aeroportos e bases de manutenção |
+| `raw/ESCALA DE VOO MODELO 1.csv` | Escala de missões |
+| `raw/ICA 66-31 2023.pdf` | Instrução regulatória de aeronavegabilidade (referência) |
+| `raw/Airline Operations and Scheduling*.pdf` | Referência bibliográfica principal (Bazargan, 2010) |