72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```text
|
|
| 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 |
|
|
```
|