Report E-commerce — Vulcabras

Dashboard executivo de operação de armazém (CD Vulcabras — Extrema/MG) para acompanhamento de Outbound, Inbound, Estoque, Reversa e Balanço WMS×SAP do e-commerce. Este documento não é só um manual de uso: é o registro do processo usado para construir o projeto — decisões de arquitetura, por que cada padrão técnico existe, quais bugs reais ele resolveu, e como replicar esse mesmo processo para um novo contexto (ex.: recriar o projeto para uma distribuidora, com fluxo de dados diferente mas a mesma base tecnológica e a mesma identidade visual).

Se você está lendo isto para recriar o projeto em outro contexto, vá direto para Recriando para um novo contexto. O restante do documento explica o "porquê" de cada peça, que é o que você vai precisar decidir de novo lá.

---

1. Visão geral da arquitetura

O projeto é deliberadamente simples em número de peças, e deliberadamente rígido na separação de responsabilidades entre elas:

 Planilhas/exports do WMS, SAP, Forecast, etc.
              │
              │  (upload manual, feito pelo operador no navegador)
              ▼
        ┌───────────────┐
        │   ingest.js    │   Lê os arquivos, cruza dados, calcula os
        │  (processa e   │   indicadores, grava tudo já pronto no banco.
        │   só escreve)  │   NUNCA desenha nada na tela.
        └───────┬────────┘
                │  grava
                ▼
        ┌───────────────┐
        │   Supabase     │   Postgres (dados estruturados) +
        │ (Postgres +    │   Storage (backup dos arquivos originais,
        │  Storage)      │   comprimidos em gzip)
        └───────┬────────┘
                │  lê (snapshot já pronto)
                ▼
        ┌───────────────┐
        │  index.html    │   Lê o snapshot mais recente e desenha os
        │ (renderiza e   │   cards/gráficos/tabelas. NUNCA processa ou
        │   só lê)       │   recalcula regra de negócio.
        └───────────────┘
                │
                ▼
         Vercel (hospedagem estática do index.html)

Por que essa separação existe (e por que ela não é opcional):

No início do projeto, cálculo e renderização estavam misturados no mesmo arquivo. Isso criava dois problemas recorrentes: (1) qualquer ajuste visual arriscava re-executar lógica de negócio sem querer, e (2) toda vez que a base crescia, a tela travava porque o navegador do operador tentava reprocessar tudo a cada carregamento. A solução foi mover todo o processamento pesado para um script único (ingest.js), rodado uma vez por atualização de dados, que grava o resultado já pronto como um "snapshot" (JSON) no Postgres. O index.html ficou livre para ser burro e rápido: ele só busca o snapshot mais recente da página que está exibindo e desenha. Essa regra foi reforçada várias vezes ao longo do desenvolvimento e deve ser tratada como inegociável em qualquer evolução futura — inclusive na recriação para a distribuidora.

1.1. ingest.js — processamento

• Roda no navegador do operador (upload manual dos arquivos-fonte: NFs, pedidos, forecast, posição de estoque, etc.).
• Faz todo o cruzamento de dados: de-duplicação de registros, cálculo de KPIs, fechamento de expedição diária, cruzamento WMS×SAP para o Balanço, etc.
• Grava o resultado em dashboard_snapshots — uma tabela com uma linha por pagina (outbound, inbound, estoque, reversa, balanco), cada linha contendo o JSON já pronto para renderizar e um timestamp gerado_em (sempre gravado como new Date().toISOString(), ou seja, UTC).
• Também sobe uma cópia comprimida (gzip) do arquivo original para o Supabase Storage, para fins de auditoria/histórico — ver 3.4.
• Nunca deve conter document.querySelector, manipulação de DOM, ou qualquer coisa relacionada a exibir informação na tela. Se um ajuste pede para "mudar como algo aparece", ele pertence ao index.html, não a este arquivo — mesmo que pareça mais fácil calcular ali.

1.2. index.html — renderização

• Single-file: HTML + CSS + JS embutidos (sem build step, sem bundler — hospedado como estático puro no Vercel).
• Busca em dashboard_snapshots o registro mais recente de cada pagina e desenha os cards, tabelas e gráficos a partir do JSON já pronto.
• Contém a lógica de UI: troca de tema (claro/escuro), navegação entre seções, controle de acesso por perfil (ver seção 5), formatação de datas para exibição, exportação de tabelas.
• Nunca deve recalcular uma regra de negócio que já veio pronta do snapshot. Se um número está errado na tela, o primeiro lugar a investigar é o ingest.js (como o número foi calculado), não o index.html (como ele é exibido) — essa distinção economizou bastante tempo de debug ao longo do projeto.

1.3. Supabase (Postgres + Storage)

• Projeto na região ca-central-1.
• Tabela central: dashboard_snapshots (uma linha "mais recente" por pagina, versionada por gerado_em).
• Tabelas de apoio por domínio (NFs, itens, embalagens/dim_embalas, pedidos etc.) — o ingest.js lê e escreve nelas antes de consolidar o snapshot.
• Storage: bucket para os arquivos originais enviados (comprimidos), usado como backup/auditoria — não é lido pelo index.html.
• Segurança de dado de verdade é responsabilidade do Postgres (RLS — Row Level Security), não do front-end. Isso é tratado em detalhe na seção 5 porque é um ponto que ficou pendente neste projeto e não deve se repetir na recriação.

1.4. Vercel

• Hospeda o index.html como site estático. Sem variáveis de ambiente sensíveis no build — as credenciais do Supabase usadas pelo index.html são a anon key pública (protegida por RLS no backend, não por estar "escondida" no front).
• Deploy automático a partir da branch de produção do repositório GitHub.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗