Add technical docs structure
This commit is contained in:
Cesa-V
129
docs/about.md
Normal file
129
docs/about.md
Normal file
@@ -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
|
||||
```
|
||||
44
docs/authors.md
Normal file
44
docs/authors.md
Normal file
@@ -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`.
|
||||
45
docs/changelog.md
Normal file
45
docs/changelog.md
Normal file
@@ -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`.
|
||||
Reference in New Issue
Block a user