req-042: Controle de Métricas no publisher-index e Suíte de Testes com Banco de Dados

Este documento especifica os requisitos para a implementação do controle dinâmico de exibição das métricas de paginação no módulo publisher-index e a estruturação de testes de unidade/integração para o widget.

1. Requisitos do Controle de Métricas (show_metrics)

1.1 Banco de Dados e Schema

• Configuração: Adicionar o campo booleano show_metrics (valor padrão true) no fields_schema do módulo publisher-index.

1.2 Interface Administrativa (CRUD)

• Modificações nos HTMLs: Nos arquivos adicionar.html, editar.html e clonar.html (tanto na pasta pt-br quanto en do módulo publisher-index), incluir um novo campo checkbox para o controle de exibição de métricas:

  • Identificador: #show_metrics

  • Label (pt-br): Exibir métricas de paginação

  • Label (en): Show pagination metrics

  • Posicionamento: Deve ser posicionado ao lado dos demais toggles de exibição (show_search_input, show_sorting_select, show_load_more_btn) mantendo o alinhamento visual do Fomantic UI.

• Javascript Administrativo: Atualizar o arquivo publisher-index.js para garantir a leitura e persistência do valor do checkbox #show_metrics ao salvar/carregar as configurações do módulo.

1.3 Widget Renderizado e Backend

• Leitura do Schema: Em publisher-index.widget.php, recuperar a propriedade show_metrics a partir do fields_schema (usando o helper publisher_index_widget_bool com default true).

• Resolução de Variável Global: Adicionar a chave show_metrics com 'true' ou 'false' no mapeamento de variáveis globais resolvido em publisher_index_widget_resolver_globais().

• Bloco Condicional de Controle:

  • Implementar o controle condicional de bloco para as métricas usando os delimitadores:

    <!-- metrics < -->
    ...
    <!-- metrics > -->

  • No backend, realizar a remoção ou preservação deste bloco no HTML renderizado através de:

    $output = publisher_index_widget_bloco_condicional($output, 'metrics', $show_metrics);

1.4 Templates Físicos de Widget

• Nos templates físicos do módulo (lista, grid, timeline, agenda para ambos os idiomas pt-br e en), envolver o elemento HTML correspondente às métricas com os delimitadores de bloco <!-- metrics < --> e <!-- metrics > -->.

  • Exemplo:

    <!-- metrics < -->
    <div class="publisher-index-metrics text-sm text-gray-500 mb-4">
    Exibindo <span data-page-count>@[[page_count]]@</span> de <span data-page-total>@[[page_total]]@</span>
    </div>
    <!-- metrics > -->

2. Requisitos da Suíte de Testes (PHPUnit)

2.1 Testes Unitários Puros (Sem Banco de Dados)

• No arquivo de testes PublisherIndexWidgetTest.php, adicionar casos de teste que validem isoladamente a lógica das funções utilitárias que não dependem do banco de dados:

  • Mapeamento Unicode: Testar publisher_index_widget_unicode_escape() cobrindo termos com acentos (ex: "Título", "Acentuação") com e sem barras invertidas.

  • Decodificação Unicode: Testar publisher_index_widget_corrigir_unicode() cobrindo strings normais e strings contendo caracteres corrompidos (Tu00edtulo e \u00edtulo).

  • Métricas Globais: Validar a resolução das novas variáveis globais e do bloco metrics sob diferentes condições em um template mockado.

2.2 Testes de Integração com Banco de Dados MySQL (Docker)

• Estratégia de Banco de Dados de Teste:

  • Como a biblioteca banco.php é acoplada ao driver mysqli e não possui suporte a SQLite, a suíte de testes de integração deve ser executada contra o container MySQL de desenvolvimento local (conn2flow-mysql na porta 3306).

  • Configuração no PHPUnit:

  • O arquivo tests/bootstrap.php já expõe a configuração do banco a partir das variáveis de ambiente:

    • CONN2FLOW_DB_HOST (ex: [REDACTED])

    • CONN2FLOW_DB_DATABASE (ex: conn2flow_test - banco temporário)

    • CONN2FLOW_DB_USERNAME (ex: root ou conn2flow_user)

    • CONN2FLOW_DB_PASSWORD (ex: root123 ou conn2flow_pass)

  • As credenciais de produção/desenvolvimento reais nunca devem ser afetadas pelos testes. Os testes devem ser executados em um banco de dados dedicado chamado conn2flow_test.

• Implementação do Teste de Integração:

  • Criar um caso de teste em PublisherIndexWidgetTest.php (ou classe dedicada de teste de integração se fizer sentido) que:

    1. Se conecte ao banco de teste temporário.

    2. Crie tabelas mínimas necessárias (paginas e publisher_pages) ou execute migrações temporárias.

    3. Popule registros com títulos acentuados normais e acentuados corrompidos.

    4. Realize a busca chamando publisher_index_widget_buscar_publicacoes() com busca acentuada e verifique se o filtro disjuntivo e o INNER JOIN filtram os registros indesejados e retornam os resultados corretos.

    5. Limpe os dados do banco temporário após os testes.