Mapa do site — Copos personalizados

Visão geral

Backend Express na porta 3011. Banco em arquivos JSON. Identidade unificada em customers.json com role ('admin' | 'customer'). JWT único em localStorage.copos_cust_token (espelhado em copos_token para admins). Pagamento Pix com upload de comprovante. Notificações via WhatsApp Web API.

Domínios e responsabilidades

Loja pública: Vitrine, página de produto com mockup, carrinho, checkout, conta do cliente.
Painel admin: Catálogo (categorias e produtos), gestão de pedidos, clientes, frete e notificações.
Pagamento: Pix antecipado (chave + QR + copia&cola). Cliente envia comprovante; admin confirma.
Personalização: Cada produto tem faces (frente/verso/laterais) com overlay do gabarito e área útil. Cliente sobe arte e ajusta posição.
Frete: Configurável por UF / região + retirada local + frete grátis condicional.

Fluxo do cliente

Caminho da escolha do produto até o recebimento.

01

Vitrine

Lista categorias e produtos ativos.

/

02

Produto

Escolhe variação, quantidade, sobe arte por face e vê o mockup ao vivo.

/produto.html?slug=…

03

Carrinho

Revisa itens, quantidades e preço com tabela de desconto por volume.

/carrinho.html

04

Login / Cadastro

Identifica o cliente — necessário pra criar pedido.

/entrar.html · /cadastro.html

05

Checkout

CEP, endereço, escolha de frete, observações. Pedido criado em aguardando_pagamento.

/checkout.html

06

Pagamento Pix

Mostra chave, QR e copia&cola. Cliente envia comprovante (upload).

/conta.html (detalhe)

07

Confirmação

Admin confere comprovante e move pra pago → em_producao.

/painel.html (admin)

08

Produção e envio

Admin atualiza status; cliente recebe notificação via WhatsApp.

/conta.html

Fluxo do admin

Operação interna para preparar o catálogo e despachar pedidos.

01

Categorias

Cria/ordena categorias (copos, tirantes, pulseiras…).

/admin-categorias.html

02

Produto

Sobe imagens, gabaritos, faces (overlay + área útil), variações, tabela de desconto, prazo, peso.

/admin-produto.html

03

Frete

Define regras por UF/região, retirada local e frete grátis.

/admin-frete.html

04

Pedidos

Acompanha pedidos, revisa comprovante, muda status, ajusta frete.

/admin-pedidos.html

05

Clientes

Lista, edita, desabilita ou redefine senha.

/admin-clientes.html

06

Notificações

Histórico de mensagens WhatsApp + envio de teste.

/admin-notificacoes.html

Status do pedido

Máquina de estados do pedido. Cliente cancela enquanto está aguardando pagamento ou confirmação; admin pode mudar para qualquer estado.

aguardando_pagamento → aguardando_confirmacao → pago → em_producao → enviado → entregue · cancelado

aguardando_pagamento: Pedido criado. Cliente vê QR/copia&cola Pix.
aguardando_confirmacao: Cliente subiu comprovante. Admin precisa conferir.
pago: Admin confirmou. Marca payment.paidAt.
em_producao: Em fabricação. Prazo é o maior productionDays dos itens.
enviado: Despachado.
entregue: Cliente recebeu.
cancelado: Cliente só cancela em aguardando_*; admin a qualquer momento.
Edição de arte: Cliente troca/remove arte enquanto status ∈ {aguardando_pagamento, aguardando_confirmacao, pago}.

Páginas da loja (público)

Tudo servido em /public com fallback SPA pra index.html.

URL	Página	Função	Acesso
`/`	index.html	Vitrine: filtra por categoria e lista produtos ativos.	público
`/produto.html?slug=…`	produto.html	Detalhe do produto com mockup ao vivo, upload de arte por face, escolha de variação/quantidade, "adicionar ao carrinho".	público
`/carrinho.html`	carrinho.html	Itens, quantidades e total. Persistido em `localStorage`.	público
`/checkout.html`	checkout.html	CEP/endereço, frete calculado, observações. Cria pedido via `POST /api/pedidos`.	cliente logado
`/entrar.html`	entrar.html	Login do cliente.	público
`/cadastro.html`	cadastro.html	Cadastro do cliente (e-mail, WhatsApp, senha, CEP, endereço opcional).	público
`/conta.html`	conta.html	Meus pedidos: histórico, detalhe, Pix, comprovante, troca de arte (se permitido), cancelar.	cliente logado
`/offline.html`	offline.html	Tela de fallback do service worker (PWA).	público
`/mapa.html`	mapa.html	Esta página.	público

Páginas do painel admin

Mesmo domínio, mesmo design, mas com sidebar e tabela densas.

URL	Página	Função	Acesso
`/admin.html`	admin.html	Redirect: vai pra login se não autenticado, senão pro painel.	público
`/admin-entrar.html`	admin-entrar.html	Legado — redireciona para `/entrar.html` (login unificado).	público
`/admin-cadastro.html`	admin-cadastro.html	Legado — redireciona para `/entrar.html`. Bootstrap do primeiro admin é feito promovendo um customer.	público
`/painel.html`	painel.html	Dashboard inicial do admin.	admin
`/admin-produtos.html`	admin-produtos.html	Lista de produtos com busca e filtros.	admin
`/admin-produto.html?id=…`	admin-produto.html	Editor de produto: imagens, gabarito PDF, faces com overlay e printArea, variações, descontos, peso, prazo, alertas de impressão.	admin
`/admin-categorias.html`	admin-categorias.html	CRUD de categorias com ícone e ordenação.	admin
`/admin-pedidos.html`	admin-pedidos.html	Lista e detalhe de pedidos. Confirma comprovante, muda status, edita frete e notas.	admin
`/admin-clientes.html`	admin-clientes.html	Lista de clientes com pedidos, total gasto e ações (editar, desabilitar, resetar senha).	admin
`/admin-frete.html`	admin-frete.html	Regras de frete: por UF, por região, retirada local, frete grátis, fallback.	admin
`/admin-notificacoes.html`	admin-notificacoes.html	Status da integração WhatsApp + histórico de envios + envio de teste.	admin

API · Autenticação admin

Prefixo /api/autenticacao. Opera sobre customers.json; exige role === 'admin'. O JWT emitido aqui é o mesmo aceito por /api/clientes/*.

Método	Rota	Função	Acesso
POST	`/api/autenticacao/register`	Cria o primeiro admin (bloqueia se já existir customer com `role='admin'`).	público (1x)
POST	`/api/autenticacao/login`	Autentica contra `customers`; rejeita se `role !== 'admin'`. Retorna `{ token, user }`.	público
GET	`/api/autenticacao/status`	`{ hasUsers }` = existe algum admin?	público
GET	`/api/autenticacao/me`	Dados do admin autenticado (customer com role=admin).	admin
PUT	`/api/autenticacao/me`	Atualiza nome/e-mail.	admin
POST	`/api/autenticacao/change-password`	Troca senha (precisa da atual).	admin

API · Clientes

Prefixo /api/clientes. JWT único (mesmo aceito em /api/autenticacao/*); o payload customer inclui role.

Método	Rota	Função	Acesso
POST	`/api/clientes/register`	Cadastro público. Valida e-mail, WhatsApp e CEP. Retorna token.	público
POST	`/api/clientes/login`	Login do cliente.	público
GET	`/api/clientes/me`	Perfil do cliente logado.	cliente
PUT	`/api/clientes/me`	Atualiza nome, razão social, WhatsApp, CEP, endereço.	cliente
POST	`/api/clientes/change-password`	Troca senha.	cliente
GET	`/api/clientes`	Lista (filtros `?q=`, `?disabled=`) com pedidos, total gasto, último pedido.	admin
GET	`/api/clientes/:id`	Detalhe + lista de pedidos resumidos.	admin
PATCH	`/api/clientes/:id`	Edita perfil ou desabilita cliente.	admin
POST	`/api/clientes/:id/reset-password`	Define nova senha.	admin
DELETE	`/api/clientes/:id`	Exclui (bloqueia se tiver pedido — preferir desabilitar).	admin

API · Categorias

Prefixo /api/categorias.

Método	Rota	Função	Acesso
GET	`/api/categorias`	Lista (ordenada por `order` + nome).	público
GET	`/api/categorias/:id`	Categoria por id.	público
POST	`/api/categorias`	Cria (gera slug único).	admin
PUT	`/api/categorias/:id`	Atualiza nome, ícone, ordem.	admin
DELETE	`/api/categorias/:id`	Remove (bloqueia se houver produto vinculado).	admin

API · Produtos

Prefixo /api/produtos. Cada produto tem variações (cor/sabor), faces de impressão (frente/verso/lateral) com overlay e área útil, gabarito PDF pra download, tabela de desconto por volume e peso pra cálculo de frete.

Método	Rota	Função	Acesso
GET	`/api/produtos`	Lista (filtros `?category=`, `?all=`). Por padrão só ativos.	público
GET	`/api/produtos/:idOrSlug`	Detalhe por id ou slug.	público
GET	`/api/produtos/:id/quote?qty&variationId`	Cotação: aplica desconto da tabela e devolve unitário, bruto, desconto e total.	público
POST	`/api/produtos`	Cria produto (gera slug único, defaults seguros).	admin
PUT	`/api/produtos/:id`	Atualiza qualquer campo (faces, variações, descontos, gabaritos, etc.).	admin
DELETE	`/api/produtos/:id`	Remove produto.	admin

API · Pedidos

Prefixo /api/pedidos. Número no formato YYYY-NNNN sequencial por ano. Cada item snapshota o produto, faces e arte do cliente.

Método	Rota	Função	Acesso
POST	`/api/pedidos`	Cria pedido a partir do carrinho. Valida itens, recalcula preços, resolve frete, gera Pix.	cliente
GET	`/api/pedidos/me`	Pedidos do cliente logado (decorados com QR Pix se ainda não pagos).	cliente
GET	`/api/pedidos/:id`	Detalhe — cliente vê só o próprio; admin vê qualquer.	cliente admin
POST	`/api/pedidos/:id/comprovante`	Cliente envia URL do comprovante Pix → status vai pra aguardando_confirmacao.	cliente
PATCH	`/api/pedidos/:id/itens/:itemIdx/arte`	Cliente troca/remove arte de uma face (só enquanto editável).	cliente
POST	`/api/pedidos/:id/cancelar`	Cliente cancela enquanto está aguardando pagamento ou confirmação.	cliente
GET	`/api/pedidos`	Lista admin (filtros `?status=`, `?customer=`).	admin
PATCH	`/api/pedidos/:id`	Admin muda status, notas, frete. Loga histórico e dispara notificação WhatsApp.	admin

API · Frete

Prefixo /api/frete. Configuração singleton em data/shipping.json. Cálculo: retirada (se habilitada) → UF → região → fallback. Frete grátis zera o preço quando subtotal ≥ mínimo.

Método	Rota	Função	Acesso
GET	`/api/frete`	Configuração visível ao cliente (regras, retirada, frete grátis).	público
PUT	`/api/frete`	Salva configuração.	admin
POST	`/api/frete/calcular`	Calcula opções pro CEP/peso/subtotal. Resolve UF via ViaCEP se não enviado.	público

API · CEP

Prefixo /api/cep. Cache em memória (24h). Tenta ViaCEP, faz fallback pra BrasilAPI.

Método	Rota	Função	Acesso
GET	`/api/cep/:cep`	Retorna logradouro, bairro, cidade, UF. Usado no autofill do checkout/cadastro.	público

API · Arquivos

Prefixo /api/arquivos. Upload via multipart/form-data (campo file). Servido em /arquivos/<bucket>/<arquivo>.

Método	Rota	Função	Acesso
POST	`/api/arquivos/:bucket`	Upload autenticado pra qualquer bucket (`produtos`, `gabaritos`, `artes`, `pagamentos`).	admin
POST	`/api/arquivos/public/:bucket`	Upload público restrito a `artes` e `pagamentos`. Usado pelo cliente.	público

API · Notificações

Prefixo /api/notificacoes. Histórico em data/notifications.json; envio via WhatsApp Web API configurada em .env.

Método	Rota	Função	Acesso
GET	`/api/notificacoes/config`	Estado da integração (`enabled`, telefone admin, etc.).	admin
GET	`/api/notificacoes`	Histórico (filtros `?kind=`, `?status=`, `?limit=`).	admin
POST	`/api/notificacoes/teste`	Envia mensagem de teste pra um número.	admin

API · Health

Único endpoint em inglês — convenção de monitoramento.

Método	Rota	Função	Acesso
GET	`/api/health`	`{ success, service: 'copos', ts }`.	público

Coleções de dados

Banco em arquivos JSON em data/. Save com debounce de 500ms.

users.json: Admins (e-mail, hash bcrypt, role, disabled).
customers.json: Clientes (e-mail, nome, razão social, WhatsApp, hash, CEP, endereço, disabled).
categories.json: Categorias (nome, slug, ícone, ordem).
products.json: Produtos com imagens, gabaritos, faces (overlay+printArea), variações, tabela de desconto, prazo, peso, alertas.
orders.json: Pedidos com snapshot dos itens, frete resolvido, totais, pagamento Pix, status e histórico.
shipping.json: Singleton: regras de frete (UF, região, fallback), retirada local, frete grátis.
notifications.json: Log de envios WhatsApp (kind, to, status, orderId, sentAt).

Buckets de upload

Arquivos físicos em uploads/<bucket>/. URL pública: /arquivos/<bucket>/<arquivo>.

produtos

Fotos do catálogo (vitrine + página de produto).

imagem · até 10 MB · admin

gabaritos

Arquivos pra cliente baixar antes de mandar a arte (PDF, CDR, PNG, SVG, ZIP).

até 50 MB · admin

artes

Arte final que o cliente sobe pra cada face do produto.

PDF/PNG/JPG · até 50 MB · público

pagamentos

Comprovante Pix enviado pelo cliente após criar o pedido.

imagem/PDF · até 10 MB · público

Tokens JWT

Identidade única em customers.json + campo role. Um único JWT serve a admin e cliente. Token vai em Authorization: Bearer …, cookie auth_token ou query ?token=.

Payload: { uid, email, role, kind: 'user' } — uid aponta pra um registro em customers; role pode ser 'admin' ou 'customer'. Aliases userId/customerId mantidos pra retro-compat.
Storage no front: Login na loja escreve em copos_cust_token/copos_cust_user; se a role for admin, espelha em copos_token/copos_user para que páginas /admin-* e /painel funcionem sem novo login.
Middlewares: requireAuth (qualquer identidade), requireRole('admin'), requireCustomer (alias semântico), optionalAuth.

Notificações WhatsApp

Disparadas automaticamente em eventos do pedido. Configuração em .env (WA_API_URL, WA_API_KEY, WA_NOTIFY_ADMIN_PHONE, WA_BUSINESS_NAME, WA_PUBLIC_URL).

Pedido criado: Avisa admin do novo pedido aguardando_pagamento.
Comprovante recebido: Avisa admin que cliente subiu comprovante.
Mudança de status: Avisa cliente quando admin move o pedido (pago, em produção, enviado…).
Cancelamento: Notifica fluxo de cancelamento (cliente ou admin).