req-123: Customização de Menus Administrativos: Labels e Ordenação em Módulos Grupos e Override de Componentes por Projeto

• Status do intake: implemented-pending-homologation

• Data: 2026-08-20

• Origem: demanda do usuário para flexibilizar a navegação administrativa (menu do sistema), permitindo customizar o rótulo de exibição dos grupos (menu_label), a prioridade de ordenação dos grupos no menu (ordemMenu) e a possibilidade de projetos (config-project.php) sobrescreverem o componente visual do menu por layout via $_GESTOR['project-admin-menu-components']

• Classificação: nova funcionalidade, banco de dados (Phinx), motor core (gestor_pagina_menu), CRUD modulos-grupos, arquitetura de componentes

• Batch candidato: BATCH-125

1. Contexto e Objetivos

No Conn2Flow, a navegação do painel administrativo é gerada dinamicamente pela função gestor_pagina_menu() em gestor/gestor.php. Os módulos são agrupados pelas categorias definidas no módulo /modulos-grupos/ (modulos_grupos), onde atualmente apenas o campo nome é utilizado como rótulo de exibição e a ordenação é primariamente alfabética.

Além disso, com a evolução dos projetos (como [REDACTED], [REDACTED], etc.), surgiu a necessidade de permitir que cada projeto defina layouts administrativos próprios e utilize componentes visuais de menu customizados sem alterar o core do sistema.

Esta requisição atende a esses objetivos estruturando:

1. Rótulo Personalizado do Menu (menu_label): Campo no módulo modulos-grupos que define como o grupo será exibido no menu. Caso não informado, o sistema utiliza o nome como fallback;

2. Prioridade de Ordenação do Menu (ordemMenu): Campo no módulo modulos-grupos para definir a ordem de exibição dos grupos, tendo precedência sobre a ordenação alfabética padrão;

3. Override de Componente de Menu por Projeto ($_GESTOR['project-admin-menu-components']): Capacidade de registrar no config-project.php uma tabela de correspondência (layout $\rightarrow$ componente) que substitui o componente de menu padrão (menu-principal-sistema-tailwind ou menu-principal-sistema), mantendo o fallback padrão ativo quando não configurado.

2. Escopo Técnico Requerido

Módulo 1: Migração Phinx e Schema do Banco de Dados

• Arquivo de Migração: Criar migração Phinx em gestor/db/migrations/ (ex: YYYYMMDDHHMMSS_alter_modulos_grupos_add_menu_label.php).

• Estrutura:

  • Adicionar coluna menu_label (string / varchar(255), null => true, default => null) na tabela modulos_grupos.

  • Garantir a presença e integridade da coluna ordemMenu (integer, null => true, default => null) na tabela modulos_grupos.

  • Garantir degradação graciosa com checagem de existência de coluna via schema helpers.

Módulo 2: CRUD do Módulo /modulos-grupos/

• Localização: gestor/modulos/modulos-grupos/

  • modulos-grupos.php

  • modulos-grupos.json

  • Telas HTML em resources/pt-br/pages/ e resources/en/pages/ (modulos-grupos-adicionar, modulos-grupos-editar, modulos-grupos-clonar).

• Campos da Interface:

  • nome: Nome identificador do grupo (obrigatório, gera o id textual como hoje).

  • menu_label: "Rótulo do Menu" / "Menu Label" (opcional). Placeholder explicativo: "Se não preenchido, usa o Nome".

  • ordemMenu: "Ordem no Menu" / "Menu Order" (opcional / número inteiro). Placeholder: "Ex: 1, 2, 3...".

• Processamento de Backend:

  • Incluir menu_label e ordemMenu em $camposBanco nas operações de adicionar, editar e clonar.

  • Gravar menu_label como texto limpo e ordemMenu como inteiro (ou NULL quando não preenchido).

  • Registrar alterações no histórico de auditoria (interface_historico_incluir).

  • Adicionar variáveis de internacionalização (form-menu-label-label, form-menu-label-placeholder, form-ordem-menu-label, form-ordem-menu-placeholder, etc.) em pt-br e en no modulos-grupos.json.

Módulo 3: Motor de Menu do Core (gestor_pagina_menu() em gestor/gestor.php)

• Localização: gestor/gestor.php na função gestor_pagina_menu().

• Ajustes de Consulta e Ordenação:

  • A consulta na tabela modulos_grupos deve selecionar id, nome, menu_label e ordemMenu.

  • Ordenação SQL: ordenar por prioridade de ordemMenu (grupos com ordem definida vêm primeiro ordenados crescentemente, seguidos dos grupos sem ordem ordenados alfabeticamente por nome / menu_label).

• Resolução do Rótulo da Categoria:

  • Para cada grupo de módulos renderizado, calcular o rótulo:

    $nomeGrupo = (existe($modulo_grupo['menu_label']) ? $modulo_grupo['menu_label'] : $modulo_grupo['nome']);

  • Substituir a tag #categoria-nome# pelo $nomeGrupo resolvido.

Módulo 4: Suporte a Componentes de Menu Customizados por Projeto

• Variável de Configuração: $_GESTOR['project-admin-menu-components'] (geralmente definida no config-project.php).

• Estrutura Esperada:

  $_GESTOR['project-admin-menu-components'] = [
    'layout-id-especifico' => 'componente-menu-customizado',
    // ou chave genérica/padrão se aplicável
  ];

• Lógica de Seleção do Componente em gestor_pagina_menu():

  1. Identificar o layout da página atual ($_GESTOR['layout#id'] ou $paginas[0]['layout_id'] ou $_GESTOR['layout-id']).

  2. Se $_GESTOR['project-admin-menu-components'] estiver configurado e contiver uma entrada para o layout corrente (ou chave correspondente), utilizar o identificador do componente definido pelo projeto.

  3. Caso contrário (fallback padrão), manter o comportamento nativo:

     • Tailwind: 'menu-principal-sistema-tailwind'

     • Fomantic UI / Legado: 'menu-principal-sistema'

  4. Carregar o componente resultante via gestor_componente(Array('id' => $componenteMenuId)).

• Compatibilidade com JS do Menu:

  • Preservar os marcadores e blocos padrão do template (<!-- icon -->, <!-- icon-2 -->, <!-- item -->, <!-- categoria -->, <!-- simples -->, <!-- itemContCel -->, <!-- conteiner -->, etc.).

  • Caso o projeto utilize um template com comportamento JavaScript customizado, o motor do core deve preencher o HTML das células sem interferir nas tags do projeto.

3. Critérios de Aceite e Validação

1. Migração Phinx: A migração executa sem erros adicionando menu_label e garantindo ordemMenu na tabela modulos_grupos.

2. CRUD Módulos Grupos:

   • Campos menu_label e ordemMenu visíveis e funcionais em Adicionar, Editar e Clonar (pt-br e en).

   • Salvar com menu_label preenchido reflete no banco; salvar vazio grava NULL.

3. Exibição do Menu:

   • Grupo com menu_label preenchido exibe o rótulo do menu na barra de navegação administrativa.

   • Grupo com menu_label vazio exibe o nome original do grupo.

   • Grupos com ordemMenu definido (ex: 1, 2, 10) aparecem no topo do menu respeitando a ordem numérica, seguidos pelos demais em ordem alfabética.

4. Override de Componente de Menu:

   • Ao definir $_GESTOR['project-admin-menu-components'] mapeando o layout atual para um componente customizado, o sistema renderiza o componente customizado com as categorias e módulos preenchidos.

   • Na ausência da variável ou sem correspondência de layout, o sistema utiliza o fallback padrão (menu-principal-sistema-tailwind / menu-principal-sistema) sem quebras.

5. Testes Automatizados:

   • Suíte de testes unitários cobrindo o fallback de menu_label, a lógica de ordenação e a resolução do componente de menu.

   • PHPUnit e Vitest 100% verdes.