arara_oarmp/README.md

# Arara OAMRP

Este repositório organiza os arquivos, processamentos e protótipos do projeto Arara OAMRP do Esquadrão Arara, em Manaus.

A ideia é construir, em conjunto, uma base confiável para encaixar missões, aeronaves e manutenções. O repositório serve como lugar único para guardar documentos originais, registrar decisões, transformar relatórios em dados utilizáveis e manter um histórico claro do que foi feito por cada colaborador.

## O que é um repositório

Um repositório é uma pasta controlada pelo Git. Ele guarda os arquivos do projeto e também o histórico de alterações.

O Gitea do PPGAO/ITA é o site onde esse repositório fica hospedado de forma privada, para que os colaboradores possam acessar, baixar, atualizar e enviar contribuições.

Na prática:

- o Git mostra o que mudou;
- o Gitea permite compartilhar o projeto;
- os commits são registros das alterações feitas;
- o `LOG.md` explica o motivo e o contexto das mudanças importantes.

## Estrutura do projeto

```text
arara_oarmp/
  db/
    raw/
    pre_process/
    processed/
  software/
  docs/
  CONTEXTO.md
  LOG.md
  README.md
```

- `db/raw/`: documentos originais. Não editar esses arquivos diretamente.
- `db/pre_process/`: scripts e arquivos intermediários gerados a partir dos documentos originais.
- `db/processed/`: arquivos finais, limpos e prontos para análise ou uso.
- `software/`: modelos e protótipos executáveis, incluindo o modelo MIP inicial de roteamento.
- `docs/`: documentação técnica, autoria e histórico de versões.
- `CONTEXTO.md`: regras, combinados e orientações permanentes do projeto.
- `LOG.md`: histórico rastreável das ações feitas no projeto.
- `README.md`: este guia inicial.

## Colaboradores

Usamos tags curtas para identificar quem fez cada alteração relevante:

- `VTO`: Vitor Cesa.
- `GNR`: Generoso.
- `JOM`: João Marcos.

Sempre que alguém fizer uma mudança importante, deve registrar no `LOG.md` com data, hora, tag do autor, ação, arquivos e observações.

## Como usar pelo site do Gitea

Este caminho é bom para quem só quer ver arquivos, baixar documentos ou conferir o histórico.

1. Abra o repositório no Gitea do PPGAO/ITA.
2. Entre nas pastas para ver os arquivos.
3. Use `db/raw/` para consultar documentos originais.
4. Use `db/pre_process/` para consultar arquivos intermediários.
5. Use `db/processed/` para consultar dados finais quando existirem.
6. Abra o `LOG.md` para entender o que já foi feito.
7. Abra o `CONTEXTO.md` para ver os combinados do projeto.

Para baixar um arquivo pelo site:

1. Clique no arquivo.
2. Clique em `Download raw file` ou no botão de download.
3. Salve no computador.

## Documentação

- `docs/about.md`: descrição técnica, fluxo de dados, limitações e oportunidades de melhoria.
- `docs/authors.md`: autoria, colaboradores e regras de contribuição.
- `docs/changelog.md`: histórico resumido de versões significativas.
- `LOG.md`: diário operacional detalhado.

## Como usar no computador

Este caminho é para quem vai mexer nos arquivos e devolver alterações ao Gitea.

Primeiro, instale o Git:

```powershell
git --version
```

Se o comando não funcionar, o Git ainda não está instalado.

Depois, clone o repositório:

```powershell
git clone https://git.ppgao.ita.br/vitorcesavc/arara_oarmp.git
cd arara_oarmp
```

Antes de começar a trabalhar, atualize sua cópia:

```powershell
git pull
```

Depois de alterar arquivos, veja o que mudou:

```powershell
git status
```

Adicione os arquivos modificados:

```powershell
git add .
```

Crie um commit com uma mensagem curta:

```powershell
git commit -m "Descreva a alteração feita"
```

Envie para o Gitea:

```powershell
git push
```

## Fluxo recomendado de trabalho

1. Rode `git pull` antes de começar.
2. Coloque documentos novos em `db/raw/`.
3. Gere arquivos intermediários em `db/pre_process/`.
4. Coloque resultados finais em `db/processed/`.
5. Atualize o `LOG.md`.
6. Faça commit.
7. Rode `git push`.

## Cuidados importantes

- Não editar arquivos originais dentro de `db/raw/`.
- Não apagar arquivos de outros colaboradores sem combinar.
- Não subir arquivos temporários do Office, como arquivos começando com `~$`.
- Não colocar senhas, tokens ou informações pessoais desnecessárias no repositório.
- Preferir nomes de arquivo descritivos, com tipo do documento, aeronave, matrícula e data quando possível.
- Registrar no `LOG.md` qualquer decisão que afete os dados.

## Estado atual

O modelo ativo é `software/oamrp_v3.py`, que implementa o OAMRP sobre uma rede espaço-tempo com arcos de ferry, múltiplos tipos de inspeção e prioridades de missão via OFRAG.

Última rodada validada (2026-06-16): 50/50 missões sintéticas cumpridas, solver CBC Optimal, 4 EVAMs operacionais.

Arquivos principais do modelo:

```text
software/oamrp_v3.py          — modelo MIP principal
software/gerar_ofrag.py       — gerador da tabela OFRAG
software/visualizar_resultado.py — mapa Folium interativo
db/processed/ofrag.csv        — ordens de missão com prioridades 1–5
db/processed/resultado_oamrp_sintetico.csv — resultado da última rodada
db/processed/mapa_rotas.html  — mapa interativo de rotas
```

Para rodar:

```powershell
python software/oamrp_v3.py --sintetico --seed 42 --aleatorio --ofrag db/processed/ofrag.csv
python software/visualizar_resultado.py
```

Pré-processamentos disponíveis:

```text
db/raw/relatorio_ciclo_inspecoes_c105_2805_2026-06-15.pdf — ciclo de inspeções C-105/2805
db/processed/registro_voo_2025.csv — registro de voo 2025 limpo (1420 trechos)
db/processed/registro_voo_2025_consolidado.csv — consolidado para roteamento
```
## Atualizacao - registro de voo 2025

A `Planilha 2025.xlsx` foi pre-processada a partir de `db/raw/` sem alterar o arquivo original.

Arquivos gerados:

```text
db/pre_process/registro_voo_2025/preprocess_planilha_2025.py
db/pre_process/registro_voo_2025/registro_voo_2025_limpo.csv
db/pre_process/registro_voo_2025/registro_voo_2025_limpo.xlsx
db/pre_process/registro_voo_2025/registro_voo_2025_consolidado.csv
db/pre_process/registro_voo_2025/missoes_oamrp_2025.csv
db/pre_process/registro_voo_2025/missoes_oamrp_2025_consolidado.csv
db/pre_process/registro_voo_2025/resumo_registro_voo_2025.json
db/pre_process/registro_voo_2025/validacao_registro_voo_2025.md
db/processed/registro_voo_2025.csv
db/processed/registro_voo_2025_consolidado.csv
```

O consolidado trata `ROTA` como marcador de transicao, nao como localidade operacional, e remove a linha original 793 da aeronave 2806 dos artefatos processados.

## Modelo OAMRP v2

O arquivo `software/oamrp_v2.py` executa a primeira rodada do modelo com dados reais consolidados de 2025. Por padrao, ele usa janeiro/2025, as aeronaves `2800`, `2803`, `2809` e `2811`, e grava:

```text
db/processed/resultado_oamrp_jan_2025.csv
```

Para executar:

```powershell
python software/oamrp_v2.py
```

A rodada inicial de janeiro/2025 foi resolvida como otima pelo CBC, com 50 de 61 missoes cumpridas.