You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Manutenção, Qualidade de Código e Compatibilidade
Visão Geral
Conjunto de trabalhos técnicos focados em higiene do código, padronização, documentação arquitetural e correções de co
mpatibilidade com o ecossistema WordPress. Não adicionam funcionalidades de produto diretas, mas são essenciais para a
saúde a longo prazo do plugin, onboarding de novos desenvolvedores e estabilidade em produção.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Qualidade de Código
Lint Massivo de PHP
Commit 73c153c — Lint PHP code
• Refatoração de 31 arquivos PHP (+543/-251 linhas)
• Aplicação das regras do WordPress Coding Standards (WPCS):
• Espaçamento e indentação padronizados
• Uso correto de strict_types e type hints
• Padronização de nomes de variáveis e funções
• Ordem correta de parâmetros em funções do WordPress
• Escape de saída HTML com funções adequadas (esc_html(), esc_attr(), etc.)
• Arquivos afetados incluem todo o núcleo de IA, geocoding, settings, admin e o loader principal
Commit 446bd30 — Lint PHP code: warnings
• Correção de warnings restantes em 15 arquivos (+67/-54 linhas)
• Foco em:
• Variáveis não utilizadas
• Retornos implícitos
• DocBlocks incompletos
• Comparações loose vs strict
Adição de PHPDoc
Commit 9ab5bb9 — Add PHPDoc comments
• Documentação completa de 31 arquivos PHP (+1463/-787 linhas)
• Cada classe e método público/protegido recebeu:
• Descrição da responsabilidade
• @param com tipos e descrições
• @return com tipos
• @throws onde aplicável
• @SInCE tags para versionamento
• Arquivos documentados:
• src/includes/admin/dashboard-page.php
• src/includes/admin/welcome-page.php
• src/includes/ai/.php (todas as classes de IA)
• src/includes/class-ai-adapter.php
• src/includes/class-ai-handler.php
• src/includes/class-jeo.php
• src/includes/cli/class-ai-cli.php
• src/includes/geocode/.php
• src/includes/loaders.php
• src/includes/menu/class-menu.php
• src/includes/settings/*.php
• src/jeo.php
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Documentação Arquitetural
Commit 3a37922 — Add AI-aware documentation
• Criação do diretório .architecture/ com 15 arquivos markdown (+1369 linhas)
• Cada domínio do plugin recebeu documentação própria:
Arquivo Domínio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.architecture/README.md Índice geral e mapeamento de tareas
.architecture/ai/README.md Integração com IA (NeuronAI, RAG, bulk)
.architecture/blocks/README.md Blocos Gutenberg e sidebars
.architecture/build/README.md Webpack, scripts, bundles
.architecture/deployment/README.md Deploy para WordPress.org
.architecture/discovery/README.md Funcionalidade Discovery
.architecture/frontend/README.md Runtime de mapas, MapLibre/Mapbox
.architecture/geocoding/README.md Geocodificação e geolocalização de posts
.architecture/layers/README.md Custom Post Type de camadas
.architecture/maps/README.md Custom Post Type de mapas
.architecture/rest-api/README.md Endpoints customizados
.architecture/settings/README.md Páginas de admin e configurações
.architecture/storymap/README.md Storymap (scrollytelling)
.architecture/templates/README.md Templates e temas
AGENTS.md Convenções para agentes de IA
• A documentação segue o padrão exigido pelo projeto: toda alteração significativa em componentes, blocos, CPTs, rotas
EST ou settings deve atualizar tanto .architecture/ quanto AGENTS.md
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Compatibilidade e Correções
Reversão de Breaking Change
Commit 6bba9d5 — Revert breaking change on default longitude field
• Problema: Um commit anterior havia renomeado o campo de longitude de center_lon para center_lng em múltiplos arquivo
• Impacto: Mapas e camadas existentes paravam de carregar corretamente por inconsistência de nomes de atributos
• Solução: Reversão completa do nome do campo para center_lon em 7 arquivos:
• .architecture/stories-near-you/README.md
• src/includes/admin/dashboard-page.php
• src/includes/class-jeo.php
• src/includes/loaders.php
• src/includes/settings/class-settings.php
• src/includes/settings/settings-page.php
• src/includes/stories-near-you/class-stories-near-you.php
Commit 0821714 — Revert center_lng to center_lon for backwards compatibility
• Reversão adicional nos arquivos JavaScript que também haviam sido afetados:
• src/js/src/layers-sidebar/layers-sidebar.js
• src/js/src/map-blocks/index.js
• src/js/src/map-blocks/map-panel.js
• src/js/src/map-blocks/map-settings.js
• src/js/src/map-blocks/onetime-map-display.js
• src/js/src/maps-sidebar/maps-sidebar.js
• Total: 6 arquivos JS com +14/-13 linhas
Compatibilidade com WordPress 6.x
Commit 2fff735 — Tentatively fix map/layer preview in WP 6.x
• Correção na preview de mapas e camadas dentro do editor Gutenberg do WordPress 6.x
• Problema: O iframe do editor na versão 6.x carregava scripts de forma diferente, quebrando a inicialização do MapLib
• Solução: Ajuste no carregamento condicional de scripts no entry point src/js/src/map-blocks/index.js (+25/-1 linhas)
• Adicionada detecção de ambiente iframe e fallback de inicialização
Validação de Templates
Commit b243327 — Check if storymap CPT is not empty before assigning its template
• Problema: Erro fatal em alguns ambientes quando o CPT storymap não tinha posts cadastrados
• Solução: Adicionada verificação ! empty() antes de atribuir template ao storymap em src/includes/class-jeo.php (+6/-
linhas)
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Dashboard e Interface Administrativa
Clusters no Mapa do Dashboard
Commit 435c601 — Add clusters to dashboard map (Tratar Clusterização Mapa: Refinar a funcionalidade do mapa na página de visualização global. Implementar clusterização, paginação e filtragem para lidar com grande volume de georreferenciamentos. #538)
• Adicionado agrupamento de pins (clusters) no mapa do painel administrativo
• Substituída a renderização individual de markers por agrupamento dinâmico baseado em proximidade
• Melhoria significativa de performance quando há muitos posts geolocalizados
• Arquivo: src/includes/admin/dashboard-page.php (+148/-48 linhas)
Remoção de Dependência Carto
**Commit 1144123 — Remove dependency on Carto`
• Removida a dependência do serviço Carto (antigo provedor de tiles base)
• O plugin passa a usar exclusivamente MapLibre GL JS / Mapbox GL JS para tiles
• Arquivo: src/includes/admin/dashboard-page.php (+22/-1 linhas)
Estilização do Seletor de Range/Timeline
Commits 14e8473 e 8c48a61 — Style range picker / Improve styling of timeline range
• Melhorias visuais no componente de seleção de intervalo temporal do dashboard
• Ajustes de CSS inline no PHP para alinhamento e espaçamento
• Arquivo: src/includes/admin/dashboard-page.php (+37/-23 linhas no total)
Filtro de Modelos de IA
Commit c145250 — List only text-based models (Filtrar Modelos IA: Implementar filtro para remover modelos de IA que não sejam LLM de texto. Remover modelos como Dali, Lira ou quaisquer outros que não sejam de texto. #534)
• O seletor de modelos de IA no painel administrativo passa a listar apenas modelos textuais
• Problema: Modelos multimodais (visão, áudio) apareciam na lista mas não eram compatíveis com as tarefas de geocodifi
ção e RAG
• Solução: Filtragem por capability do modelo no class-ai-handler.php (+118/-58 linhas)
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Build e DevOps
Smoke Test de CI
Commit 55a1029 — Add zip extension on smoke test
• Adicionada extensão PHP zip no workflow de smoke test do GitHub Actions
• Necessária para compatibilidade com bibliotecas de exportação/importação de dados geoespaciais
• Arquivo: .github/workflows/wordpress-smoke.yml (+1/-1 linha)
Atualização de Dependências
Commit ab3af28 — Update Composer lockfile
• Atualização do composer.lock (+734/-2 linhas)
• Inclui atualizações de segurança e compatibilidade de pacotes PHP
Configuração Local de PHPCS
Commits anteriores (fora dos 30 mais recentes mas no escopo)
• Setup do PHPCS local para desenvolvimento sem dependência de CI
• Remoção do PHPUnit (não utilizado no projeto)
• Adição do arquivo .git-blame-ignore-revs para ignorar commits de formatação em blame
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Resumo de Impacto
Categoria Arquivos Afetados Linhas Modificadas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Lint PHP ~46 arquivos PHP ~2.000+ linhas
PHPDoc 31 arquivos PHP ~2.250 linhas
Documentação 15 arquivos markdown ~1.400 linhas novas
Compatibilidade WP 6.x 7 arquivos (JS + PHP) ~40 linhas
Dashboard 1 arquivo PHP ~200 linhas
CI/DevOps 2 arquivos ~735 linhas
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Notas de Impacto
• Zero breaking changes após as reversões de campos de longitude
• O lint e a adição de PHPDoc não alteram comportamento funcional — são mudanças puramente de estilo e documentação
• A documentação em .architecture/ é obrigatória para todo desenvolvimento futuro no projeto
• A remoção do Carto pode exigir reconfiguração de camadas antigas que ainda referenciavam tiles Carto
• O filtro de modelos textuais evita erros silenciosos quando usuários selecionavam modelos de visão para tarefas de t
to
Manutenção, Qualidade de Código e Compatibilidade
Visão Geral
Conjunto de trabalhos técnicos focados em higiene do código, padronização, documentação arquitetural e correções de co
mpatibilidade com o ecossistema WordPress. Não adicionam funcionalidades de produto diretas, mas são essenciais para a
saúde a longo prazo do plugin, onboarding de novos desenvolvedores e estabilidade em produção.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Lint Massivo de PHP
Commit 73c153c — Lint PHP code
• Refatoração de 31 arquivos PHP (+543/-251 linhas)
• Aplicação das regras do WordPress Coding Standards (WPCS):
• Espaçamento e indentação padronizados
• Uso correto de strict_types e type hints
• Padronização de nomes de variáveis e funções
• Ordem correta de parâmetros em funções do WordPress
• Escape de saída HTML com funções adequadas (esc_html(), esc_attr(), etc.)
• Arquivos afetados incluem todo o núcleo de IA, geocoding, settings, admin e o loader principal
Commit 446bd30 — Lint PHP code: warnings
• Correção de warnings restantes em 15 arquivos (+67/-54 linhas)
• Foco em:
• Variáveis não utilizadas
• Retornos implícitos
• DocBlocks incompletos
• Comparações loose vs strict
Adição de PHPDoc
Commit 9ab5bb9 — Add PHPDoc comments
• Documentação completa de 31 arquivos PHP (+1463/-787 linhas)
• Cada classe e método público/protegido recebeu:
• Descrição da responsabilidade
• @param com tipos e descrições
• @return com tipos
• @throws onde aplicável
• @SInCE tags para versionamento
• Arquivos documentados:
• src/includes/admin/dashboard-page.php
• src/includes/admin/welcome-page.php
• src/includes/ai/.php (todas as classes de IA)
• src/includes/class-ai-adapter.php
• src/includes/class-ai-handler.php
• src/includes/class-jeo.php
• src/includes/cli/class-ai-cli.php
• src/includes/geocode/.php
• src/includes/loaders.php
• src/includes/menu/class-menu.php
• src/includes/settings/*.php
• src/jeo.php
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Commit 3a37922 — Add AI-aware documentation
• Criação do diretório .architecture/ com 15 arquivos markdown (+1369 linhas)
• Cada domínio do plugin recebeu documentação própria:
Arquivo Domínio
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.architecture/README.md Índice geral e mapeamento de tareas
.architecture/ai/README.md Integração com IA (NeuronAI, RAG, bulk)
.architecture/blocks/README.md Blocos Gutenberg e sidebars
.architecture/build/README.md Webpack, scripts, bundles
.architecture/deployment/README.md Deploy para WordPress.org
.architecture/discovery/README.md Funcionalidade Discovery
.architecture/frontend/README.md Runtime de mapas, MapLibre/Mapbox
.architecture/geocoding/README.md Geocodificação e geolocalização de posts
.architecture/layers/README.md Custom Post Type de camadas
.architecture/maps/README.md Custom Post Type de mapas
.architecture/rest-api/README.md Endpoints customizados
.architecture/settings/README.md Páginas de admin e configurações
.architecture/storymap/README.md Storymap (scrollytelling)
.architecture/templates/README.md Templates e temas
AGENTS.md Convenções para agentes de IA
• A documentação segue o padrão exigido pelo projeto: toda alteração significativa em componentes, blocos, CPTs, rotas
EST ou settings deve atualizar tanto .architecture/ quanto AGENTS.md
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Reversão de Breaking Change
Commit 6bba9d5 — Revert breaking change on default longitude field
• Problema: Um commit anterior havia renomeado o campo de longitude de center_lon para center_lng em múltiplos arquivo
• Impacto: Mapas e camadas existentes paravam de carregar corretamente por inconsistência de nomes de atributos
• Solução: Reversão completa do nome do campo para center_lon em 7 arquivos:
• .architecture/stories-near-you/README.md
• src/includes/admin/dashboard-page.php
• src/includes/class-jeo.php
• src/includes/loaders.php
• src/includes/settings/class-settings.php
• src/includes/settings/settings-page.php
• src/includes/stories-near-you/class-stories-near-you.php
Commit 0821714 — Revert center_lng to center_lon for backwards compatibility
• Reversão adicional nos arquivos JavaScript que também haviam sido afetados:
• src/js/src/layers-sidebar/layers-sidebar.js
• src/js/src/map-blocks/index.js
• src/js/src/map-blocks/map-panel.js
• src/js/src/map-blocks/map-settings.js
• src/js/src/map-blocks/onetime-map-display.js
• src/js/src/maps-sidebar/maps-sidebar.js
• Total: 6 arquivos JS com +14/-13 linhas
Compatibilidade com WordPress 6.x
Commit 2fff735 — Tentatively fix map/layer preview in WP 6.x
• Correção na preview de mapas e camadas dentro do editor Gutenberg do WordPress 6.x
• Problema: O iframe do editor na versão 6.x carregava scripts de forma diferente, quebrando a inicialização do MapLib
• Solução: Ajuste no carregamento condicional de scripts no entry point src/js/src/map-blocks/index.js (+25/-1 linhas)
• Adicionada detecção de ambiente iframe e fallback de inicialização
Validação de Templates
Commit b243327 — Check if storymap CPT is not empty before assigning its template
• Problema: Erro fatal em alguns ambientes quando o CPT storymap não tinha posts cadastrados
• Solução: Adicionada verificação ! empty() antes de atribuir template ao storymap em src/includes/class-jeo.php (+6/-
linhas)
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Clusters no Mapa do Dashboard
Commit 435c601 — Add clusters to dashboard map (Tratar Clusterização Mapa: Refinar a funcionalidade do mapa na página de visualização global. Implementar clusterização, paginação e filtragem para lidar com grande volume de georreferenciamentos. #538)
• Adicionado agrupamento de pins (clusters) no mapa do painel administrativo
• Substituída a renderização individual de markers por agrupamento dinâmico baseado em proximidade
• Melhoria significativa de performance quando há muitos posts geolocalizados
• Arquivo: src/includes/admin/dashboard-page.php (+148/-48 linhas)
Remoção de Dependência Carto
**Commit 1144123 — Remove dependency on Carto`
• Removida a dependência do serviço Carto (antigo provedor de tiles base)
• O plugin passa a usar exclusivamente MapLibre GL JS / Mapbox GL JS para tiles
• Arquivo: src/includes/admin/dashboard-page.php (+22/-1 linhas)
Estilização do Seletor de Range/Timeline
Commits 14e8473 e 8c48a61 — Style range picker / Improve styling of timeline range
• Melhorias visuais no componente de seleção de intervalo temporal do dashboard
• Ajustes de CSS inline no PHP para alinhamento e espaçamento
• Arquivo: src/includes/admin/dashboard-page.php (+37/-23 linhas no total)
Filtro de Modelos de IA
Commit c145250 — List only text-based models (Filtrar Modelos IA: Implementar filtro para remover modelos de IA que não sejam LLM de texto. Remover modelos como Dali, Lira ou quaisquer outros que não sejam de texto. #534)
• O seletor de modelos de IA no painel administrativo passa a listar apenas modelos textuais
• Problema: Modelos multimodais (visão, áudio) apareciam na lista mas não eram compatíveis com as tarefas de geocodifi
ção e RAG
• Solução: Filtragem por capability do modelo no class-ai-handler.php (+118/-58 linhas)
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Smoke Test de CI
Commit 55a1029 — Add zip extension on smoke test
• Adicionada extensão PHP zip no workflow de smoke test do GitHub Actions
• Necessária para compatibilidade com bibliotecas de exportação/importação de dados geoespaciais
• Arquivo: .github/workflows/wordpress-smoke.yml (+1/-1 linha)
Atualização de Dependências
Commit ab3af28 — Update Composer lockfile
• Atualização do composer.lock (+734/-2 linhas)
• Inclui atualizações de segurança e compatibilidade de pacotes PHP
Configuração Local de PHPCS
Commits anteriores (fora dos 30 mais recentes mas no escopo)
• Setup do PHPCS local para desenvolvimento sem dependência de CI
• Remoção do PHPUnit (não utilizado no projeto)
• Adição do arquivo .git-blame-ignore-revs para ignorar commits de formatação em blame
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Resumo de Impacto
Categoria Arquivos Afetados Linhas Modificadas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Lint PHP ~46 arquivos PHP ~2.000+ linhas
PHPDoc 31 arquivos PHP ~2.250 linhas
Documentação 15 arquivos markdown ~1.400 linhas novas
Compatibilidade WP 6.x 7 arquivos (JS + PHP) ~40 linhas
Dashboard 1 arquivo PHP ~200 linhas
CI/DevOps 2 arquivos ~735 linhas
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Notas de Impacto
• Zero breaking changes após as reversões de campos de longitude
• O lint e a adição de PHPDoc não alteram comportamento funcional — são mudanças puramente de estilo e documentação
• A documentação em .architecture/ é obrigatória para todo desenvolvimento futuro no projeto
• A remoção do Carto pode exigir reconfiguração de camadas antigas que ainda referenciavam tiles Carto
• O filtro de modelos textuais evita erros silenciosos quando usuários selecionavam modelos de visão para tarefas de t
to
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────