req-052: Disponibilidade do Menu com Visibilidade Condicional (Público, Logado e Perfil de Usuário) no Módulo Menus

Este lote de trabalho (BATCH-052) define a reestruturação do módulo menus para suportar visibilidade condicional. No lugar do atual fluxo de um único menu fixo ("Itens do Menu"), o sistema permitirá definir regras de disponibilidade (Visível a Todos vs. Visibilidade Condicional), criando dinamicamente sub-menus (árvores de itens isoladas) por condição (Público, Logado, Perfil de Usuário) gerenciadas através de abas na interface administrativa e renderizadas dinamicamente no widget público de acordo com o estado do usuário ativo.

1. Atualização do Schema de Dados (fields_schema)

O campo fields_schema armazenado na tabela menus (e controlado via JSON no JS/PHP) deve ser expandido. O novo formato JSON do schema deve suportar a seguinte estrutura:

{
  "availability": "todos" | "condicional",
  "conditions": [
    { "type": "publico" | "logado" | "perfil_usuario", "slug": "slug-da-condicao" }
  ],
  "menus": {
    "visible_to_all": [ /* árvore de itens do menu padrão */ ],
    "slug-da-condicao-1": [ /* árvore de itens da condição 1 */ ],
    "slug-da-condicao-2": [ /* árvore de itens da condição 2 */ ]
  },
  "template_id": "menus-horizontal-navbar",
  "selected_items": [ /* mantido apenas para retrocompatibilidade caso availability seja "todos" */ ]
}

Nota de Retrocompatibilidade: Caso o JSON lido não possua availability, trate como "todos" e use selected_items como a árvore padrão inicial de visible_to_all.

2. Modificações na Interface Administrativa (CRUD de Menus)

2.1 Alteração da Seção "Itens do Menu" para "Disponibilidade do Menu"

Nos arquivos HTML do módulo de administração (gestor/modulos/menus/resources/pt-br/pages/menus-adicionar.html, menus-editar.html, menus-clonar.html e equivalentes em inglês):

• Renomear a seção de "Itens do Menu" para "Disponibilidade do Menu" (form-fields_schema-label).

• Adicionar um elemento de seleção (<select> ou Fomantic-UI dropdown) com as opções:

  • Visível a Todos (valor: todos - padrão)

  • Visibilidade Condicional (valor: condicional)

• Abaixo desse select, posicionar um container #menu-availability no DOM para renderizar o editor correspondente.

2.2 Gerenciamento do Container #menu-availability no JS (menus.js)

Modificar gestor/modulos/menus/menus.js para reagir ao tipo de disponibilidade selecionado:

• Caso Visível a Todos:

  • Exibir a interface clássica do construtor de itens e a árvore de menu correspondente a menus.visible_to_all.

• Caso Visibilidade Condicional:

  • Renderizar um painel de CRUD de Condições:

  • Botão "Adicionar Condição".

  • Ao clicar, exibir um formulário contendo:

    • Select com opções: público (valor: publico), logado (valor: logado), perfil de usuário (valor: perfil_usuario).

    • Input de texto para o slug da condição. Ao mudar o select, pré-preencher com o valor do tipo selecionado (ex: publico, logado ou o nome do perfil de usuário correspondente).

    • Botão de confirmação "Adicionar" e botão "Cancelar".

  • Ao confirmar, salvar a nova condição na lista de conditions e criar um novo nó vazio na estrutura de menus associado ao slug escolhido.

  • Renderizar um Menu de Abas (Fomantic-UI pointing secondary menu ou similar) logo abaixo:

  • Cada aba representa uma condição cadastrada. O rótulo da aba deve ser o slug da condição.

  • Cada aba deve possuir um pequeno botão "Excluir" para remover a condição (removendo seu respectivo menu e atualizando a lista de condições).

  • Ao alternar entre as abas, carregar a árvore de itens correspondente àquele slug no construtor de árvore, isolando o estado local das variáveis (a árvore ativa editada no DOM reflete apenas na chave correspondente de menus[slug]).

  • Certificar-se de sincronizar e serializar corretamente o JSON composto de fields_schema para o input hidden correspondente antes de enviar o formulário (currentSchemaOut()).

3. Delimitadores de Modelo nos Templates / Editor HTML

O gerador/editor HTML deve aceitar e preservar blocos envelopados com comentários que diferenciem os menus de acordo com a visibilidade.

3.1 Identificação das Células / Comentários no HTML

No "Editor HTML" e nos templates físicos das páginas:

• Para menus com disponibilidade Visível a Todos, o código HTML correspondente do menu (com sua estrutura de tags) deve ser delimitado por:

  <!-- menu-visible < -->
  ... HTML DO MENU ...
  <!-- menu-visible > -->

• Para menus com disponibilidade Visibilidade Condicional, cada menu condicional será delimitado por:

  <!-- menu-conditional-SLUG < -->
  ... HTML DO MENU CONDICIONAL ...
  <!-- menu-conditional-SLUG > -->

  Onde SLUG representa o ID da condição correspondente.

3.2 Atualização no JS do Editor e Sincronização

Ao alternar abas no editor HTML ou salvar os dados, certificar-se de que esses comentários permaneçam intactos no editor e que o renderizador saiba interpretar a divisão das strings.

4. Renderização Dinâmica no Widget Público (menus.widget.php)

Atualizar gestor/modulos/menus/menus.widget.php para resolver a visibilidade correta em tempo de execução:

1. Obter dados do usuário ativo: Chamar a função global gestor_usuario() para recuperar as informações do usuário atual:

   $user_data = gestor_usuario();

2. Processar o Schema e Disponibilidade: Decodificar o fields_schema.

   • Se availability for todos ou não estiver definido:

     • Utilizar o bloco HTML delimitado por <!-- menu-visible < --> e <!-- menu-visible > --> (se existir, senão usar o template HTML inteiro).

     • Renderizar os itens de menus['visible_to_all'] (ou fallback de selected_items).

   • Se availability for condicional:

     • Iterar sobre as conditions na ordem definida:

     • Caso publico: Válido se o usuário for anônimo ($user_data['id_usuarios'] == 0 ou id for _anonimo).

     • Caso logado: Válido se o usuário estiver logado ($user_data['id_usuarios'] > 0 e id diferente de _anonimo).

     • Caso perfil_usuario: Válido se o usuário estiver logado e seu perfil corresponder à condição.

       • Resolução do Perfil: Fazer uma busca simples no banco na tabela usuarios_perfis buscando o campo id correspondente a $user_data['id_usuarios_perfis']. Se o id (slug do perfil) do banco coincidir com o slug da condição, ela é válida.

     • Encontrar a primeira condição válida.

     • Extrair do HTML do template apenas o bloco delimitado por:

       <!-- menu-conditional-[SLUG_DA_CONDICAO] < -->
       ...
       <!-- menu-conditional-[SLUG_DA_CONDICAO] > -->

     • Se o bloco condicional correspondente não existir no template, fazer fallback para o bloco <!-- menu-visible < --> ou, por fim, o HTML inteiro do template.

     • Renderizar os itens correspondentes a menus[SLUG_DA_CONDICAO] usando este bloco de HTML extraído.

5. Atualização do Módulo de IA (ai_modes)

Modificar a especificação de prompt do módulo de menus para que a IA do assistente de layout compreenda os novos delimitadores condicionais.

• Arquivos: gestor/modulos/menus/resources/pt-br/ai_modes/menus/menus.md e equivalente em inglês.

• Adicionar instruções explicando as seções <!-- menu-visible < --> e <!-- menu-conditional-SLUG < -->, instruindo a IA a utilizá-las quando precisar sugerir menus com variações visuais condicionais (ex: exibindo itens de login/cadastro no bloco público, e botões de perfil/sair no bloco logado).

6. Validação e Testes Unitários

1. Testes PHPUnit:

   • Adicionar casos de teste em tests/ para validar a função de rendering dinâmico em menus.widget.php:

     • Simular usuário deslogado e verificar se renderiza a árvore associada à condição publico.

     • Simular usuário logado e verificar se renderiza a árvore associada à condição logado.

     • Simular usuário de perfil X (ex: cliente) e verificar se renderiza a árvore associada à condição perfil_usuario do slug cliente.

     • Garantir que o fallback para menu-visible ou todo o HTML funcione se blocos específicos estiverem ausentes.

2. Testes Estáticos / Sintaxe:

   • Rodar verificações estáticas de PHP e JS:

     • php -l gestor/modulos/menus/menus.php

     • php -l gestor/modulos/menus/menus.widget.php

     • node --check gestor/modulos/menus/menus.js