Criar validações para o elemento <issue>

[Rossi-Luciano]

Objetivo

Implementar validações para o elemento <issue> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 70% (7 de 10 regras).

Nota: Algumas validações para <issue> podem já estar parcialmente implementadas no repositório. Este Issue visa reavaliar, complementar e garantir cobertura completa das regras SPS 1.10.

---

Contexto

O elemento <issue> identifica o número de uma publicação periódica, incluindo suplementos e números especiais. Validações corretas garantem que o formato seja consistente e padronizado conforme especificações SPS, sem pontuação, sem uppercase, sem zeros à esquerda, e usando nomenclaturas corretas para suplementos (suppl) e números especiais (spe).

Conformidade atual: X de 10 regras implementadas (X%)
Meta após implementação: 7 de 10 regras (70%)

---

Documentação SPS

Referência oficial: https://docs.google.com/document/d/1GTv4Inc2LS_AXY-ToHT3HmO66UT0VAHWJNOIqzBNSgA/edit?tab=t.0#heading=h.issue

Regras principais conforme SPS 1.10:

1. Ocorrência:

   • <issue> deve aparecer no máximo uma vez em <article-meta>

2. Formatos válidos:

   • Número simples: 4
   • Suplemento de número: 4 suppl 1
   • Suplemento de volume: suppl 1
   • Número especial: spe1

3. Restrições de formato:

   • Sem pontuação: não usar ., ,, -, /, etc.
   • Sem uppercase: usar apenas minúsculas
   • Sem zero à esquerda: usar 4 ao invés de 04
   • Espaçamento específico: um espaço entre número e suppl (ex: 4 suppl 1)

4. Nomenclatura obrigatória:

   • Para suplemento: usar suppl (não supl, s, supplement)
   • Para número especial: usar spe (não esp, nesp, nspe, especial)

5. Elemento proibido:

   • Não usar <supplement> em <article-meta> (suplementos devem ser identificados em <issue>)

---

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

#	Regra	Nível	Descrição
1	Validar unicidade de <issue>	ERROR	O elemento <issue> deve aparecer no máximo uma vez em <article-meta>
2	Validar ausência de pontuação	ERROR	O valor de <issue> não deve conter pontuação (., ,, -, /, :, ;, etc.)
3	Validar ausência de uppercase	ERROR	O valor de <issue> deve estar em minúsculas (sem letras maiúsculas)
4	Validar nomenclatura de suplemento	ERROR	Suplementos devem usar suppl (não supl, s, supplement, sup)
5	Validar nomenclatura de número especial	ERROR	Números especiais devem usar spe (não esp, nesp, nspe, especial, noesp)
6	Validar ausência de <supplement> em <article-meta>	CRITICAL	O elemento <supplement> não é permitido em <article-meta> (usar <issue> para suplementos)

P1 – Importantes (implementar se possível)

#	Regra	Nível	Descrição
7	Validar ausência de zero à esquerda	WARNING	Números não devem ter zero à esquerda (usar 4 ao invés de 04)

P2 – Futuras (fora do escopo deste Issue)

#	Regra	Motivo de exclusão
8	Validar espaçamento correto (4 suppl 1 vs 4suppl1)	Baixa prioridade - formato já coberto por outras validações
9	Validar consistência com nome de arquivo	Alta complexidade - requer validação cruzada com sistema de arquivos
10	Validar que partes numéricas são válidas	Baixa prioridade - formato livre permite variações

---

Arquivos a Criar/Modificar

Avaliar existentes (podem ter validações parciais):

• packtools/sps/models/article_meta.py ou similar – Verificar se modelo existe
• packtools/sps/validation/article_meta.py ou issue.py – Verificar validações existentes
• packtools/sps/validation/rules/issue_rules.json ou similar – Verificar configuração

Criar (se não existirem):

• packtools/sps/models/issue.py – Modelo de extração de dados
• packtools/sps/validation/issue.py – Validações
• packtools/sps/validation/rules/issue_rules.json – Configuração de níveis de erro
• tests/sps/validation/test_issue.py – Testes unitários

Referenciar (implementações similares):

• packtools/sps/validation/article_doi.py – Validação de unicidade
• packtools/sps/validation/utils.py – Funções auxiliares (build_response)

---

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Número simples -->
<article-meta>
    <volume>10</volume>
    <issue>4</issue>
</article-meta>

<!-- Exemplo 2: Apenas número sem volume -->
<article-meta>
    <issue>4</issue>
</article-meta>

<!-- Exemplo 3: Suplemento de número -->
<article-meta>
    <volume>10</volume>
    <issue>4 suppl 2</issue>
</article-meta>

<!-- Exemplo 4: Suplemento de volume -->
<article-meta>
    <volume>10</volume>
    <issue>suppl 2</issue>
</article-meta>

<!-- Exemplo 5: Número especial -->
<article-meta>
    <volume>10</volume>
    <issue>spe1</issue>
</article-meta>

<!-- Exemplo 6: Números com múltiplos dígitos -->
<article-meta>
    <volume>15</volume>
    <issue>123</issue>
</article-meta>

<!-- Exemplo 7: Suplemento com número de dois dígitos -->
<article-meta>
    <volume>5</volume>
    <issue>2 suppl 12</issue>
</article-meta>

<!-- Exemplo 8: Número especial com múltiplos dígitos -->
<article-meta>
    <volume>8</volume>
    <issue>spe15</issue>
</article-meta>

XML Inválido – Caso 1: Múltiplos (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4</issue>
    <issue>5</issue>
</article-meta>

Erro esperado: Elemento <issue> deve aparecer no máximo uma vez em <article-meta>

XML Inválido – Caso 2: Com pontuação (ponto) (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4.2</issue>
</article-meta>

Erro esperado: Valor de <issue> não deve conter pontuação. Remova . do valor.

XML Inválido – Caso 3: Com pontuação (hífen) (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4-5</issue>
</article-meta>

Erro esperado: Valor de <issue> não deve conter pontuação. Remova - do valor.

XML Inválido – Caso 4: Com pontuação (barra) (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4/5</issue>
</article-meta>

Erro esperado: Valor de <issue> não deve conter pontuação. Remova / do valor.

XML Inválido – Caso 5: Com uppercase (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4 Suppl 1</issue>
</article-meta>

Erro esperado: Valor de <issue> deve estar em minúsculas. Use suppl ao invés de Suppl.

XML Inválido – Caso 6: Nomenclatura incorreta de suplemento "supl" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4 supl 1</issue>
</article-meta>

Erro esperado: Use suppl para suplementos. Valor encontrado: supl.

XML Inválido – Caso 7: Nomenclatura incorreta de suplemento "s" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4 s 1</issue>
</article-meta>

Erro esperado: Use suppl para suplementos. Valor encontrado: s.

XML Inválido – Caso 8: Nomenclatura incorreta de suplemento "supplement" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>4 supplement 1</issue>
</article-meta>

Erro esperado: Use suppl para suplementos. Valor encontrado: supplement.

XML Inválido – Caso 9: Nomenclatura incorreta de número especial "esp" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>esp1</issue>
</article-meta>

Erro esperado: Use spe para números especiais. Valor encontrado: esp.

XML Inválido – Caso 10: Nomenclatura incorreta de número especial "nesp" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>nesp1</issue>
</article-meta>

Erro esperado: Use spe para números especiais. Valor encontrado: nesp.

XML Inválido – Caso 11: Nomenclatura incorreta de número especial "nspe" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>nspe1</issue>
</article-meta>

Erro esperado: Use spe para números especiais. Valor encontrado: nspe.

XML Inválido – Caso 12: Nomenclatura incorreta de número especial "especial" (ERROR)

<article-meta>
    <volume>10</volume>
    <issue>especial1</issue>
</article-meta>

Erro esperado: Use spe para números especiais. Valor encontrado: especial.

XML Inválido – Caso 13: Elemento presente (CRITICAL)

<article-meta>
    <volume>10</volume>
    <issue>4</issue>
    <supplement>1</supplement>
</article-meta>

Erro esperado: Elemento <supplement> não é permitido em <article-meta>. Use <issue> para identificar suplementos (ex: <issue>4 suppl 1</issue>).

XML Inválido – Caso 14: Zero à esquerda (WARNING)

<article-meta>
    <volume>10</volume>
    <issue>04</issue>
</article-meta>

Erro esperado: Número não deve ter zero à esquerda. Use 4 ao invés de 04.

XML Inválido – Caso 15: Múltiplos zeros à esquerda (WARNING)

<article-meta>
    <volume>10</volume>
    <issue>004</issue>
</article-meta>

Erro esperado: Número não deve ter zeros à esquerda. Use 4 ao invés de 004.

XML Inválido – Caso 16: Zero à esquerda em suplemento (WARNING)

<article-meta>
    <volume>10</volume>
    <issue>4 suppl 01</issue>
</article-meta>

Erro esperado: Número do suplemento não deve ter zero à esquerda. Use 1 ao invés de 01.

XML Inválido – Caso 17: vazio (CRITICAL)

<article-meta>
    <volume>10</volume>
    <issue></issue>
</article-meta>

Erro esperado: Elemento <issue> não pode estar vazio

XML Inválido – Caso 18: apenas espaços (CRITICAL)

<article-meta>
    <volume>10</volume>
    <issue>   </issue>
</article-meta>

Erro esperado: Elemento <issue> não pode conter apenas espaços

---

Padrão de Implementação

Diretrizes Gerais:

1. Seguir padrões existentes no repositório:

   • Consultar implementações similares como article_doi.py (validação de unicidade)
   • Usar estrutura de classes já estabelecida no packtools
   • IMPORTANTE: Verificar se já existem validações parciais para <issue> e integrá-las ou complementá-las

2. Internacionalização (i18n):

   • OBRIGATÓRIO: Todas as mensagens devem suportar internacionalização
   • Usar advice_text e advice_params em build_response()
   • Consultar conversas anteriores sobre implementação de i18n no packtools
   • Referência: validações em article_contribs.py que já implementam i18n completo

3. Validações condicionais:

   • Validações que dependem de contexto devem retornar None quando não aplicável
   • Exemplo: validação de zero à esquerda só se aplica se valor for numérico
   • Usar filter_results() nos testes para remover None

4. Uso de build_response():

   • Sempre usar parent=self.data (dict completo, nunca string)
   • Campo response deve conter: "OK", "WARNING", "ERROR", "CRITICAL"
   • Sempre fornecer advice_text e advice_params para i18n

5. Modelo de dados:

   • Criar propriedade que retorna dicionário com dados de <issue>
   • Dict deve conter: issue, has_supplement_element, parent, parent_id, parent_lang

6. Validação de pontuação:

   • Lista de caracteres proibidos: ., ,, -, /, :, ;, !, ?, (, ), [, ], {, }, ', "
   • Usar regex ou verificação de caracteres

7. Validação de uppercase:

   • Verificar se há letras maiúsculas no valor
   • Usar método .islower() ou comparação de string com .lower()

8. Validação de nomenclatura:

   • Detectar variantes incorretas usando regex ou in operator
   • Para suplementos: procurar por supl, s , supplement, sup (com espaço)
   • Para especiais: procurar por esp, nesp, nspe, especial, noesp

9. Validação de zero à esquerda:

   • Usar regex para detectar padrões como ^0\d+ ou \s0\d+
   • Considerar que 0 sozinho é válido (não é zero à esquerda)

---

Testes Esperados

Casos de teste obrigatórios:

Unicidade:

• Um único <issue> em <article-meta> (OK)
• Dois ou mais <issue> em <article-meta> (ERROR)
• Nenhum <issue> em <article-meta> (OK - opcional)

Formato de número simples:

• Número simples 4 (OK)
• Número simples 10 (OK)
• Número simples 123 (OK)
• Número com zero à esquerda 04 (WARNING)
• Número com múltiplos zeros 004 (WARNING)
• Apenas 0 (OK - não é zero à esquerda)

Suplementos:

• Suplemento de número 4 suppl 1 (OK)
• Suplemento de volume suppl 1 (OK)
• Suplemento com dois dígitos 4 suppl 12 (OK)
• Nomenclatura incorreta 4 supl 1 (ERROR)
• Nomenclatura incorreta 4 s 1 (ERROR)
• Nomenclatura incorreta 4 supplement 1 (ERROR)
• Nomenclatura incorreta 4 sup 1 (ERROR)
• Uppercase em suppl 4 Suppl 1 (ERROR)
• Uppercase 4 SUPPL 1 (ERROR)
• Zero à esquerda em suppl 4 suppl 01 (WARNING)

Números especiais:

• Número especial spe1 (OK)
• Número especial com dois dígitos spe12 (OK)
• Nomenclatura incorreta esp1 (ERROR)
• Nomenclatura incorreta nesp1 (ERROR)
• Nomenclatura incorreta nspe1 (ERROR)
• Nomenclatura incorreta especial1 (ERROR)
• Nomenclatura incorreta noesp1 (ERROR)
• Uppercase Spe1 (ERROR)
• Uppercase SPE1 (ERROR)

Pontuação:

• Com ponto 4.2 (ERROR)
• Com vírgula 4,5 (ERROR)
• Com hífen 4-5 (ERROR)
• Com barra 4/5 (ERROR)
• Com dois pontos 4:2 (ERROR)
• Com ponto e vírgula 4;2 (ERROR)
• Com parênteses 4(2) (ERROR)
• Com colchetes [4] (ERROR)

Uppercase:

• Totalmente minúsculo (OK)
• Uma letra maiúscula no meio (ERROR)
• Primeira letra maiúscula (ERROR)
• Totalmente maiúsculo (ERROR)
• Apenas números (OK - não tem uppercase)

Elemento :

• Sem <supplement> em <article-meta> (OK)
• Com <supplement> em <article-meta> (CRITICAL)

Casos de borda:

• <issue> vazio (CRITICAL)
• <issue> apenas espaços (CRITICAL)
• Valor com espaços extras 4 suppl 1 (permitir - não validar espaçamento)
• Múltiplos tipos misturados 4 suppl 1 spe2 (permitir - formato livre)
• Valor muito longo (OK - sem limite de tamanho)
• Caracteres especiais Unicode (OK - permitir)

Total esperado: ~50 testes unitários

Estrutura de testes:

• Usar filter_results() para remover None dos resultados
• Asserções devem usar campo response (não is_valid)
• Testes devem ser autocontidos e descritivos
• Agrupar testes por categoria (unicidade, pontuação, uppercase, nomenclatura, etc.)

---

Critérios de Aceite

O PR será aceito quando:

• Verificação de validações existentes: Código existente para <issue> foi analisado e integrado ou substituído adequadamente
• Todas as regras P0 implementadas (6 validações CRITICAL/ERROR)
• Todas as regras P1 implementadas (1 validação WARNING)
• Testes unitários passando com cobertura mínima de ~50 casos
• Nenhum teste existente quebrado
• Arquivo issue_rules.json criado com todos os níveis de erro
• Internacionalização completa em todas as mensagens (i18n obrigatório)
• Código seguindo padrões do packtools (build_response, filter_results, validações condicionais)
• Modelo de dados criado com extração adequada
• Validação de unicidade funcionando
• Validação de pontuação detectando todos os caracteres proibidos
• Validação de uppercase funcionando corretamente
• Validação de nomenclatura detectando variantes incorretas
• Validação de zero à esquerda funcionando
• Validação de presença de <supplement> funcionando
• Documentação inline clara (docstrings)

---

Referências

Documentação SPS:

• SPS 1.10 – <issue>: Número, Número Especial e Suplemento
• SPS 1.10 – Regras para Nomeação de Arquivos e Pastas

Padrões JATS:

• JATS 1.3 – <issue>
• JATS 1.3 – <volume>

Referências internas packtools:

• Internacionalização: Consultar conversas anteriores sobre implementação de i18n
• Implementações similares: article_doi.py (unicidade)
• Funções auxiliares: utils.py (build_response)

---

Labels Sugeridas

enhancement validation SPS-1.10 good-first-issue

---

Impacto Esperado

Antes:

• Conformidade SPS 1.10 para <issue>: X% (verificar validações existentes)
• Formatos inconsistentes podem passar sem detecção
• Uso incorreto de nomenclatura (supl, esp, etc.) não detectado
• Presença de pontuação e uppercase não detectada
• Zeros à esquerda não detectados
• Uso indevido de <supplement> não prevenido

Depois:

• Conformidade SPS 1.10 para <issue>: 70% (7 de 10 regras)
• Validação ERROR de formato (pontuação, uppercase)
• Validação ERROR de nomenclatura correta (suppl, spe)
• Validação CRITICAL contra uso de <supplement>
• Validação WARNING de zeros à esquerda
• ~50 testes unitários garantindo qualidade
• Internacionalização completa (PT/EN/ES)

Benefícios:

• Melhora a qualidade dos XMLs SciELO
• Garante consistência de formato entre documentos
• Previne erros de nomenclatura de suplementos e especiais
• Facilita processamento automatizado
• Reduz necessidade de correções manuais
• Melhora interoperabilidade com sistemas externos
• Facilita identificação correta de fascículos
• Promove conformidade com padrões SciELO
• Facilita manutenção e depuração de XMLs

Observações importantes:

• Implementar internacionalização ajustando as respostas das validações ao formato da função build_response em packtools/sps/validation/utils.py;
• Verificar e adicionar as validações no orquestrador: packtools/sps/validation/xml_validations.py e packtools/sps/validation/xml_validator.py
• Verificar a corretude dos testes exsitentes para a validação e complementar caso necessário;
• Realizar ajustes, caso necessário, nos modelos que são utilizados pelas validações, garantindo que o ajuste não interfira em possíveis usos atuais desses modelos.