Adicionar app `referencia`

[gitnnolabs]

Descrição da tarefa

Adicionar o app Django referencia (renomeado do original references no singular) ao repositório scielo-tools.

A aplicação de referências é responsável por receber strings de citações textuais (mixed citations), normalizá-las, gerar o checksum e utilizar o serviço da aplicação ia (mark_references via LLMService) para extrair os elementos estruturados (autores, ano, volume, páginas, periódico, etc.) salvando-os em formato JSON e XML.

Esta app deve ser totalmente isolada, conter migrations próprias, suas próprias telas no Wagtail, suas próprias APIs REST (DRF) e ser estruturada de forma a ser reutilizável em outros projetos que dependam apenas do app ia.

Âmbito:

Módulo	Responsabilidade
referencia/models.py	Modelos Reference (a citação textual) e ElementCitation (os dados estruturados retornados e convertidos para XML).
referencia/data_utils.py	Função auxiliar de conversão para XML JATS (get_xml) e tarefa Celery assíncrona (get_reference) para processamento via IA.
referencia/wagtail_hooks.py	Painel administrativo no Wagtail para criação de lotes de referências e listagem de citações processadas.
referencia/api/v1/	Endpoints REST (via Django REST Framework) contendo serializers e views para receber submissões externas de citações.
referencia/apps.py	Configuração do Django App (ReferenciaConfig).

Decisões de Design para Reusabilidade (Auto-suficiência):

1. Desacoplamento de dependências globais:
   • Ajustar todos os imports que apontavam para ai para utilizarem o novo app ia (singular).
   • Garantir que o app referencia dependa apenas do framework Django, Wagtail e do app local ia.
2. REST API Isolada e Reutilizável:
   • O app deve conter sua própria rota de API no padrão /api/v1/referencia/ herdando de GenericViewSet e CreateModelMixin.
   • Outras aplicações no futuro (como manuscripts) podem usar a API REST ou importar os modelos diretamente de forma desacoplada.

Fora do âmbito desta issue:

• Integração da marcação com o fluxo do app manuscripts.
• Criação/migração da aplicação manuscripts.

---

Pré-requisitos (blockers)

Pré-requisito	Consumido por	Notas
ia (App Django)	referencia/data_utils.py	O app ia deve estar instalado e configurado no projeto (dependência direta de stz_norm e mark_references).
djangorestframework	referencia/api/	Necessário para expor as views DRF de processamento de referências.
lxml	referencia/data_utils.py	Processamento e manipulação de tags XML do elemento de citação.
django-compressor / wagtail-json-widget	referencia/models.py	Interface rica do JSONEditorWidget no admin do Wagtail.

---

Subtarefas

• Criar a pasta do app referencia/ na raiz do projeto
• Renomear todas as referências internas de references para referencia (ex: imports, nome da app, meta options).
• Ajustar imports de ai para ia em todos os arquivos de referencia/ (ex: from ia.utils.normalizers import stz_norm e from ia.references import mark_references).
• Registrar "referencia" na lista LOCAL_APPS em config/settings/base.py.
• Adicionar dependências necessárias em requirements/base.txt caso não estejam presentes:
  • lxml
  • djangorestframework
  • wagtail-json-widget
• Rodar o comando de geração de migrações iniciais para a app:

  python manage.py makemigrations referencia

• Executar as migrações no banco local:

  python manage.py migrate

• Registrar o roteamento das APIs REST da app referencia no roteador global do DRF em config/urls.py.
• Garantir que o painel administrativo do Wagtail exiba a aba "References" no menu de snippets.
• Realizar smoke test no shell Django:

  python manage.py shell

  from referencia.data_utils import get_xml
  # Garantir que a geração JATS XML baseada no parser lxml funciona sem erros

---

API pública a preservar / expor

Contratos consumidos externamente pelas demais aplicações:

referencia.data_utils

• get_xml(json_reference): Converte a estrutura de resposta JSON da IA em um nó XML <element-citation> JATS compatível.
• get_reference(obj_id): Tarefa Celery (ou chamada direta síncrona) que consome a IA e atualiza o status do objeto Reference.

Endpoints REST API

• POST /api/v1/referencia/ (ou endpoint associado):
  • Request Payload:

    {
      "references": "Citação textual completa...",
      "type": "json" // ou "xml"
    }

  • Response:

    {
      "message": "reference: { ... }" // JSON da citação ou XML JATS
    }

---

Critérios de aceite

• O comando python manage.py check executa sem erros de integridade.
• A API REST POST /api/v1/referencia/ responde corretamente a requisições autenticadas.
• As tabelas prefixadas com referencia_ são criadas com sucesso no banco de dados.
• O snippet administrativo de referências do Wagtail permite criar itens manualmente colando referências textuais e dispara com sucesso o fluxo de marcação.

---

Como testar manualmente

1. Subir o ambiente local (make build && make up).
2. Executar as migrações com sucesso.
3. No console Django (python manage.py shell), testar o helper de criação JATS XML:

   import json
   from referencia.data_utils import get_xml
   from lxml import etree
   sample_json = json.dumps({"reftype": "journal", "title": "Test Title", "source": "Nature", "date": "2024"})
   xml_node = get_xml(sample_json)
   print(etree.tostring(xml_node, pretty_print=True, encoding='unicode'))

4. Testar o endpoint REST autenticado enviando uma requisição POST e validando o processamento assíncrono/síncrono.