Add technical docs structure

2026-06-15 17:58:54 -03:00
parent c09ce95e62
commit 33c452b264
6 changed files with 246 additions and 6 deletions
--- 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

--- 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. |
--- 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
--- a/docs/about.md
+++ 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
+```
--- a/docs/authors.md
+++ 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<versão> — <Autor ou tag> — <YYYY-MM>
+
+### 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`.
--- a/docs/changelog.md
+++ 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<versão> — <Autor ou tag> — <YYYY-MM>
+
+### 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`.