req-145: Minificação de JS/CSS próprios — em build, não no roteamento

• Status do intake: implemented-pending-homologation

• Data: 2026-08-29

• Origem: sugestão do Engenheiro Chefe durante o BATCH-146 ("sempre que um JS for roteado no nosso sistema pensei em minificar", apontando controladores/arquivo-estatico/arquivo-estatico.php)

• Classificação: desempenho de entrega, arquitetura de derivados

• Batch: BATCH-148

1. Oportunidade medida

Primeira contagem: 89 arquivos, 2,7 MB não minificados (excluindo assets/vendor/). Depois de separar o que é AUTORIA do que é terceiro vendorizado à mão, sobraram 64 arquivos e 1,59 MB — ver a correção abaixo.

Correção da primeira leitura (medido depois)

A leitura inicial deste intake dizia que os dois arquivos do DataTables (925 KB) seriam "ganho de graça". A medição desmentiu isso. O runtime inclui datatables/datatables.min.js — a versão JÁ minificada:

interface.php:5543-5544  ->  datatables/datatables.min.css  (7,1 KB entregues)
                             datatables/datatables.min.js   (109,5 KB entregues)

Nenhum recurso do sistema referencia datatables.js nem jquery.dataTables.js. Os 925 KB são peso de repositório e superfície exposta (respondem 200 se pedidos diretamente), não bytes entregues ao visitante. Removê-los não reduz nada do que o navegador baixa.

O ganho real está no JavaScript de autoria, que era servido sem minificação nenhuma.

2. Por que NÃO minificar no arquivo-estatico.php

O controlador é a camada de entrega, e transformar o corpo ali colide com quatro coisas que ele já faz corretamente (BATCH-100):

1. Content-Length e Range: o controlador anuncia Accept-Ranges: bytes e serve requisições parciais. Um corpo transformado em tempo de resposta não tem tamanho conhecido antes de ser gerado, e não há como servir um intervalo de bytes de algo que ainda não existe.

2. ETag e 304: o ETag é derivado de filesize + filemtime do arquivo em disco. Minificar depois disso faz o validador descrever um corpo que não é o entregue.

3. Custo por requisição: sem cache, cada visitante paga a minificação. Com cache, é preciso inventar invalidação, diretório de cache e limpeza — reconstruindo um passo de build dentro do servidor de arquivos.

4. Risco de quebra silenciosa: minificador ingênuo que remove quebras de linha quebra código que depende de ASI (inserção automática de ponto e vírgula). O sintoma aparece em produção, no navegador do visitante.

3. Onde ela pertence

No build, seguindo a doutrina já estabelecida no req-141 / CR-002: html e css de autoria são uma coisa; derivados são outra, sempre recalculáveis e nunca editados à mão.

O arquivo minificado é um derivado do JS de autoria, exatamente como css_precompiled é derivado do css. Isso dá, de graça, o vocabulário que já existe:

• gerado por um estágio do pipeline (resources:sync ou um c2f assets:build), nunca em runtime;

• assinatura de procedência análoga ao css_source_hash, para saber quando o derivado deixou de corresponder à autoria;

• arquivo-estatico.php continua servindo arquivo em disco, com Range, ETag e 304 intactos — ele só passa a receber um arquivo menor.

4. Esboço de escopo

1. c2f assets:minify: gera <id>.min.js ao lado do fonte, com procedência (sha1) registrada em gestor/assets/minify-manifest.json. Usa o terser, que já estava em devDependencies.

2. A escolha do derivado acontece na RESOLUÇÃO do arquivo estático, não no emissor: um ponto só em vez de cinco ramos de construção de URL, e o envio continua sendo um envio de arquivo.

3. Gate por ambiente: em DEVELOPMENT_ENV=true serve sempre o fonte. Isso também torna inofensivo o derivado envelhecer enquanto alguém edita — quem edita está em dev.

4. Etapa no pipeline (manager:update-all 5/5 e project:update-all 7/7), não fatal: máquina sem Node continua rodando o pipeline e servindo o arquivo de autoria.

5. node --check obrigatório antes de gravar cada derivado.

Limite honesto: node --check valida SINTAXE, não semântica. Código que dependa do nome de funções em runtime (fn.name, eval de identificadores locais) pode minificar sem erro e falhar no navegador. Homologação visual segue sendo do operador.

5. Resultado medido

6. Recomendação (mantida após a implementação)

A recomendação central se sustentou: não no arquivo-estatico.php. Minificar na entrega trocaria um problema de tamanho por quatro de correção, jogando fora garantias de HTTP que o controlador levou um lote inteiro para ganhar. Escolher QUAL arquivo enviar entrega o mesmo ganho sem custo nenhum — medido: Content-Length 17305 batendo byte a byte com o derivado, 304 e 206 corretos.

A parte da recomendação que não se sustentou foi a do DataTables (seção 1): aqueles 925 KB nunca foram entregues ao visitante.

7. Pendência deixada de fora, deliberadamente

gestor/assets/datatables/ tem 67 arquivos e 1,7 MB, dos quais o sistema usa DOIS (datatables.min.js e datatables.min.css). O resto são temas de Bootstrap, Foundation e jQuery UI que este projeto não usa, mais as versões não minificadas.

Não removi por conta própria: é biblioteca EM USO, e apagar 65 arquivos dela é decisão do operador, não faxina de agente. O ganho seria de repositório e de superfície exposta — não de banda do visitante, que já recebe só a versão minificada.