arara_oarmp/docs/about.md

Documentação Técnica — Arara OARMP

O que é

O Arara OARMP é um projeto para organizar dados e documentos 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 raw/;
• scripts e saídas intermediárias em pre_process/;
• área reservada para dados finais em processed/;
• 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
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 raw/ sem edição direta.

Como funciona

O fluxo atual é:

1. Guardar documentos originais em raw/.
2. Executar scripts de extração e padronização em 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 processed/ quando os critérios de qualidade estiverem definidos.

Pré-processamento atual

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

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

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. Ainda não há modelo final em 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 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 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 pre_process/preprocess_pdf.py