Refatoração: separação entre modelos de dados e modelos de validação

[Rossi-Luciano]

Contexto

O pacote packtools possui duas camadas distintas de responsabilidade:

• Modelos de dados (packtools/sps/models/): responsáveis pela extração,
  normalização e agregação de informações do XML
• Validações (packtools/sps/validation/): responsáveis por aplicar regras
  de negócio sobre os dados extraídos e produzir respostas de validação

Com o crescimento do projeto, alguns modelos de dados foram complementados com
atributos e métodos que servem exclusivamente à camada de validação e não são
utilizados em nenhum outro contexto. Isso introduz acoplamento indesejado entre
as duas camadas, dificultando a manutenção, os testes e a evolução independente
de cada uma.

Objetivo

Separar claramente as responsabilidades, movendo para dentro da camada de
validação os modelos que existem exclusivamente para suportá-la.

Arquitetura esperada

Criar a pasta packtools/sps/validation/models/ para abrigar os modelos
exclusivos de validação. Os modelos de dados puros permanecem em
packtools/sps/models/ sem alteração.

packtools/sps/
├── models/                    # modelos de dados — sem alteração
│   ├── dates.py
│   ├── references.py
│   └── ...
└── validation/
    ├── models/                # NOVA PASTA — modelos exclusivos de validação
    │   └── ...
    ├── dates.py
    ├── references.py
    └── ...

Critério geral de separação

Um modelo (ou parte dele) deve migrar para validation/models/ quando sua
existência se justifica exclusivamente pelo que a camada de validação
precisa. O Copilot deve avaliar cada par de arquivos e decidir o que pertence
a cada camada, considerando:

• O que é extração e estruturação de dados do XML → permanece em models/
• O que existe para servir a lógica de validação → migra para validation/models/

Casos ambíguos devem ser resolvidos com base no critério: o dado teria valor
fora do contexto de validação? Se sim, permanece no model de dados.

Observação sobre a pasta models/v2/

A pasta packtools/sps/models/v2/ contém modelos de dados atualizados que
substituem os correlatos do nível acima. Para fins desta refatoração, apenas
os modelos de v2/ devem ser considerados quando existir um correlato nessa
pasta. Os arquivos do nível acima devem ser mantidos sem alteração, pois
outras aplicações dependem deles.

Arquivos em models/v2/:

packtools/sps/models/v2/
├── abstract.py
├── aff.py
├── article_assets.py
├── article_toc_sections.py
├── article_xref.py
├── related_articles.py
└── __init__.py

Arquivos envolvidos

Modelos de dados (packtools/sps/models/)

accessibility_data.py       article_authors.py            article_renditions.py
aff.py                      article_contribs.py           article_titles.py
app_group.py                article_data_availability.py  article_toc_sections.py
article_abstract.py         article_doi_with_lang.py      article_uri.py
article_and_subarticles.py  article_ids.py                article_xref.py
article_assets.py           article_license.py            author_notes.py
basenotes.py                base_text_node.py             body.py
dates.py                    fig.py                        formula.py
front_articlemeta_issue.py  funding_group.py              graphic.py
journal_meta.py             kwd_group.py                  label_and_caption.py
media.py                    packages.py                   peer_review.py
references.py               related_articles.py           sps_package.py
supplementary_material.py   tablewrap.py                  visual_resource_base.py
fn.py

Modelos de dados atualizados (packtools/sps/models/v2/)

abstract.py         article_assets.py       article_xref.py
aff.py              article_toc_sections.py related_articles.py

Validações (packtools/sps/validation/)

accessibility_data.py       article_contribs.py     author_notes.py
aff.py                      article_data_availability.py  basefn.py
alternatives.py             article_doi.py          dates.py
app_group.py                article_license.py      fig.py
article_abstract.py         article_toc_sections.py fn.py
article_and_subarticles.py  article_xref.py         formula.py
front_articlemeta_issue.py  funding_group.py        graphic.py
journal_meta.py             media.py                peer_review.py
preprint.py                 references.py           related_articles.py
supplementary_material.py   tablewrap.py            visual_resource_base.py

Tarefa solicitada

Para cada par de arquivos (model + validation) listado acima:

1. Ler o modelo de dados correspondente em packtools/sps/models/ (ou
   packtools/sps/models/v2/ quando existir o correlato)
2. Ler o arquivo de validação correspondente em packtools/sps/validation/
3. Identificar o que no modelo existe exclusivamente para suportar a validação
4. Criar uma ISSUE individual descrevendo:
   • Os caminhos exatos dos arquivos envolvidos
   • O que deve migrar para validation/models/ e o que deve permanecer
   • As adaptações necessárias nos imports do arquivo de validação
   • Qualquer impacto em outros arquivos que importem o model afetado

Pares sem model correspondente (ex: alternatives.py, preprint.py,
basefn.py, article_doi.py) devem ser ignorados nesta análise.