req-087: Parametrização e Resumo de Órfãos no Sincronizador de Banco de Dados

Descrição do Problema / Contexto

O script de sincronização de banco de dados (atualizacoes-banco-de-dados.php) realiza o cálculo de registros órfãos (presentes no banco mas ausentes nos arquivos JSON de origem). Atualmente, por padrão, o script gera logs muito grandes no console/banco de dados (logs individuais como ORPHAN_DB_ROW_NAT) e grava arquivos JSON de descarte no disco.

Como esse recurso raramente é usado no dia a dia, ele polui desnecessariamente os logs históricos de execução mantidos no banco de dados. Precisamos parametrizar esse comportamento para que o padrão seja silencioso/resumido (exibindo apenas as contagens no relatório final), deixando os logs individuais e a escrita em disco como comportamentos opcionais ativados por parâmetros de linha de comando.

Proposta de Alterações Detalhada

1. Atualizações em atualizacoes-banco-de-dados.php

No arquivo gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php:

1. Retorno de Sincronização:

   • Modificar o retorno da função sincronizarTabela() para incluir a quantidade de registros órfãos detectados:

     return ['inserted' => $inserted, 'updated' => $updated, 'same' => $same, 'orphans' => count($orphans)];

   • Ajustar todos os pontos de retorno prematuro ou de fluxo normal para sempre conter a chave 'orphans' (ex: em caso de array de registros vazio, retornar ['inserted'=>0,'updated'=>0,'same'=>0,'orphans'=>0]).

2. Silenciar Logs Individuais por Padrão:

   • O log detalhado de cada órfão (linhas ORPHAN_DB_ROW no modo PK e ORPHAN_DB_ROW_NAT no modo chave natural) deve ser condicionado à presença da flag --orphans-detail nas opções da CLI (não apenas ao $debug).

   • Exemplo de alteração:

     $orphansDetail = !empty($GLOBALS['CLI_OPTS']['orphans-detail']);
     // ...
     if ($orphansDetail) log_unificado("ORPHAN_DB_ROW_NAT tabela=$tabela chave=$nk", $GLOBALS['LOG_FILE_DB']);

3. Alterar Padrão de Exportação de Arquivos:

   • Mudar o padrão da variável $orphansMode. Em vez de herdar 'export' por padrão, o padrão deve ser 'ignore' para exportações físicas no disco.

   • Exemplo:

     $orphansMode = $GLOBALS['CLI_OPTS']['orphans-mode'] ?? 'ignore'; // Padrão alterado de 'export' para 'ignore'

   • Desta forma, o script só criará os arquivos .json de órfãos no disco se --orphans-mode=export for explicitamente fornecido.

4. Sumário Visual no Relatório Final:

   • Atualizar relatorioFinal(array $resumo) para extrair a chave 'orphans' e exibir a contagem por tabela de maneira compacta:

     foreach ($resumo as $tab => $r) {
      $msg .= sprintf("? %s => +%d ~%d =%d (órfãos: %d)" . PHP_EOL, $tab, $r['inserted'], $r['updated'], $r['same'], $r['orphans'] ?? 0);
     }

   • Exibir também o total consolidado de registros órfãos:

     $totalIns=$totalUpd=$totalSame=$totalOrphans=0;
     foreach ($resumo as $r){
      $totalIns+=$r['inserted'];
      $totalUpd+=$r['updated'];
      $totalSame+=$r['same'];
      $totalOrphans+=$r['orphans'] ?? 0;
     }
     // ...
     $msg .= "Σ TOTAL => +$totalIns ~{$totalUpd} ={$totalSame} | Órfãos Totais: {$totalOrphans}" . PHP_EOL;

2. Atualizações em atualizacoes-sistema.php

No arquivo gestor/controladores/atualizacoes/atualizacoes-sistema.php, na função executarAtualizacaoBanco(array $opts):

• Adicionar as novas flags 'orphans-detail' e 'orphans-mode' na lista de cópia de opções permitidas que são propagadas do array $opts do sistema para a configuração do banco de dados $cli:

  foreach (['debug','force-all','tables','log-diff','dry-run','orphans-detail','orphans-mode'] as $k) { if (isset($opts[$k])) $cli[$k] = $opts[$k]; }

• O padrão de exportação de órfãos no disco deve ser 'ignore' (não exportar) em vez de 'export', a menos que o usuário/rotina forneça explicitamente --orphans-mode=export.

Validação e Testes

1. Verificação Estática:

   • Rodar php -l gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php

   • Rodar php -l gestor/controladores/atualizacoes/atualizacoes-sistema.php

2. Validação Funcional:

   • Executar uma sincronização completa em ambiente local de testes sem flags extras de órfãos e confirmar:

     • Nenhum arquivo .json foi gerado em db/orphans/bd/.

     • Nenhum log individual do tipo ORPHAN_DB_ROW_NAT ou ORPHAN_DB_ROW foi impresso na CLI.

     • O relatório final exibe o totalizador de órfãos corretamente: (órfãos: X) e Órfãos Totais: Y.

   • Executar com as flags --orphans-detail e --orphans-mode=export e validar que o comportamento antigo (arquivos em disco + logs individuais) é reativado com sucesso.

3. Regressão:

   • Executar composer test e confirmar que a suíte completa de testes continua passando sem quebras.