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:

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

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:

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:

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:

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:

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.