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 inicial

O arquivo software/oamrp_v1.py contém um protótipo de modelo MIP em PuLP para o Aircraft Routing do Esquadrão Arara. O modelo usa dados sintéticos/substituíveis de aeronaves e missões e busca maximizar o cumprimento ponderado de missões opcionais.

Restrições representadas no protótipo:

• continuidade espacial e temporal por aeronave;
• turnaround mínimo entre missões;
• limite de horas de célula até a próxima inspeção;
• base inicial e horas acumuladas reais de cada aeronave como parâmetros de entrada.

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