Adicionar app `periodico`

[gitnnolabs]

Descrição da tarefa

Adicionar o app Django journal (singular) ao repositório scielo-tools.

O app gere o catálogo editorial de periódicos e fascículos (modelos Journal e Issue): metadados ISSN, volume/número/ano, painel Wagtail para gestão manual e sincronização periódica com a API SciELO Core (sync_journals_from_api, sync_issues_from_api via Celery). A implementação legada acopla-se a core.models.CommonControlField, core.models.CoreSyncState e utilitários em core.utils — o core do projeto atual está vazio ou mínimo e não deve ser pré-requisito.

O objetivo é tornar journal auto-suficiente e reutilizável:

• Banco de dados próprio com migrations em journal/migrations/ (tabelas prefixadas journal_).
• Telas Wagtail próprias (snippets Journal Manager: periódicos e fascículos, ícones, autocomplete).
• APIs REST (DRF) para consulta e gestão de periódicos/fascículos por sistemas externos ou por outros apps (manuscrito, integrações editoriais).
• Sem dependência do app manuscrito, ia, referencia ou sps.
• Portável para outro projeto Django/Wagtail com Celery e settings documentados.

Âmbito:

Módulo	Responsabilidade
journal/models.py	Modelos Journal (periódico) e Issue (fascículo); metadados ISSN, volume, número, ano, etc.
journal/sync_api.py	Sincronização paginada com API SciELO Core (journals e issues).
journal/tasks.py	Tarefas Celery task_sync_journals_from_api, task_sync_issues_from_api.
journal/wagtail_hooks.py	SnippetViewSetGroup "Journal Manager", ícones SVG, autocomplete.
journal/api/v1/	Endpoints REST (serializers, viewsets) para Journal e Issue.
journal/forms.py	Formulário admin Wagtail com registo de creator / updated_by (desacoplado de core.forms).
journal/apps.py	Configuração Django (JournalConfig).

Fora do âmbito desta issue:

• Adição do app manuscrito, ia, referencia ou sps.
• Sincronização de outros recursos Core (coleções, artigos publicados) — apenas journal/issue.
• Restauro completo do app core como dependência obrigatória.

Pré-requisitos (blockers)

Pré-requisito	Consumido por	Notas
djangorestframework	journal/api/	API REST
wagtail-autocomplete	journal/models.py, wagtail_hooks.py	AutocompletePanel em Issue
requests	sync_api.py (via helper HTTP)	Chamadas à API SciELO Core
Celery + Redis	journal/tasks.py	Sync assíncrono
Settings SciELO Core	sync_api.py	CORE_API_DOMAIN, CORE_JOURNAL_API_ENDPOINT, CORE_ISSUE_API_ENDPOINT, CORE_ISSUE_FROM_DATE_CREATED

Decisões de design para reusabilidade

1. Desacoplamento de core.models e core.forms:

   • Issue herda metadados de controlo (creator, updated_by, created, updated) via classe abstrata JournalMetadataModel e JournalAdminModelForm em journal/forms.py.
   • Journal permanece modelo simples (sem campos de auditoria), salvo decisão em contrário na implementação.

2. Estado de sincronização próprio:

   • Modelo JournalSyncState em journal/models.py (recursos journal e issue), com helpers em journal/utils/sync_state.py.

3. Cliente HTTP próprio:

   • Helper fetch_data em journal/utils/requester.py, sem import de core.

4. API REST:

   • Camada DRF para Journal e Issue, além do sync interno com a API Core — requisito de reuso e integração agnóstica (RCT).

Subtarefas

• Criar o app journal/ na raiz do projeto com a estrutura de módulos listada no âmbito.
• Implementar modelos Journal, Issue e JournalSyncState com migrations próprias.
• Criar journal/forms.py com JournalAdminModelForm e JournalMetadataModel.
• Implementar journal/utils/sync_state.py e journal/utils/requester.py.
• Implementar sync_api.py e tasks.py (sync paginado Core + Celery).
• Criar journal/api/v1/serializers.py e views.py com viewsets para Journal e Issue.
• Implementar wagtail_hooks.py (snippets, ícones, autocomplete).
• Registrar "journal" em LOCAL_APPS (config/settings/base.py).
• Adicionar settings Core em config/settings/base.py (variáveis de ambiente com defaults documentados).
• Registrar rotas REST em config/urls.py ou router DRF global:
  • GET/POST /api/v1/journal/ (recurso Journal)
  • GET/POST /api/v1/journal/issue/ (recurso Issue)
  • POST /api/v1/journal/sync/journal/ (disparo de sync, autenticado)
  • POST /api/v1/journal/sync/issue/ (disparo de sync, autenticado)
• Adicionar templates de ícones Wagtail (journal.svg, issue.svg).
• Ajustar config/menu.py para get_menu_order("journal").
• Gerar e aplicar migrations:

  python manage.py makemigrations journal
  python manage.py migrate

• Smoke test no shell e na API autenticada.

API pública a preservar / expor

Serviços Python (journal.sync_api)

Função	Uso
sync_journals_from_api(collection_acron=None, issn_scielo=None, from_date_updated=None)	Importa/atualiza periódicos da API Core
sync_issues_from_api(issn_scielo=None, from_date_updated=None)	Importa fascículos para periódicos já registados
get_or_create_issue_from_api_data(issue_data)	Upsert de fascículo a partir de payload Core
build_api_url_core(domain, endpoint, params)	Construção de URL paginada

Tarefas Celery (journal.tasks)

• task_sync_journals_from_api(**kwargs)
• task_sync_issues_from_api(**kwargs)

Endpoints REST

Método	Endpoint	Descrição
GET	/api/v1/journal/	Lista periódicos (filtro por issn, acronym, title)
GET	/api/v1/journal/{id}/	Detalhe de periódico
POST	/api/v1/journal/	Cria periódico (autenticado)
GET	/api/v1/journal/issue/	Lista fascículos (filtro por journal, year, volume)
GET	/api/v1/journal/issue/{id}/	Detalhe de fascículo
POST	/api/v1/journal/issue/	Cria fascículo (autenticado)
POST	/api/v1/journal/sync/journal/	Dispara sync Celery com periódicos Core
POST	/api/v1/journal/sync/issue/	Dispara sync Celery de fascículos

Autenticação: IsAuthenticated (JWT/sessão conforme projeto).

Wagtail autocomplete

• Journal.autocomplete_search_field = "title"
• Issue.autocomplete_custom_queryset_filter — filtro por journal no painel de artigos (consumido futuramente por manuscrito).

Critérios de aceite

• python manage.py check sem erros com journal em LOCAL_APPS.
• Nenhum import de core.models, core.forms ou manuscrito dentro de journal/.
• Tabelas journal_journal, journal_issue, journal_journalsyncstate criadas via migrations.
• Menu Wagtail "Journal Manager" exibe periódicos e fascículos com ícones customizados.
• GET /api/v1/journal/ responde com lista paginada (autenticado).
• POST /api/v1/journal/sync/journal/ enfileira tarefa Celery sem erro (com settings Core válidos ou mock em teste).
• Autocomplete de Issue filtra por journal no Wagtail admin.
• App instalável em projeto Django+Wagtail sem os demais apps SciELO Tools (exceto dependências de framework).

Como testar manualmente

1. Subir ambiente: make build && make up && make django_migrate.
2. Acessar Wagtail admin → Journal Manager → criar um periódico manualmente (título, ISSN).
3. Criar um fascículo ligado ao periódico (volume, número, ano).
4. No shell:

   from journal.models import Journal, Issue
   from journal.sync_api import sync_journals_from_api
   print(Journal.objects.count(), Issue.objects.count())

5. Testar API autenticada:

   curl -H "Authorization: Bearer <token>" http://localhost:8009/api/v1/journal/

6. (Opcional, com rede) Disparar sync:

   from journal.tasks import task_sync_journals_from_api
   task_sync_journals_from_api.delay()

Considerações e notas

• Nomenclatura: app Django journal (singular); modelos Journal (periódico) e Issue (fascículo). A tabela do modelo Journal será journal_journal (padrão Django).
• Consumidores futuros: manuscrito referencia Journal e Issue via FK em Article; sps usa metadados de journal/issue na geração XML. O journal deve ser pré-requisito do manuscrito.
• SciELO Core: sync depende de conectividade com https://core.scielo.org (ou CORE_API_DOMAIN configurável). Em CI, mockar respostas ou marcar testes de integração como opcionais.
• API REST: camada DRF incluída nesta issue como requisito de reuso.
• Issue vs fascículo: na UI Wagtail o label pode permanecer "Issue" (inglês); na documentação em português usar "fascículo".
• Plano de fragmentação: ver docs/plans/2026-06-28-fragmentar-manuscrito.md.

Referências

• API SciELO Core: https://core.scielo.org/api/v2/pid/journal/
• Settings sugeridos: CORE_API_DOMAIN, CORE_JOURNAL_API_ENDPOINT, CORE_ISSUE_API_ENDPOINT, CORE_ISSUE_FROM_DATE_CREATED