docs: criar insumos de documentação para v2.x e v3.x#954
Merged
Conversation
2 tasks
Copilot
AI
changed the title
[WIP] Create inputs for technical documentation
Aguardando esclarecimento de escopo — nenhuma alteração realizada
May 5, 2026
Member
|
@copilot não é um issue para modificação no código. É um issue para criar documentação das versão v2.x e v3.x |
Agent-Logs-Url: https://github.com/scieloorg/scms-upload/sessions/58694732-da3f-4a62-abaf-109fd0ea4f11 Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>
Contributor
Author
Entendido — sem mudanças de código. Em
|
Copilot
AI
changed the title
Aguardando esclarecimento de escopo — nenhuma alteração realizada
docs: criar insumos de documentação para v2.x e v3.x
May 5, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Este PR adiciona insumos de documentação técnica para as linhas v2.x e v3.x do scms-upload, descrevendo propósito, arquitetura, componentes (apps), funcionalidades e convenções de cada linha, com referência explícita aos branches/versões usadas como base.
Changes:
- Adiciona
docs/v2.x/README.mdcom visão geral da linha 2.x (migração/publicação do legado e convenções principais). - Adiciona
docs/v3.x/README.mdcom visão geral da linha 3.x (ênfase no appuploade fluxo de QA), incluindo seção comparativa vs. 2.x.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| docs/v2.x/README.md | Documento técnico da linha 2.x (propósito, stack, apps, pipeline de migração/publicação, convenções e referências). |
| docs/v3.x/README.md | Documento técnico da linha 3.x (foco no app upload, estados/fluxo de QA, tarefas e diferenças vs. 2.x). |
| | Framework web | Django | 5.2.3 | | ||
| | CMS | Wagtail | (admin para gestão de conteúdo) | | ||
| | Tarefas assíncronas | Celery | 5.5.3 (com `django-celery-beat` 2.8.1) | | ||
| | Broker / cache | Redis | 5.x | |
| | Framework web | Django | 5.2.3 | | ||
| | CMS | Wagtail | (admin para gestão de conteúdo) | | ||
| | Tarefas assíncronas | Celery | 5.5.3 (com `django-celery-beat` 2.8.1) | | ||
| | Broker / cache | Redis | 5.x | |
Comment on lines
+121
to
+138
| Tarefas Celery em `upload/tasks.py` (priority 0): | ||
|
|
||
| - `task_optimise_package(file_path)` — pré-processamento do ZIP recebido. | ||
| - `task_receive_packages(user_id, pkg_zip_id)` / `task_receive_package(user_id, pkg_id)` — | ||
| ingestão de lote / individual. | ||
| - `task_validate_xml_structure(...)` — valida o XML usando | ||
| `packtools.sps.validation.xml_structure.StructureValidator`. | ||
| - `task_validate_xml_content(...)` — valida o conteúdo do XML | ||
| (`upload.validation.xml_data_checker.XMLDataChecker`). | ||
| - `task_validate_assets(package_id, xml_path, package_files, xml_assets)` — | ||
| valida figuras/ativos. | ||
| - `task_validate_renditions(...)` / `task_validate_renditions_content(...)` — | ||
| valida PDFs e seu conteúdo (`upload.validation.rendition_validation`). | ||
| - `task_validate_webpages_content(package_id)` — valida páginas renderizadas | ||
| (`upload.validation.html_validation.validate_webpage`). | ||
| - `task_publish_article(...)` — publica o artigo aprovado. | ||
| - `task_complete_journal_data(...)` / `task_complete_issue_data(...)` — | ||
| preenche metadados de periódico/fascículo a partir do pacote. |
Comment on lines
+55
to
+67
| | Empacotamento | Docker + `docker-compose` | `local.yml`, `production-v3.0.0rc4.yml` | | ||
|
|
||
| > Em relação à 2.x: a 3.x usa **versões anteriores** de `packtools` e | ||
| > `scielo_classic_website`. Isso reflete o ciclo de release das duas linhas | ||
| > (a 3.x foi cortada antes das atualizações que entraram na 2.x mais | ||
| > recente). Verifique compatibilidade ao realizar *backports*. | ||
|
|
||
| ### 2.2 Containers (compose) | ||
|
|
||
| Idênticos à 2.x: `django`, `celeryworker`, `celerybeat`, `flower`, | ||
| `postgres`, `redis`, `minio`, `docs`. O arquivo de produção de referência | ||
| nesta linha é `production-v3.0.0rc4.yml`. | ||
|
|
Comment on lines
+64
to
+69
| - `flower` — painel de monitoramento Celery. | ||
| - `postgres` — banco relacional. | ||
| - `redis` — broker e backend de cache/resultados. | ||
| - `minio` — armazenamento de arquivos (XML, PDF, ativos, ZIPs). | ||
| - `docs` — servidor Sphinx para documentação. | ||
|
|
Comment on lines
+64
to
+66
| Idênticos à 2.x: `django`, `celeryworker`, `celerybeat`, `flower`, | ||
| `postgres`, `redis`, `minio`, `docs`. O arquivo de produção de referência | ||
| nesta linha é `production-v3.0.0rc4.yml`. |
Comment on lines
+278
to
+280
| A documentação Sphinx pode ser servida com: | ||
|
|
||
| ```bash |
Comment on lines
+129
to
+135
| (`upload.validation.xml_data_checker.XMLDataChecker`). | ||
| - `task_validate_assets(package_id, xml_path, package_files, xml_assets)` — | ||
| valida figuras/ativos. | ||
| - `task_validate_renditions(...)` / `task_validate_renditions_content(...)` — | ||
| valida PDFs e seu conteúdo (`upload.validation.rendition_validation`). | ||
| - `task_validate_webpages_content(package_id)` — valida páginas renderizadas | ||
| (`upload.validation.html_validation.validate_webpage`). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O que esse PR faz?
Cria insumos de documentação técnica para as duas linhas de versões do
scms-upload, conforme solicitado no issue:docs/v2.x/README.md— descrição da versão 2.x elaborada a partir do branchmain(referênciav2.12.0rc6).docs/v3.x/README.md— descrição da versão 3.x elaborada a partir do branchrc(referênciav3.0.0rc20).Cada documento cobre: propósito da versão, arquitetura geral (Django 5.2.3 + Wagtail + Celery + Redis + PostgreSQL + MinIO), stack tecnológica e containers, componentes (todos os apps Django listados em
LOCAL_APPScom suas responsabilidades), funcionalidades principais, estrutura de diretórios em alto nível, comandos doMakefile, convenções importantes (CommonControlField, sanitização de camposdetail/JSON,BaseProc.get_or_create, fachadaproc/controller.py,CommonControlFieldViewSet) e versão de referência.O documento da v3.x destaca o que muda em relação à v2.x — especialmente o app
uploadativado emINSTALLED_APPS, descrevendo modelos (Package,PackageZip,ValidationReport,UploadValidator), as tarefas Celery emupload/tasks.py, o fluxo completo de estadosPS_*doPackage(desubmittedapublished/required-erratum/required-update/depublished/archived) e uma tabela comparativa v2.x vs v3.x cobrindo dependências (packtools,scielo_classic_website), entradas do menu Wagtail (upload,upload-error),production-v3.0.0rc4.yml, ajustes emPublicationAPI(parâmetroenabled, fluxo de auth/validação revisto, exceção tratada empublish_article_on_website), refatoração deOperation.start/exclude_eventse tratamento deMultipleObjectsReturnedemHTMLXML.Nenhuma alteração de código foi feita — apenas adição de arquivos markdown sob
docs/.Onde a revisão poderia começar?
docs/v2.x/README.mddocs/v3.x/README.mdComo este poderia ser testado manualmente?
Por se tratar exclusivamente de conteúdo markdown, basta abrir os dois arquivos no GitHub (ou em qualquer renderizador markdown) e verificar:
LOCAL_APPSdeconfig/settings/base.pyem cada branch (mainpara v2.x,rcpara v3.x).proc/tasks.py,upload/tasks.py,upload/choices.py,migration/choices.py,tracker/choices.pyepid_provider/choices.py.config/menu.py,requirements/base.txt, appuploadhabilitado/desabilitado).Opcionalmente, é possível subir o servidor Sphinx local (
docker-compose -f local.yml up docs) — embora os novos arquivos sejam markdown puro e não estejam ligados aotoctreedo Sphinx (foram criados como insumos, conforme o título do issue, e não como parte da árvore Sphinx).Algum cenário de contexto que queira dar?
Após o esclarecimento de @robertatakenaka no PR ("não é um issue para modificação no código. É um issue para criar documentação das versão v2.x e v3.x"), o escopo foi confirmado como puramente documental. Os dois branches (
mainerc) foram consultados para extrair as informações; em particular,maincompartilha quase toda a base de apps comrc, sendo o appupload(recepção e QA de pacotes SPS por usuários) o principal diferenciador da linha 3.x. Esse contraste é o eixo central do documento da v3.x.Screenshots
N/A — a mudança é apenas de conteúdo markdown.
Referências
maindo repositórioscieloorg/scms-upload(v2.12.0rc6) —config/settings/base.py,config/menu.py,requirements/base.txt,proc/tasks.py,migration/,pid_provider/,tracker/choices.py,publication/.rcdo repositórioscieloorg/scms-upload(v3.0.0rc20) — mesmos arquivos acima eupload/(tasks.py,models.py,choices.py,validation/,controller.py)..github/pull_request_template.md.