Ir para o conteúdo

Guia de Desenvolvimento

Este guia documenta a estrutura do repositório logis, os comandos de automação do Makefile, como executar a suíte de testes, as regras de compatibilidade para QGIS 4 / Qt6, o papel dos scripts utilitários em tools/ e a instrução para servidor e build local da documentação.

1. Estrutura do Repositório

A organização do código fonte e dos artefatos do projeto é dividida da seguinte forma:

logis/
├── logis/                    # Código-fonte do plugin QGIS
│   ├── __init__.py           # Entrada do plugin (instancia LogisPlugin)
│   ├── logis_plugin.py       # Gerenciador da interface, menus e dock panels
│   ├── provider.py           # Processing Provider "logis"
│   ├── metadata.txt          # Metadados do plugin QGIS
│   ├── core/                 # Núcleo de lógica de negócios e algoritmos puros
│   │   ├── network/          # Pipelines de rede (osm_pipeline, snv_pipeline, graph_builder, od_matrix)
│   │   ├── connectors/       # Conectores HTTP/WFS/REST (osm, wfs, arcgis_rest)
│   │   ├── indicators/       # Indicadores (urban, regional, waste)
│   │   ├── routing/          # Algoritmos de roteirização (vrp, arc_routing)
│   │   ├── location/         # Otimização de localização de instalações (facility)
│   │   ├── downloader.py     # Cache em disco e gerenciador de downloads
│   │   ├── sources.py        # Registro declarativo de fontes de dados
│   │   └── qgis_compat.py    # Camada de compatibilidade Qt5/Qt6 e QGIS 3/4
│   ├── algorithms/           # Algoritmos do QGIS Processing (logis:*)
│   ├── gui/                  # Painéis de interface (dock panels) por módulo
│   └── i18n/                 # Arquivos de internacionalização (.ts e .qm)
├── tools/                    # Scripts de teste headless e validação em desenvolvimento
├── docs/                     # Documentação do projeto (MkDocs)
├── dist/                     # Pacotes zip gerados para distribuição
├── Makefile                  # Tarefas de automação de desenvolvimento
└── mkdocs.yml                # Configuração do site de documentação

2. Alvos do Makefile

O Makefile centraliza os comandos de desenvolvimento, instalação local no QGIS e empacotamento:

Alvo Descrição
help Exibe o resumo dos alvos disponíveis no Makefile.
deploy Cria um symlink do plugin no perfil default do QGIS 3 do sistema (~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/logis).
deploy-flatpak Cria um symlink no perfil default da instalação Flatpak do QGIS 3 (~/.var/app/org.qgis.qgis/data/QGIS/QGIS3/profiles/default/python/plugins/logis).
undeploy Remove o symlink instalado no perfil QGIS3 do sistema.
undeploy-flatpak Remove o symlink instalado no perfil Flatpak do QGIS3.
clean Limpa diretórios __pycache__ e arquivos compilados .pyc.
test Executa o smoke test estático de verificação de sintaxe Python sem exigir interface gráfica do QGIS.
package Gera o pacote zip de distribuição do plugin em dist/logis-<versão>.zip via qgis-plugin-ci.
i18n Extrai as strings marcadas com self.tr(...) para o arquivo de tradução logis/i18n/logis_pt_BR.ts.
transcompile Compila os arquivos de tradução .ts do Qt para binários .qm usando lrelease.
docs-deps Cria o ambiente virtual .venv-docs e instala as dependências de documentação de docs/requirements.txt.
docs-serve Sobe o servidor local de documentação (mkdocs serve), em http://127.0.0.1:8000.
docs-build Compila o site de documentação em modo estrito (mkdocs build --strict).

3. Como Rodar os Testes

O projeto utiliza duas estratégias complementares para validação e testes:

Smoke Test de Sintaxe

Para checar rapidamente a sintaxe Python de todos os arquivos do projeto sem dependência de ambiente QGIS rodando: 

make test

Suíte de Testes Unitários e de Integração

Para rodar a suíte completa de testes unitários com o pytest: 

python3 -m pytest -q

4. Regras de Compatibilidade Qt6 / QGIS 4

Para garantir que o logis seja totalmente compatível tanto com o QGIS 3 (Qt5/PyQt5) quanto com o futuro QGIS 4 (Qt6/PyQt6), todo o código deve seguir rigorosamente as três regras abaixo:

1. Enums Escopados (Scoped Enums)

O PyQt6 removeu os enums não escopados. Sempre acesse os enums utilizando o namespace completo da classe:

  • Qt.DockWidgetArea.RightDockWidgetArea (nunca Qt.RightDockWidgetArea)
  • QgsProcessing.SourceType.TypeVectorLine (nunca QgsProcessing.TypeVectorLine)
  • QgsProcessingParameterNumber.Type.Double (nunca QgsProcessingParameterNumber.Double)
  • QgsWkbTypes.Type.LineString / QgsWkbTypes.GeometryType.Line (nunca QgsWkbTypes.LineString)
  • QgsTask.Flag.CanCancel (nunca QgsTask.CanCancel)

2. Tipos de Campo via field_type()

Em Qt6, a enumeração QVariant.Type foi substituída por QMetaType.Type. Para evitar quebras ao instanciar campos de vetores (QgsField), utilize apenas a função auxiliar compatível do projeto:

from logis.core.qgis_compat import field_type
from qgis.PyQt.QtCore import QVariant

# Forma correta e agnóstica entre Qt5 e Qt6:
field = QgsField("nome", field_type(QVariant.String))

3. Proibição de exec_()

O método exec_() com underline legado do PyQt4/PyQt5 foi totalmente removido no PyQt6. Use exclusivamente exec() em caixas de diálogo (QDialog) e modais:

# Correto:
dialog.exec()

# Proibido:
dialog.exec_()

Para verificar se o seu ambiente atende às regras de compatibilidade, você pode rodar o utilitário tools/qgis4_compat_check.py.

5. Scripts de Utilidade (tools/)

Os scripts localizados em tools/ apoiam o desenvolvimento e a validação headless fora do ambiente GUI do QGIS:

  • tools/pilot_urbano_mg.py: Piloto headless ponta-a-ponta do Módulo Urbano (Fase F1). Encadeia a extração e tratamento OSM (osm_pipeline), a montagem do grafo (graph_builder) e o cálculo de matriz OD (od_matrix) para o município de Serra da Saudade/MG (code_muni=3166600).
  • tools/pilot_regional_mg.py: Piloto headless ponta-a-ponta do Módulo Regional (Fase F3). Encadeia o download e corte da malha SNV (snv_pipeline), montagem do grafo regional (graph_builder) e matriz OD (od_matrix) para o estado de Minas Gerais.
  • tools/qgis4_compat_check.py: Script de inspeção de compatibilidade entre QGIS 4 / Qt6 e QGIS 3 / Qt5. Relata a presença e suporte dos enums escopados, suporte a QMetaType em QgsField e suporte ao método .exec().
  • tools/verify_delivery_distance.py: Script de validação headless para o algoritmo logis:urban_delivery_distance. Carrega os dados da rede piloto, cria camadas em memória de depósitos e zonas e valida se as métricas de distância e tempo são calculadas corretamente pelo Processing Provider.

6. Como Rodar o Site Localmente

A documentação do logis é construída com o MkDocs e o tema Material for MkDocs.

Configuração e Servidor Local

Os alvos do Makefile cuidam do ambiente virtual de documentação, que fica isolado do plugin:

make docs-deps   # cria .venv-docs e instala docs/requirements.txt
make docs-serve  # sobe o servidor em http://127.0.0.1:8000

docs-serve já depende de docs-deps (roda antes automaticamente), e as dependências do site (MkDocs, Material etc.) vivem só no .venv-docs — nunca entram no ambiente do plugin QGIS.

Verificação Estrita antes do Commit

Antes de submeter modificações na documentação, execute:

make docs-build

Esse alvo roda mkdocs build --strict com o bloco validation: do mkdocs.yml ativo, de modo que página órfã (fora da nav), link quebrado ou âncora quebrada derrubam o build.