arara_oarmp/CONTEXTO.md

Contexto do Projeto

Objetivo

Organizar, preservar e processar documentos relacionados ao projeto Arara OAMRP, mantendo rastreabilidade das alterações e separando arquivos originais, intermediários, processados e modelos de software.

Estrutura de Pastas

• db/raw/: arquivos originais, sem alteração.
• db/pre_process/: scripts e saídas intermediárias de pré-processamento.
• db/processed/: dados finais limpos, consolidados ou prontos para análise.
• software/: modelos, scripts analíticos e protótipos executáveis do OAMRP.
• 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

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

Orientações de Trabalho

• Manter documentos originais sempre em db/raw/.
• Não alterar arquivos dentro de db/raw/; quando necessário, gerar cópias ou saídas em db/pre_process/.
• Manter modelos e protótipos executáveis em software/.
• 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.
• Registrar quantidade de registros extraídos, descartados, corrigidos ou validados.
• 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 db/pre_process/ para db/processed/.
• Atualizar docs/about.md quando o fluxo técnico, campos extraídos ou limitações conhecidas mudarem.

Checklist de Atualização Documental

Antes de fechar uma mudança relevante ou criar um commit, verificar se algum destes arquivos precisa ser atualizado:

• LOG.md: atualizar em toda entrada de documento, alteração de dados, execução de script, processamento, decisão técnica ou mudança estrutural relevante.
• docs/changelog.md: atualizar quando a mudança representar nova versão ou marco do projeto, como novo parser, novo modelo, novo conjunto de dados, alteração de estrutura, nova funcionalidade ou correção importante.
• README.md: atualizar quando mudar a forma de usar o projeto, a estrutura de pastas, comandos principais, estado atual, dependências esperadas ou orientação para colaboradores.
• docs/about.md: atualizar quando mudar o fluxo técnico, arquitetura, campos extraídos, modelo de dados, limitações conhecidas, fontes de dados ou oportunidades de melhoria.
• docs/authors.md: atualizar quando houver novo colaborador, mudança de papel, nova contribuição atribuída ou nova versão registrada no changelog.
• CONTEXTO.md: atualizar quando mudar regra permanente de trabalho, convenção de pastas, política de documentação, padrão de nomenclatura ou combinado do projeto.
• .gitignore: atualizar quando surgirem novos arquivos temporários, caches, saídas locais ou artefatos gerados que não devem ser versionados.

Critério prático:

• Mudança operacional ou decisão do dia: registrar no LOG.md.
• Mudança significativa para quem usa ou entende o projeto: registrar também em docs/changelog.md.
• Mudança que altera como trabalhar no repositório: atualizar README.md e, se for regra permanente, CONTEXTO.md.
• Mudança técnica interna: atualizar docs/about.md.

Formato Recomendado do Log

| Data | Hora | Autor | Ação | Arquivos | Observações |
| --- | --- | --- | --- | --- | --- |
| 2026-06-15 | 15:41 | VTO | Pré-processou PDF de inspeções | db/raw/documento.pdf; db/pre_process/saida.csv | 18 inspeções extraídas |