Report Distribuidora — Balanço e Detalhamento de Estoque

Dashboard executivo de estoque da distribuidora, com a hierarquia Armazém › Marca › Família em listagem que abre e fecha, no modelo do dash financeiro usado como referência.

A base técnica e a identidade visual são herdadas do Report E-commerce (CD Vulcabras — Extrema/MG), mas este é um projeto independente: repositório próprio, banco Supabase próprio e deploy próprio. As demais páginas — romaneio, faturamento, entrega por transportadora — entram depois nesta mesma base, sem mudança de estrutura: cada uma vira uma nova linha em dashboard_snapshots.

---

1. Arquitetura

Três camadas, com separação rígida de responsabilidade:

   Extração TXT do sistema (Posição de Stock)
              │  upload manual, feito pelo operador no navegador
              ▼
        ┌───────────────┐
        │   ingest.js    │  Lê o arquivo, cruza com os gabaritos, calcula
        │  (processa e   │  os indicadores e grava tudo já pronto.
        │   só escreve)  │  NUNCA desenha nada na tela.
        └───────┬────────┘
                │ grava
                ▼
        ┌───────────────┐
        │   Supabase     │  Postgres (dados + snapshot) +
        │                │  Storage (backup gzip do TXT original)
        └───────┬────────┘
                │ lê o snapshot já pronto
                ▼
        ┌───────────────┐
        │  index.html    │  Desenha cards, gráficos e a árvore.
        │ (renderiza e   │  NUNCA recalcula regra de negócio.
        │   só lê)       │
        └───────────────┘
                ▼
             Vercel

Essa separação não é opcional. Número errado na tela se investiga no ingest.js (como foi calculado); aparência se ajusta no index.html (como é exibido). Foi o que economizou tempo de debug no projeto do e-commerce e é o que mantém a tela rápida com base grande.

Arquivo	O que é
index.html	O dashboard. Single-file, sem build step.
ingest.js	Parse, agregação e gravação (página Estoque).
distr-fluxo.js	Renderizador + editor da página Fluxo de Processos (ver seção 10).
esquema.sql	Todo o banco: tabelas, gabaritos, RLS. Já aplicado.
embarque.js	Setor Embarque: leitura da base histórica, forecast mensal ÷ dias úteis e o gráfico Expedição × Forecast / Análise Prevista de Backlog (mesmo traço do Report E-commerce).
migracao_embarque.sql	Tabelas embarque_diario (histórico diário) e embarque_forecast_mensal. Já aplicada.
testes-embarque.js	Testes do Embarque (node testes-embarque.js).
seed_distr_fluxo.sql	Semente da primeira versão do Fluxo de Processos (ver seção 10).
vercel.json	Diz ao Vercel que é estático puro, sem build.
favicon.png	Ícone da aba e marca no menu.

---

2. Infraestrutura já provisionada

Supabase

Projeto	report-distribuidora
Organização	Vulca
Região	sa-east-1 (São Paulo)
URL	https://qaehjplsasumuhszjcnu.supabase.co
Custo	R$ 0/mês

O schema e os gabaritos já estão aplicados (7 armazéns, 37 famílias com marca e segmento). A publishable key já está preenchida no index.html — ela é pública por design: quem protege o dado é a RLS no Postgres, não o fato de a chave estar escondida no front.

O que ainda falta fazer no Supabase (5 min)

1. Storage → New bucket → nome backups, Public: OFF. É onde fica a cópia comprimida de cada TXT enviado, para auditoria.
2. Authentication → Users → Add user → seu e-mail e senha.
3. Copie o UUID do usuário e rode no SQL Editor:

   insert into perfis_acesso (user_id, role, nome)
   values ('COLE-O-UUID-AQUI', 'admin', 'Seu Nome');
   

   Sem esse passo o login recusa: a tela exige perfil cadastrado.

GitHub

Crie um repositório novo (ex. report-distribuidora) e suba estes arquivos na raiz dele. Nada além do que está aqui é necessário.

Vercel

1. Add New → Project → importe o repositório.
2. Framework Preset: Other. Build Command e Output Directory em branco — o vercel.json já cuida disso.
3. Deploy. Em ~30 segundos o link fica pronto.
4. Todo push na branch de produção redeploya sozinho.

O index.html também funciona aberto direto do disco (duplo clique): ele fala com o Supabase pela internet, não depende do servidor de hospedagem. Serve de plano B se o deploy travar na véspera de uma apresentação.

---

3. Carregar o estoque

1. Abra o link, faça login.
2. Menu Admin → Atualizar dados.
3. Selecione o TXT da extração de posição de stock, exatamente como sai do sistema.
4. Acompanhe o log. Ao terminar, o dashboard recarrega sozinho.

Os dois layouts de extração

O ingest aceita os dois formatos e detecta qual é pelo conteúdo do arquivo, não pelo nome:

Layout	Extração	Observação
Delimitado por |	EX000796	Preferido. Traz St e Em Linha como colunas separadas, e artigo/descrição/cor/tamanho cada um na sua coluna.
Largura fixa	EX000914	Mantido por compatibilidade. É o único que imprime o ** TOTAL GERAL do sistema, útil para conferência.

Não abra o arquivo no Excel e salve por cima. No layout de largura fixa as colunas são lidas por posição de caractere, e qualquer reformatação quebra a leitura.

---

4. O que a tela mostra

4.1. Faixa de conferência

Quando a extração é a de largura fixa, o ingest compara o que leu com o ** TOTAL GERAL impresso pelo próprio sistema:

• Verde — a quantidade confere exatamente. Na carga de 25/08/2026: 2.946.194 unidades, batendo linha a linha. A diferença de R$ 0,88 no valor é arredondamento do próprio relatório e fica declarada na tela.
• Vermelho — não bateu. Significa linha perdida na leitura: não apresente o número, investigue o parse.

Quando a extração é a delimitada, o arquivo não imprime totais. A tela diz exatamente isso — "não há conferência externa" — em vez de fingir uma validação que não houve.

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