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