# 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 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:

```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.