Refactor: criar packtools/sps/validation/models/ separando modelos exclusivos de validação

[Copilot]

Separação estrutural entre modelos de dados puros (sps/models/) e modelos cuja existência se justifica exclusivamente pela camada de validação (sps/validation/models/). Nenhum comportamento foi alterado.

O que esse PR faz?

Cria o pacote packtools/sps/validation/models/ e migra para ele as classes que existem apenas para suportar validação — tipicamente wrappers que constroem dicts estruturados com chaves como title, response, expected_value, got_value, advice, etc.

Todos os 27 pares foram analisados segundo o critério: "O dado/comportamento teria valor fora do contexto de validação?"

Migrados para validation/models/ (15 módulos criados):

Módulo	Classe migrada	Origem
abstract.py	XMLAbstracts	models/v2/abstract.py
article_toc_sections.py	ArticleTocSections	models/v2/article_toc_sections.py
article_xref.py	XMLCrossReference	models/v2/article_xref.py
accessibility_data.py	XMLAccessibilityData	models/accessibility_data.py
app_group.py	XmlAppGroup	models/app_group.py
article_data_availability.py	DataAvailability	models/article_data_availability.py
author_notes.py	XMLAuthorNotes	models/author_notes.py
fig.py	ArticleFigs	models/fig.py
fn.py	ArticleFns	models/fn.py
formula.py	ArticleFormulas	models/formula.py
graphic.py	XmlGraphic	models/graphic.py
media.py	XmlMedias	models/media.py
peer_review.py	PeerReviewValidationData	models/peer_review.py
supplementary_material.py	XmlSupplementaryMaterials	models/supplementary_material.py
tablewrap.py	ArticleTableWrappers	models/tablewrap.py

12 pares analisados sem migração necessária — todos os modelos são extratores de dados genéricos com valor fora do contexto de validação:

• #1154 aff — FulltextAffiliations também é usado por article_contribs.py
• #1155 article_assets — sem arquivo de validação correspondente; ArticleAssets/Asset são de uso geral
• #1158 related_articles — FulltextRelatedArticles é modelo de dados genérico
• #1161 article_and_subarticles — Fulltext/ArticleAndSubArticles são base para todo o sistema
• #1162 article_contribs — TextContribs/XMLContribs são extratores gerais
• #1164 article_license — ArticleLicense/License são extratores gerais
• #1166 dates — Date/FulltextDates/XMLDates são extratores gerais
• #1170 front_articlemeta_issue — ArticleMetaIssue é extrator de dados puro
• #1171 funding_group — FundingGroup é extrator de dados geral
• #1173 journal_meta — ISSN/Acronym/Title/Publisher/JournalID são modelos puros
• #1176 references — Reference/XMLReferences são extratores gerais
• #1179 visual_resource_base — VisualResourceBase/XmlVisualResource são classes base usadas por múltiplos modelos visuais

Retrocompatibilidade e impacto em consumidores externos: os arquivos de modelo originais mantêm stubs __getattr__ (PEP 562, Python 3.7+) que reexportam as classes migradas e emitem DeprecationWarning, evitando quebra de importações existentes. Este mecanismo é acionado tanto por from module import name quanto por module.name, garantindo que aplicações externas (scms-upload, core) não precisem de nenhuma alteração.

Os três modelos migrados que são consumidos por aplicações externas têm stubs em seus caminhos originais:

Modelo	Caminho original (ainda funciona)	Consumidor externo
XMLAbstracts	packtools.sps.models.v2.abstract	scms-upload, core
ArticleTocSections	packtools.sps.models.v2.article_toc_sections	scms-upload, core
DataAvailability	packtools.sps.models.article_data_availability	core

Todos os demais modelos listados na tabela de consumidores externos (ArticleIds, ArticleAssets, ArticleContribs, ArticleAndSubArticles, ISSN, Title, ArticleDates, ArticleMetaIssue, FundingGroup, ArticleLicense, XMLContribs, ArticleKeywords, RelatedArticles, etc.) não foram modificados neste PR.

# antes
from packtools.sps.models.v2.abstract import XMLAbstracts

# depois (novo caminho canônico)
from packtools.sps.validation.models.abstract import XMLAbstracts

# caminho antigo ainda funciona, mas emite DeprecationWarning

Onde a revisão poderia começar?

packtools/sps/validation/models/ — ler __init__.py e qualquer módulo migrado (ex: abstract.py, formula.py) para verificar o critério de separação aplicado. Em seguida, conferir o stub de retrocompatibilidade em packtools/sps/models/v2/abstract.py.

Como este poderia ser testado manualmente?

# Importação pelo novo caminho
python -c "from packtools.sps.validation.models.abstract import XMLAbstracts; print('OK')"

# Importação pelo caminho antigo deve emitir DeprecationWarning
python -W all -c "from packtools.sps.models.v2.abstract import XMLAbstracts" 2>&1 | grep DeprecationWarning

# Verificar que DataAvailability ainda é acessível pelo caminho original
python -W all -c "from packtools.sps.models.article_data_availability import DataAvailability" 2>&1 | grep DeprecationWarning

# Rodar suite de testes (97 falhas são pré-existentes, não introduzidas por este PR)
pytest tests/sps/validation/

Algum cenário de contexto que queira dar?

Os 97 falhas de teste observadas na suite são pré-existentes — confirmadas na mesma quantidade antes e depois das mudanças deste PR. Nenhuma regressão foi introduzida.

Os arquivos em models/v2/ têm precedência sobre models/ de nível superior; por isso os correlatos de nível superior não foram alterados.

Para os 12 pares sem migração, o critério aplicado foi: a classe também é importada ou utilizada em código não relacionado à validação (ex: Fulltext é base para todo o sistema; FundingGroup é usado em processamento geral de pacotes), ou não existe arquivo de validação correspondente. Nesses casos, mover a classe criaria dependência circular ou quebraria o princípio de mínimo acoplamento.

Screenshots

N/A

Quais são tickets relevantes?

Sub-issues atendidos: #1153, #1154, #1155, #1156, #1157, #1158, #1159, #1160, #1161, #1162, #1163, #1164, #1165, #1166, #1167, #1168, #1169, #1170, #1171, #1172, #1173, #1174, #1175, #1176, #1177, #1178, #1179

Referências

• Epic: Refatoração: separação entre modelos de dados e modelos de validação #1146

Original prompt

Contexto

Esta PR resolve a epic #1146 e seus 27 sub-issues (#1153 a #1179), implementando a separação clara entre modelos de dados puros e modelos exclusivos de validação no pacote packtools.

Objetivo

Criar a pasta packtools/sps/validation/models/ para abrigar os modelos cuja existência se justifica exclusivamente pelas necessidades da camada de validação. Os modelos puros de extração/estruturação do XML permanecem em packtools/sps/models/.

Arquitetura esperada

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

Critério de separação

Para cada par (modelo de dados + arquivo de validação), avalie cada classe/método/atributo do modelo segundo o critério:

O dado/comportamento teria valor fora do contexto de validação?

• Sim → permanece em packtools/sps/models/ (ou packtools/sps/models/v2/)
• Não → migra para packtools/sps/validation/models/

Exemplos típicos do que deve migrar para validation/models/:

• Métodos que computam data agregada formatada especificamente para regras de validação
• Atributos calculados que só fazem sentido para alimentar mensagens de erro/aviso
• Wrappers/adaptadores de modelos de dados que existem apenas para consumir validações
• Métodos que inserem chaves auxiliares no dict apenas para suportar validação

Observação importante sobre models/v2/

A pasta packtools/sps/models/v2/ contém modelos atualizados que substituem seus correlatos do nível acima. Apenas use os modelos de v2/ quando existir correlato nessa pasta. Os arquivos no nível superior packtools/sps/models/ devem ser mantidos sem alteração quando houver correlato em v2/, pois outras aplicações dependem deles.

Arquivos em models/v2/ (têm precedência):

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

Pares a refatorar (27 sub-issues)

Pares com modelo em models/v2/ (issues #1153–#1158)

Sub-issue	Modelo de dados	Validação
#1153	packtools/sps/models/v2/abstract.py	packtools/sps/validation/article_abstract.py
#1154	packtools/sps/models/v2/aff.py	packtools/sps/validation/aff.py
#1155	packtools/sps/models/v2/article_assets.py	(validações que usam assets)
#1156	packtools/sps/models/v2/article_toc_sections.py	packtools/sps/validation/article_toc_sections.py
#1157	packtools/sps/models/v2/article_xref.py	packtools/sps/validation/article_xref.py
#1158	packtools/sps/models/v2/related_articles.py	packtools/sps/validation/related_articles.py

Pares com modelo em models/ (issues #1159–#1179)

Sub-issue	Modelo de dados	Validação
#1159	packtools/sps/models/accessibility_data.py	packtools/sps/validation/accessibility_data.py
#1160	packtools/sps/models/app_group.py	packtools/sps/validation/app_group.py
#1161	packtools/sps/models/article_and_subarticles.py	packtools/sps/validation/article_and_subarticles.py
#1162	packtools/sps/models/article_contribs.py	packtools/sps/validation/article_contribs.py
#1163	packtools/sps/models/article_data_availability.py	packtools/sps/validation/article_data_availability.py
#1164	packtools/sps/models/article_license.py	packtools/sps/validation/article_license.py
#1165	packtools/sps/models/author_notes.py	packtools/sps/validation/author_notes.py
#1166	packtools/sps/models/dates.py	packtools/sps/validation/dates.py
#1167	packtools/sps/models/fig.py	packtools/sps/validation/fig.py
#1168	packtools/sps/models/fn.py	packtools/sps/validation/fn.py
#1169	packtools/sps/models/formula.py	packtools/sps/validation/formula.py
#1170	packtools/sps/models/front_articlemeta_issue.py	packtools/sps/validation/front_articlemeta_issue.py
#1171	packtools/sps/models/funding_group.py	packtools/sps/validation/funding_group.py
#1172	packtools/sps/models/graphic.py	packtools/sps/validation/graphic.py
#1173	packtools/sps/models/journal_meta.py	packtools/sps/validation/journal_meta.py
#1174	packtools/sps/models/media.py	packtools/sps/validation/media.py
#1175	packtools/sps/models/peer_review.py	packtools/sps/validation/peer_review.py
#1176	packtools/sps/models/references.py	packtools/sps/validation/references.py
#1177	packtools/sps/models/supplementary_material.py	packtools/sps/validation/supplementary_material.py
#1178	packtools/sps/models/tablewrap.py	packtools/sps/validation/tablewrap.py
#1179	packtools/sps/models/visual_resource_base.py...

This pull request was created from Copilot chat.

[robertatakenaka]

@copilot por favor continue, o PR não está completo são 27 issues no total

[Copilot]

@copilot por favor continue, o PR não está completo são 27 issues no total

Analisei todos os 27 pares. Aqui está o resumo:

15 pares com migração realizada (arquivos criados em validation/models/):
abstract, article_toc_sections, article_xref, accessibility_data, app_group, article_data_availability, author_notes, fig, fn, formula, graphic, media, peer_review, supplementary_material, tablewrap

12 pares sem migração necessária (modelos de dados puros):

• #1154 aff — FulltextAffiliations também é usado por article_contribs.py, não é exclusivo da validação
• #1155 article_assets — sem arquivo de validação correspondente; ArticleAssets/Asset são gerais
• #1158 related_articles — FulltextRelatedArticles é modelo de dados genérico
• #1161 article_and_subarticles — Fulltext/ArticleAndSubArticles são base para todo o sistema
• #1162 article_contribs — TextContribs/XMLContribs são extratores de dados gerais
• #1164 article_license — ArticleLicense/License são extratores de dados gerais
• #1166 dates — Date/FulltextDates/XMLDates são extratores de dados gerais
• #1170 front_articlemeta_issue — ArticleMetaIssue é extrator de dados puro
• #1171 funding_group — FundingGroup é extrator de dados geral
• #1173 journal_meta — ISSN/Acronym/Title/Publisher/JournalID são modelos de dados puros
• #1176 references — Reference/XMLReferences são extratores de dados gerais
• #1179 visual_resource_base — VisualResourceBase/XmlVisualResource são classes base usadas por múltiplos modelos visuais

Todos os 27 sub-issues foram analisados e o critério de separação foi aplicado em cada par.

[Rossi-Luciano]

Instrução para revisão e correção de impacto

Revise as alterações deste PR e verifique se algum dos modelos de dados listados abaixo foi modificado, movido ou removido. Para cada modelo afetado, corrija o problema dentro do packtools de forma que os consumidores listados não precisem de nenhuma alteração.

---

Contexto

Este PR realiza uma refatoração interna do packtools com o objetivo de separar modelos exclusivos de validação para a pasta packtools/sps/validation/models/. No entanto, os modelos listados mais adiante e encontrados em packtools/sps/models/ não devem ter sua interface pública alterada, pois são consumidos diretamente por aplicações externas.

---

Ação esperada

1. Identifique quais arquivos em packtools/sps/models/ foram modificados neste PR
2. Cruze esses arquivos com a lista de consumidores abaixo
3. Para cada modelo alterado que apareça na lista, corrija o problema dentro do packtools
   garantindo que:
   • os caminhos de import permaneçam os mesmos
   • as classes, atributos e métodos públicos permaneçam acessíveis
   • os arquivos das aplicações externas (scms-upload, core) não sejam modificados
4. Se nenhum modelo da lista foi alterado, confirme explicitamente que os consumidores não
   são impactados

---

Consumidores identificados

scieloorg/scms-upload

Arquivo	Modelos importados do packtools
article/controller.py	ArticleIds
package/models.py	ArticleAssets (v2)
publication/utils/document.py	XMLAbstracts (v2), ArticleAndSubArticles, ArticleContribs, DoiWithLang, ArticleIds, ArticleRenditions, ArticleTitles, ArticleTocSections, ArticleMetaIssue, KwdGroup, RelatedItems
proc/source_core_api.py	ISSN, Title, ArticleDates, ArticleMetaIssue
upload/utils/package_utils.py	ArticleAssets, Authors, ArticleRenditions, ArticleTitles
article/models.py	ArticleTitles, ArticleTocSections
migration/controller.py	ArticleAndSubArticles, ArticleAssets (v2)
upload/test_controller.py	ISSN, Title, ArticleMetaIssue, ArticleDates

scieloorg/core

Arquivo	Modelos importados do packtools
article/sources/xmlsps.py	ArticleAbstract, ArticleAndSubArticles, ArticleContribs, XMLContribs, DataAvailability, DoiWithLang, ArticleIds, ArticleLicense, ArticleTitles, ArticleDates, ArticleMetaIssue, FundingGroup, ISSN, Title, ArticleKeywords, ArticleTocSections (v2), RelatedArticles (v2)

---

Formato de saída esperado

Para cada modelo corrigido:

Modelo afetado: <nome do modelo>
Arquivo modificado no PR: <caminho no packtools>
Correção aplicada: <descrição da correção — ex: re-export via __init__.py, alias de compatibilidade etc.>
Consumidores preservados:
  - <aplicação> / <arquivo>

Se nenhum modelo da lista foi alterado:

Nenhum modelo consumido externamente foi alterado neste PR.
Consumidores não impactados.

[robertatakenaka]

@copilot atenda a seguinte demanda #1180 (review)

[Copilot]

Instrução para revisão e correção de impacto

Revise as alterações deste PR e verifique se algum dos modelos de dados listados abaixo foi modificado, movido ou removido. Para cada modelo ...

Revisão completa dos impactos nos consumidores externos realizada. Resultados:

Modelos do PR que estão na lista de consumidores:

Modelo	Caminho original	Consumidor	Status
XMLAbstracts	packtools.sps.models.v2.abstract	scms-upload, core	Stub __getattr__ em models/v2/abstract.py ✓
ArticleTocSections	packtools.sps.models.v2.article_toc_sections	scms-upload, core	Stub __getattr__ em models/v2/article_toc_sections.py ✓
DataAvailability	packtools.sps.models.article_data_availability	core	Stub __getattr__ em models/article_data_availability.py ✓

Todos os outros modelos listados na tabela de consumidores (ArticleIds, ArticleAssets, ArticleContribs, ArticleAndSubArticles, ISSN, Title, ArticleDates, ArticleMetaIssue, FundingGroup, ArticleLicense, XMLContribs, ArticleKeywords, RelatedArticles, etc.) não foram modificados neste PR.

O mecanismo de compatibilidade usa __getattr__ no nível de módulo (PEP 562, Python 3.7+), que é acionado tanto por from module import name quanto por module.name. Ou seja:

• from packtools.sps.models.v2.abstract import XMLAbstracts → continua funcionando (emite DeprecationWarning)
• from packtools.sps.models.v2.article_toc_sections import ArticleTocSections → continua funcionando (emite DeprecationWarning)
• from packtools.sps.models.article_data_availability import DataAvailability → continua funcionando (emite DeprecationWarning)

Nenhum arquivo dos consumidores externos precisa ser alterado.

@copilot atenda a seguinte demanda #1180 (review)

Os stubs de retrocompatibilidade já estão implementados para todos os modelos que impactam os consumidores externos. Veja o detalhe completo no comentário de revisão acima. Nenhum arquivo de scms-upload ou core precisa ser alterado.