Projeto Loja - Modulo de Compressao de Imagens no Frontend

Este documento descreve a arquitetura e as decisoes tecnicas por tras do modulo de upload e compressao de imagens deste projeto. O foco principal e a eficiencia e a experiencia do usuario, transferindo a carga pesada de processamento de imagem do servidor para o dispositivo do cliente (navegador).

Decisao Tecnica: Compressao no Frontend (Client-Side)

Tradicionalmente, uploads de imagens funcionam enviando o arquivo original (muitas vezes com 5MB, 10MB ou mais) para o servidor, que entao processa, redimensiona e comprime a imagem.

Neste projeto, adotamos uma abordagem moderna de pré-processamento no cliente.

Por que essa decisao foi tomada?

1. Economia de Banda e Dados: Em vez de enviar uma imagem de 10MB em uma conexao movel instavel, o usuario envia apenas a versao processada (ex: 50KB a 150KB). Isso torna o upload quase instantaneo.
2. Reducao de Custo de Servidor: O processamento de imagem (redimensionamento e re-codificacao) e intensivo em CPU. Ao fazer isso no navegador, distribuimos essa carga computacional para os dispositivos dos usuarios, permitindo que o servidor atenda muito mais requisicoes com menos hardware.
3. Experiencia do Usuario (UX): O usuario ve o resultado final antes de enviar. Se a imagem ficar ruim ou cortar algo importante, ele sabe na hora. Alem disso, extraimos metadados (como a cor predominante) instantaneamente para efeitos visuais imediatos.
4. Armazenamento Otimizado: O backend ja recebe o arquivo pronto para ser salvo no S3/Disco, sem necessidade de pipelines complexos de pos-processamento.

Estrutura de Pastas e Integracao

A organizacao do projeto separa claramente as responsabilidades, mas mantem uma integracao fluida entre Backend e Frontend:

• api_core/: Contem a logica de negocio, classes PHP (incluindo o novo `AssetManager`) e dependencias.
• frontend_src/: Codigo fonte Javascript e configuracoes do Vite.
• public_html/: Ponto de entrada. O `index.php` agora serve nao apenas a API, mas tambem renderiza o HTML inicial da aplicacao.

Integracao Inteligente (AssetManager)

O projeto utiliza uma classe AssetManager para gerenciar como os scripts sao carregados:

1. Modo Desenvolvimento: Se o arquivo `manifest.json` nao for encontrado, o sistema assume que voce esta rodando o servidor Vite (`npm run dev`). O PHP entao injeta uma tag `<script>` apontando para `http://localhost:3000/main.js`, permitindo Hot Module Replacement (HMR).
2. Modo Producao: Ao rodar `npm run build`, o Vite gera os arquivos estaticos otimizados e um `manifest.json`. O PHP le este manifesto e aponta para os arquivos com hash (ex: `/assets/main.x82a.js`), garantindo cache-busting eficiente.

Como Instalar e Rodar

Siga os passos abaixo para configurar o ambiente de desenvolvimento.

1. Instalacao das Dependencias do Backend

Navegue ate a pasta do nucleo da API e instale as bibliotecas PHP:

cd api_core
composer install

2. Instalacao das Dependencias do Frontend

Navegue ate a pasta dos arquivos fonte do frontend e instale as ferramentas Node.js:

cd ../frontend_src
npm install

3. Rodando o Projeto

Voce precisara de dois terminais abertos simultaneamente.

Terminal 1 (Build do Frontend em tempo real): Este comando vai monitorar mudancas no JS e atualizar os arquivos na pasta publica.

cd frontend_src
npm run dev

Terminal 2 (Servidor PHP): Inicie o servidor embutido do PHP apontando para a pasta publica.

cd public_html
php -S localhost:8000

Acesse no navegador: http://localhost:8000

Implantacao em Producao (Build)

Para rodar o projeto em um ambiente de producao (ou simular o comportamento final), voce nao precisa manter o terminal do Node aberto.

1. Gerar o Build

Este comando vai processar todos os arquivos JS/CSS, minifica-los e salva-los na pasta public_html/assets.

cd frontend_src
npm run build

2. Rodar Apenas o PHP

Apos o build, o Node.js nao e mais necessario. O PHP detectara automaticamente os arquivos gerados atraves do AssetManager.

cd ../public_html
php -S localhost:8000

3. Configuracao em Hospedagem Compartilhada (.htaccess)

Caso voce nao tenha acesso para mudar a pasta raiz do servidor (DocumentRoot) para public_html, voce pode criar um arquivo .htaccess na raiza do projeto com o seguinte conteudo para redirecionar todo o trafego:

Arquivo: /.htaccess

<IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteCond %{REQUEST_URI} !^public_html
    RewriteRule ^(.*)$ public_html/$1 [L]
</IfModule>

Isso fara com que o site carregue corretamente mesmo se os arquivos estiverem fora da pasta publica padrao.

Analise dos Arquivos Principais

A logica central reside em dois arquivos JavaScript na pasta frontend_src.

1. image-compressor.js (O Motor)

Este e um modulo ES6 puro, agnostico de framework, focado em uma unica responsabilidade: transformar um arquivo bruto em um arquivo otimizado.

Principais Funcionalidades: API Canvas*: Utiliza o elemento canvas HTML5 para renderizar e redimensionar a imagem com alta performance. Algoritmo de Media de Cor (getAverageColor)*: Implementa uma leitura direta dos bytes da imagem para calcular a cor media dominante. Isso e feito amostrando pixels para garantir que a operacao leve apenas alguns milissegundos. Conversao WebP*: Exporta nativamente para o formato WebP, que oferece compressao superior ao JPEG/PNG com menor perda de qualidade. Retorno Rico*: Devolve um objeto contendo metadados valiosos: dimensoes originais vs. finais, tamanho em bytes e a cor hexadecimal extraida.

2. main.js (O Orquestrador)

Este arquivo atua como a camada de controle, ligando a interface do usuario (DOM) a logica de compressao.

Fluxo de Trabalho: 1. Preview Imediato: Mostra a imagem original instantaneamente ao usuario. 2. Processamento Assincrono: Chama a compressao e aguarda o resultado sem travar a interface. 3. Feedback Visual: Exibe a comparacao de tamanho e a cor predominante. 4. Preparacao para Envio: Constroi o FormData anexando o arquivo ja processado (WebP) e nao o original. 5. Envio de Metadados: Envia tambem largura, altura e cor dominante como campos de texto para o backend.

Potencial do Projeto

Este modulo serve como um modelo de arquitetura que pode ser replicado em diversas aplicacoes. Ele nao e apenas um script de upload, mas uma solucao completa de tratamento de midia.

Casos de Uso:

• E-commerce: Upload de produtos onde a padronizacao e velocidade sao cruciais.
• Redes Sociais: Upload de fotos de perfil ou feed, onde a compressao rapida e essencial.
• Sistemas de Documentos: Pre-tratamento de fotos de documentos para reduzir tamanho.
• Apps Offline-First: Preparar imagens para serem salvas localmente antes de sincronizar.

Extensibilidade:

O codigo e modular. O componente de compressao pode ser importado em projetos React, Vue, Angular ou React Native.