Adicionar app `SPS`

[gitnnolabs]

Descrição da tarefa

Adicionar o app Django sps ao repositório scielo-tools

Hoje, a lógica de conformidade SPS (geração de XML, marcação de citações no DOCX, validação packtools, HTML e PDF) está implementada no pacote sps/, mas só é utilizável no monólito quando o app manuscrito e as dependências satélite (rotulagem, docx_parser) estão presentes e corretamente configurados. O objetivo desta issue é tornar o sps uma camada isolada e reutilizável:

• Sem dependência do app manuscrito, ia ou referencia.
• Contrato Python estável (sps.xml, sps.xref, sps.utils, sps.exceptions) consumível por qualquer app Django ou script do projeto (manuscrito, spsvalidator, integrações futuras).
• Auto-suficiente no âmbito da conformidade SPS: registo em INSTALLED_APPS, settings documentados, dependências explícitas em requirements/, smoke tests próprios.
• Sem modelos de base de dados — módulo de lógica pura (models.py vazio); não exige migrations.

Âmbito:

Módulo	Responsabilidade
sps/xml.py	Geração de XML SPS a partir de DOCX + estrutura editorial (get_xml)
sps/xref.py	Marcação e validação de citações no DOCX (ABNT, Vancouver bracket/superscript)
sps/utils.py	Validação packtools (XML e pacote .zip), geração HTML e PDF
sps/exceptions.py	Exceções de domínio (XMLFileValidationError, SPSPackageValidationError, etc.)
sps/apps.py	Registo Django (SPSConfig)

Fora do âmbito desta issue:

• Adição do app manuscrito, ia, referencia ou periodico.
• API REST / JWT (DRF) — contrato inicial é biblioteca Python; API pode ser issue futura.
• Migração de manuscrito/utils/xml_utils.py para sps/ (melhoria posterior).
• Integração do pipeline editorial completo (DOCX → artigo → publicação).

Subtarefas

• Copiar o pacote sps/`` para a raiz de scielo-tools(6 ficheiros:apps.py, exceptions.py, models.py, utils.py, xml.py, xref.py`).

• Registar "sps" em LOCAL_APPS em config/settings/base.py.

• Adicionar dependências em requirements/base.txt:

  • lxml==4.9.4
  • python-docx==1.1.2
  • git+https://git@github.com/scieloorg/packtools@4.12.6#egg=packtools

• Adicionar pacote rotulagem .

• Adicionar pacote docx_parser e layout docx_parser/layouts/two_cols.docx.

• Configurar HTML_GENERATION_CONFIG em config/settings/base.py (paths de CSS/JS estáticos compatíveis com o projeto).

• Garantir LibreOffice (soffice) no container Django local ou documentar instalação manual.

• Avaliar e, se necessário, tornar opcional o uso de wagtail.images.get_image_model em sps/xml.py (parâmetro image_resolver ou fallback sem Wagtail).

• Criar testes smoke mínimos em sps/tests/ (imports, validate_zip com fixture, xref.validate_marks com DOCX de exemplo).

• Executar smoke test no shell Django:

  python manage.py shell

  from sps.xml import get_xml
  from sps import utils as sps_utils
  from sps.xref import is_marked, mark_references, validate_marks

API pública a preservar / expor

Contrato consumido por manuscrito (futuro), spsvalidator e outros apps:

sps.xml

Função	Uso
get_xml(article_docx, data_front, data, data_back, xref_map=None)	Geração de XML SPS a partir da estrutura editorial

sps.xref

Função	Uso
is_marked(doc)	Verifica se o DOCX já tem citações marcadas
mark_references(doc)	Marca citações e referências no DOCX
validate_marks(doc)	Valida consistência hyperlinks ↔ bookmarks
read_marks(doc)	Lê marcas existentes
build_text_xref_replacer(doc)	Função de substituição de xref em texto
make_text_xref_fn_from_refs(ref_items)	Função xref a partir da lista de referências
apply_xml_xrefs_to_docx(doc, xml_tree)	Aplica xrefs do XML ao DOCX (pipeline PDF)

sps.utils

Função	Uso
validate_xml_document(xml_file_path, output_root_dir, params)	Validação SPS de um XML
validate_zip(zip_path)	Validação de pacote SPS .zip
generate_html_for_xml_document(xml_file_path, output_root_dir, config, asset_url_map=None)	HTML via packtools
generate_pdf_for_xml_document(xml_file_path, output_root_dir, params)	PDF via packtools + LibreOffice

sps.exceptions

• XMLFileParsingError, XMLFileValidationError, XMLFileDocxGenerationError
• XMLFilePDFGenerationError, XMLFileHTMLGenerationError, SPSPackageValidationError

Critérios de aceite

• python manage.py check executa sem erros com sps em LOCAL_APPS.
• Nenhum import de manuscrito, ia ou referencia dentro de sps/.
• make build resolve dependências (incluindo packtools via git).
• Imports smoke no django_shell sem ImportError.
• API pública listada acima disponível com as mesmas assinaturas.
• HTML_GENERATION_CONFIG acessível via django.conf.settings.
• generate_pdf_for_xml_document encontra docx_parser/layouts/two_cols.docx.
• Pelo menos um teste automatizado em sps/tests/ passa no CI.
• LibreOffice disponível no Docker local para conversão DOCX → PDF (ou documentado como opcional).

Como testar manualmente

1. Subir ambiente: make build && make up && make django_migrate.

2. Abrir shell: make django_shell.

3. Confirmar imports da API pública (sem ImportError).

4. Validar um pacote SPS .zip existente:

   from sps import utils
   rows, exceptions = utils.validate_zip("/caminho/para/pacote.zip")
   print(len(rows), len(exceptions))

5. (Opcional) Com DOCX de teste, exercitar marcação xref:

   from docx import Document
   from sps.xref import mark_references, validate_marks
   doc = Document("/caminho/artigo.docx")
   marked = mark_references(doc)
   print(validate_marks(marked))

Considerações e notas

• Reutilização: o app sps já é logicamente separado do manuscrito
• Sem testes próprios no initial: cobertura indireta em manuscrito/tests/; esta issue introduz testes mínimos em sps/tests/.
• packtools via git: CI precisa de acesso a scieloorg/packtools durante o build Docker.
• LibreOffice é dependência de sistema, não pip — relevante para Docker, produção e CI se testes de PDF forem incluídos.
• Acoplamento Wagtail: sps/xml.py usa get_image_model() para resolver imagens por PK; para reuso fora de Wagtail, considerar callback injetável na fase de implementação.
• Nomenclatura RCT vs código: o RCT menciona xml_manager; no initial o equivalente é sps/ + trechos em manuscrito/utils/xml_utils.py. Esta issue cobre apenas sps/.
• Distinção de fluxos: sps.xref.mark_references(doc) marca citações no DOCX (hyperlinks/bookmarks); referencia + ia marcam bibliografia estruturada (JSON/XML JATS). São complementares, não substitutos.
• Plano de fragmentação: ver docs/plans/2026-06-28-fragmentar-manuscrito.md (issue chore(deps): bump actions/checkout from 6 to 7 #3 na sequência sugerida).

Referências

• RCT SciELO Tools v4.0 — conformidade SPS via packtools