diff --git a/CONTEXTO.md b/CONTEXTO.md index 9020a80..d348dca 100644 --- a/CONTEXTO.md +++ b/CONTEXTO.md @@ -9,6 +9,16 @@ Organizar, preservar e processar documentos relacionados ao projeto `arara_oarmp - `raw/`: arquivos originais, sem alteração. - `pre_process/`: scripts e saídas intermediárias de pré-processamento. - `processed/`: dados finais limpos, consolidados ou prontos para análise. +- `docs/`: documentação técnica, autoria e histórico de versões. + +## Arquivos de Documentação + +- `README.md`: guia inicial para colaboradores e uso básico do repositório. +- `CONTEXTO.md`: orientações permanentes e combinados de trabalho. +- `LOG.md`: diário operacional detalhado, com data, hora, autor, ação, arquivos e observações. +- `docs/about.md`: documentação técnica do projeto, 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. ## Colaboradores @@ -21,6 +31,7 @@ Organizar, preservar e processar documentos relacionados ao projeto `arara_oarmp - Manter documentos originais sempre em `raw/`. - Não alterar arquivos dentro de `raw/`; quando necessário, gerar cópias ou saídas em `pre_process/`. - Registrar no `LOG.md` toda entrada, alteração, processamento ou decisão relevante. +- Registrar em `docs/changelog.md` mudanças significativas de versão, como novo parser, novo conjunto de dados, mudança estrutural ou nova funcionalidade. - Usar o formato de log com data, hora, tag do colaborador e descrição objetiva da ação. - Registrar a origem de cada documento, quando conhecida. - Informar scripts executados e parâmetros importantes. @@ -28,6 +39,7 @@ Organizar, preservar e processar documentos relacionados ao projeto `arara_oarmp - Registrar problemas encontrados nos arquivos originais, como erros de digitação, páginas ilegíveis, campos ausentes ou tabelas quebradas. - Registrar decisões de padronização, por exemplo nomes de colunas, unidades, formatos de data e tratamento de acentos. - Explicitar os critérios usados para mover dados de `pre_process/` para `processed/`. +- Atualizar `docs/about.md` quando o fluxo técnico, campos extraídos ou limitações conhecidas mudarem. ## Formato Recomendado do Log diff --git a/LOG.md b/LOG.md index 92b0a60..5fac998 100644 --- a/LOG.md +++ b/LOG.md @@ -18,3 +18,4 @@ Legenda de autores: | 2026-06-15 | 16:03 | VTO | Corrigiu interpretação da coluna `Zera TSO` | `pre_process/preprocess_pdf.py`; `pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.json`; `pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.csv` | `Zera TSO` passou a ser coluna única `zera_tso`; níveis `B`, `P` e `O` mapeados para Base, Parque e Orgânico; `controle_original` mantido para rastreabilidade. | | 2026-06-15 | 16:08 | VTO | Separou valores numéricos dos intervalos de inspeção | `pre_process/preprocess_pdf.py`; `pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.json`; `pre_process/relatorio_ciclo_inspecoes_c105_2805_2026-06-15_inspecoes.csv` | Criadas colunas discretas para horas de voo, meses contínuos e pousos, mantendo os campos textuais originais. | | 2026-06-15 | 16:43 | VTO | Renomeou o projeto e trocou o repositório remoto | `README.md`; `CONTEXTO.md`; `.git/config` | Projeto passou a se chamar `arara_oarmp`; remoto atualizado para `https://git.ppgao.ita.br/vitorcesavc/arara_oarmp.git`. | +| 2026-06-15 | 17:57 | VTO | Criou documentação técnica no padrão `docs/` | `docs/about.md`; `docs/authors.md`; `docs/changelog.md`; `README.md`; `CONTEXTO.md`; `LOG.md` | Estrutura inspirada no módulo `meteorologia_aeroportos`: documentação técnica, autoria e changelog separados do log operacional. | diff --git a/README.md b/README.md index c5834a5..7a73641 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@ A ideia é construir, em conjunto, uma base confiável para encaixar missões, a Um repositório é uma pasta controlada pelo Git. Ele guarda os arquivos do projeto e também o histórico de alterações. -O GitHub é o site onde esse repositório fica hospedado de forma privada, para que os colaboradores possam acessar, baixar, atualizar e enviar contribuiçõ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 GitHub permite compartilhar o projeto; +- 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. @@ -24,6 +24,7 @@ arara_oarmp/ raw/ pre_process/ processed/ + docs/ CONTEXTO.md LOG.md README.md @@ -32,6 +33,7 @@ arara_oarmp/ - `raw/`: documentos originais. Não editar esses arquivos diretamente. - `pre_process/`: scripts e arquivos intermediários gerados a partir dos documentos originais. - `processed/`: arquivos finais, limpos e prontos para análise ou uso. +- `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. @@ -46,11 +48,11 @@ Usamos tags curtas para identificar quem fez cada alteração relevante: 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 GitHub +## 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 GitHub. +1. Abra o repositório no Gitea do PPGAO/ITA. 2. Entre nas pastas para ver os arquivos. 3. Use `raw/` para consultar documentos originais. 4. Use `pre_process/` para consultar arquivos intermediários. @@ -64,9 +66,16 @@ Para baixar um arquivo pelo site: 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 GitHub. +Este caminho é para quem vai mexer nos arquivos e devolver alterações ao Gitea. Primeiro, instale o Git: @@ -107,7 +116,7 @@ Crie um commit com uma mensagem curta: git commit -m "Descreva a alteração feita" ``` -Envie para o GitHub: +Envie para o Gitea: ```powershell git push diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..b8b07fc --- /dev/null +++ b/docs/about.md @@ -0,0 +1,129 @@ +# 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: + +```text +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: + +```powershell +python pre_process/preprocess_pdf.py +``` diff --git a/docs/authors.md b/docs/authors.md new file mode 100644 index 0000000..86f2cc3 --- /dev/null +++ b/docs/authors.md @@ -0,0 +1,44 @@ +# Autoria e Contribuições + +## Colaboradores + +| Tag | Nome | Papel inicial | +| --- | --- | --- | +| `VTO` | Vitor Cesa | Organização do repositório, estrutura inicial, pré-processamento e documentação | +| `GNR` | Generoso | Colaborador | +| `JOM` | João Marcos | Colaborador e origem inicial do relatório de inspeções | + +## Instituição e contexto + +Projeto desenvolvido para apoiar o OARMP do Esquadrão Arara, em Manaus, com organização colaborativa em repositório Git. + +## Como contribuir + +Ao modificar ou estender este projeto: + +1. Atualize sua cópia com `git pull` antes de começar. +2. Preserve documentos originais em `raw/`. +3. Coloque scripts e saídas intermediárias em `pre_process/`. +4. Coloque resultados finais e validados em `processed/`. +5. Registre mudanças operacionais em `LOG.md`. +6. Registre mudanças de versão em `docs/changelog.md` quando houver alteração significativa. +7. Identifique o autor usando a tag do colaborador: `VTO`, `GNR` ou `JOM`. +8. Use mensagens de commit curtas e objetivas. + +## Formato sugerido para mudanças de versão + +```text +## v — — + +### Adicionado / Alterado / Corrigido / Removido + +- Descrição objetiva da mudança. +``` + +## Histórico de contribuições + +| Versão | Autor | Data | Descrição resumida | +| --- | --- | --- | --- | +| v0.1 | VTO | 2026-06 | Estrutura inicial, documentação, pré-processamento do primeiro relatório de inspeções e migração para o repositório `arara_oarmp` | + +Contribuidores futuros devem adicionar uma linha nesta tabela e criar a entrada correspondente em `docs/changelog.md`. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..1c22fca --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,45 @@ +# Changelog + +Todas as versões significativas do Arara OARMP devem ser registradas aqui. O `LOG.md` guarda o diário operacional detalhado; este arquivo resume mudanças por versão. + +Formato: + +```text +## v — — + +### Adicionado / Alterado / Corrigido / Removido + +- Descrição objetiva. +``` + +--- + +## v0.1 — VTO — 2026-06 + +### Adicionado + +- Repositório Git inicial. +- Estrutura de dados com `raw/`, `pre_process/` e `processed/`. +- Arquivo `README.md` na raiz com guia de uso do repositório. +- Arquivo `CONTEXTO.md` com orientações permanentes do projeto. +- Arquivo `LOG.md` com rastreabilidade operacional por data, hora e tag de autor. +- Pré-processamento inicial do relatório de ciclo de inspeções do C-105 matrícula 2805. +- Saídas intermediárias em texto, JSON e CSV. +- Campos discretos para `zera_tso`, letra, nível, duração, horas de voo, meses contínuos e pousos. +- Documentação em `docs/about.md`, `docs/authors.md` e `docs/changelog.md`. + +### Alterado + +- Projeto renomeado para `arara_oarmp`. +- Repositório remoto migrado para `https://git.ppgao.ita.br/vitorcesavc/arara_oarmp.git`. +- Documentação reorganizada para separar guia inicial, contexto, autoria, histórico de versão e log operacional. + +### Corrigido + +- Interpretação da coluna `Zera TSO`, que passou a ser tratada como coluna única. +- Mapeamento dos níveis `B`, `P` e `O` para Base, Parque e Orgânico. + +### Observações + +- O parser atual foi calibrado para o primeiro PDF processado. +- A grafia original do documento fonte foi preservada, inclusive ocorrências de `INPEÇÃO`.