arara_oarmp/docs/about.md

# Documentação Técnica — Arara OAMRP

## O que é

O Arara OAMRP é um projeto para organizar dados, documentos e modelos usados no planejamento e acompanhamento operacional do Esquadrão Arara, em Manaus.

O objetivo é construir uma base rastreável para encaixar missões, aeronaves e manutenções, começando pela leitura e estruturação de documentos operacionais e de manutenção.

Nesta fase inicial, o projeto contém:

- documentos originais em `db/raw/`;
- scripts e saídas intermediárias em `db/pre_process/`;
- área reservada para dados finais em `db/processed/`;
- protótipos de otimização e análise em `software/`;
- documentação de contexto, autoria, mudanças e rastreabilidade.

## Fontes de dados

As fontes atuais são documentos operacionais e de manutenção adicionados manualmente ao repositório.

Fonte inicial processada:

| Arquivo | Conteúdo | Observação |
| --- | --- | --- |
| `db/raw/relatorio_ciclo_inspecoes_c105_2805_2026-06-15.pdf` | Relatório de ciclo de inspeções do equipamento | Aeronave C-105, matrícula 2805, relatório de 2026-06-15 |

Arquivos originais devem permanecer em `db/raw/` sem edição direta.

## Como funciona

O fluxo atual é:

1. Guardar documentos originais em `db/raw/`.
2. Executar scripts de extração e padronização em `db/pre_process/`.
3. Gerar saídas intermediárias em texto, JSON e CSV.
4. Manter campos originais para rastreabilidade.
5. Separar campos discretos úteis para cálculo, comparação e planejamento.
6. Registrar mudanças relevantes em `LOG.md`.
7. Consolidar dados finais em `db/processed/` quando os critérios de qualidade estiverem definidos.
8. Desenvolver protótipos e modelos em `software/`, mantendo dados e código separados.

## Pré-processamento atual

O script `db/pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/preprocess_pdf.py` lê o relatório de ciclo de inspeções em PDF e gera:

```text
db/pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_texto.txt
db/pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.json
db/pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.csv
```

## Modelo OAMRP v3 (modelo atual)

O arquivo `software/oamrp_v3.py` é o modelo principal. Implementa o *Operational Aircraft Maintenance Routing Problem* (Al-Thani, Ben Ahmed, Haouari, 2016, Transportation Research Part C, vol. 72, pp. 29–44) sobre uma rede espaço-tempo com arcos de ferry.

### Rede espaço-tempo

A rede tem quatro tipos de nó:

| Tipo | Descrição |
| --- | --- |
| `origem` | Nó de partida de cada aeronave (base inicial, t=0) |
| `missao` | Uma missão específica; `aeronave_id=None` (qualquer aeronave pode voar) |
| `inspecao` | Nó de manutenção; exclusivo de uma aeronave (`aeronave_id=k`) |
| `sumidouro` | Nó de chegada ao fim do horizonte |

Os arcos são: `inicio`, `missao_missao`, `missao_insp`, `insp_missao`, `missao_fim` e `ferry` (quando bases forem distintas). Ferry usa velocidade 430 km/h e distância haversine.

### Nomenclatura (Al-Thani, 2016)

| Símbolo | Significado | Campo no código |
| --- | --- | --- |
| F | Intervalo máximo legal entre manutenções | `InspecaoParam.f_max` |
| f_k | Horas acumuladas no início | `Aeronave.f0` |
| LRT = F − f_k | Tempo legal restante (decresce) | `lrt_inicial()` |
| H[k,i,nid] | Horas acumuladas em tempo real (cresce, reseta na inspeção) | `H[k,seq,nid]` |

### Restrições implementadas

- **C1**: cada missão coberta por no máximo uma aeronave.
- **C2**: conservação de fluxo em nós de missão e inspeção.
- **C3**: continuidade espacial (base de chegada = base de partida do próximo arco; ferry gerado automaticamente).
- **C4**: continuidade temporal (partida ≥ chegada + TAT 1,5h).
- **C5**: missões EVAM (`obrigatoria=True`) devem ser cumpridas.
- **C6**: `H[k,i,nid] ≤ f_max` para cada tipo de inspeção, com reset após nó de inspeção.
- **C9**: downtime de inspeção (aeronave fica indisponível durante o slot de manutenção).
- **C11**: slot único de inspeção por base — no máximo uma aeronave em manutenção a cada instante.

### Objetivos

- **L1**: maximizar cobertura ponderada `Σ prioridade_m × z_m` (missões cobertas).
- **L2**: maximizar horas voadas, dado o L1 fixado.

### Execução típica

```powershell
python software/oamrp_v3.py --sintetico --seed 42 --aleatorio --ofrag db/processed/ofrag.csv
```

Gera missões sintéticas cross-base, sorteia `f0` aleatório e carrega prioridades do OFRAG.

### Scripts auxiliares

| Script | Função |
| --- | --- |
| `software/gerar_ofrag.py` | Gera `db/processed/ofrag.csv` com ordens de missão (OFRAG), prioridades 1–5 e tipo |
| `software/visualizar_resultado.py` | Lê o CSV de resultado e gera `db/processed/mapa_rotas.html` (mapa Folium interativo) |

### Resultado validado (2026-06-16)

Rodada sintética com 50 missões, seed 42, horas iniciais aleatórias e OFRAG: 50/50 missões cumpridas, solver CBC Optimal, todas as 4 EVAMs operacionais.

---

## Modelo OAMRP v1 (protótipo inicial)

O arquivo `software/oamrp_v1.py` contém o protótipo inicial, substituído pelo v3. Mantido no repositório para referência histórica.

Campos extraídos e estruturados:

| Campo | Conteúdo |
| --- | --- |
| `seq` | Sequência da inspeção no relatório |
| `sigla_mnt` | Sigla da manutenção |
| `descricao_mnt` | Descrição da manutenção |
| `referencia` | Referência textual da inspeção |
| `tipo_vencimento` | Tipo de vencimento |
| `zera_tso` | Coluna original `Zera TSO` |
| `letra` | Letra da inspeção, quando preenchida |
| `nivel` | Código do nível |
| `nivel_descricao` | Descrição do nível |
| `var_media` | Variação média informada no relatório |
| `duracao` | Duração original, por exemplo `3 D` ou `6 H` |
| `duracao_valor` | Valor numérico da duração |
| `duracao_unidade` | Unidade normalizada: `dias` ou `horas` |
| `controle_original` | Trecho original usado para rastreabilidade |
| `intervalo_horas_voo` | Intervalo textual em horas de voo |
| `intervalo_horas_voo_valor` | Valor numérico de horas de voo |
| `intervalo_meses_continuos` | Intervalo textual em meses contínuos |
| `intervalo_meses_continuos_valor` | Valor numérico de meses contínuos |
| `intervalo_pousos` | Intervalo textual em pousos |
| `intervalo_pousos_valor` | Valor numérico de pousos |
| `linha_original` | Linha reconstruída a partir do texto extraído |

## Convenções operacionais

Níveis de manutenção:

| Código | Descrição |
| --- | --- |
| `B` | Base |
| `P` | Parque |
| `O` | Orgânico |

Unidades de duração:

| Código | Descrição |
| --- | --- |
| `D` | Dias |
| `H` | Horas |

## Limitações conhecidas

1. A extração depende da qualidade do PDF e do texto recuperado por `pdfplumber`.
2. O parser foi calibrado para o layout atual do relatório de ciclo de inspeções.
3. Mudanças no formato do relatório podem exigir ajuste no script.
4. A grafia original é preservada, inclusive erros existentes no documento fonte.
5. Ainda não há validação cruzada com outros sistemas ou fontes oficiais.
6. O modelo em `software/oamrp_v1.py` ainda é protótipo e usa dados de exemplo a substituir por bases reais.
7. Ainda não há modelo final em `db/processed/` para integração completa entre missões, aeronaves e manutenções.

## Oportunidades de melhoria

| Prioridade | Melhoria |
| --- | --- |
| Alta | Definir o modelo final de dados em `db/processed/` |
| Alta | Criar uma tabela mestre de aeronaves |
| Alta | Criar uma tabela mestre de missões |
| Alta | Definir regras para cálculo de vencimento por horas, meses e pousos |
| Média | Criar testes automatizados para o parser de PDF |
| Média | Padronizar nomes de colunas entre todos os documentos |
| Média | Criar relatórios de inconsistências e campos ausentes |
| Baixa | Criar interface simples para consulta e atualização |

## Solução de problemas

Se o pré-processamento falhar, verifique:

- se o PDF existe em `db/raw/`;
- se o nome do arquivo no script corresponde ao arquivo real;
- se as bibliotecas Python necessárias estão instaladas;
- se o layout do PDF mudou;
- se o texto extraído em `_texto.txt` contém as linhas esperadas.

Para reexecutar o pré-processamento:

```powershell
python db/pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15/preprocess_pdf.py
```
## Registro de voo 2025

O arquivo `db/raw/Planilha 2025.xlsx` foi pre-processado por `db/pre_process/registro_voo_2025/preprocess_planilha_2025.py`.

O processamento gera duas visoes principais:

- `db/processed/registro_voo_2025.csv`: registro limpo, preservando a granularidade das linhas originais relevantes.
- `db/processed/registro_voo_2025_consolidado.csv`: registro consolidado para roteamento, com `ROTA` tratado como marcador de transicao.

Tambem sao gerados CSVs no formato esperado pelo prototipo OAMRP:

```text
db/pre_process/registro_voo_2025/missoes_oamrp_2025.csv
db/pre_process/registro_voo_2025/missoes_oamrp_2025_consolidado.csv
```

Criterios aplicados:

- colunas entre `REAL` e `COM2` descartadas;
- datas de 2025 normalizadas para formato ISO e `dd/mm`;
- horarios tratados como UTC/Z;
- chegadas iguais ou anteriores a partida deslocadas para o dia seguinte;
- transicoes com `ROTA` consolidadas em origem/destino reais;
- linha original 793, aeronave 2806, excluida dos artefatos processados;
- `SEGMTO` preservado como campo original, sem recalculo automatico.

O relatorio de validacao esta em:

```text
db/pre_process/registro_voo_2025/validacao_registro_voo_2025.md
```

## Modelo OAMRP v2

O arquivo `software/oamrp_v2.py` e a primeira versao do modelo usando o registro de voo 2025 consolidado.

Entradas principais:

- `db/processed/registro_voo_2025_consolidado.csv`;
- janela padrao de `2025-01-01` ate `2025-02-01` exclusivo;
- aeronaves reais `2800`, `2803`, `2809` e `2811`;
- base inicial provisoria `SBMN`;
- base de manutencao `SBMN`;
- prioridade uniforme: todas as missoes recebem peso 1.

Saida principal:

```text
db/processed/resultado_oamrp_jan_2025.csv
```

Resultado da primeira execucao:

- status do solver: `Optimal`;
- missoes cumpridas: 50/61;
- prioridade obtida: 50/61.

Limitacao atual: o limite de horas foi deixado alto para validar primeiro a continuidade espacial/temporal. A calibracao com dados reais de manutencao ainda deve ser feita em etapa posterior.