Clientes

Visão Geral

A página de Clientes agrega o histórico de pedidos por número de telefone, identificando clientes recorrentes, VIPs e novos — sem exigir cadastro explícito.

Localização

frontend-react/src/views/admin/CustomersView.tsx

Rota

/t/:slug/admin/customers

Como Funciona

O sistema cruza customerPhone dos pedidos entregues para construir um perfil por cliente. Nenhuma tabela de clientes separada é necessária — os dados vêm diretamente de Order.

Tags de Segmentação

Tag	Critério
VIP	≥ 10 pedidos ou gasto total ≥ R$ 500
Regular	3–9 pedidos
Novo	1–2 pedidos

Campos Exibidos

Campo	Descrição
Nome	customerName do pedido mais recente
Telefone	customerPhone (chave de agrupamento)
Total de Pedidos	Contagem de pedidos entregues
Gasto Total	Soma de totalAmount dos pedidos entregues
Último Pedido	Data do pedido entregue mais recente
Itens Favoritos	Os 3 itens mais pedidos pelo cliente
Tag	VIP / Regular / Novo

Exportação CSV

Clique em Exportar CSV (canto superior direito) para baixar a lista filtrada com todos os campos acima. Útil para disparos de WhatsApp/e-mail externos.

Endpoint de exportação

GET /t/:slug/customers/export?format=csv

Filtros e Busca

• Busca por nome ou telefone — campo de texto livre
• Filtro por tag — chips: Todos / VIP / Regular / Novo
• Ordenar por — Gasto Total (padrão) / Total de Pedidos / Último Pedido

API

Listar clientes

GET /t/:slug/customers?page=1&limit=20&tag=vip&search=joao

Resposta:

{
  "data": [
    {
      "customerPhone": "11999990000",
      "customerName": "João Silva",
      "totalOrders": 14,
      "totalSpent": 687.50,
      "lastOrderAt": "2026-03-04T21:30:00Z",
      "favoriteItems": ["Moqueca de Camarão", "Caipirinha", "Pudim"],
      "tag": "vip"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Exportar CSV

GET /t/:slug/customers/export?format=csv

Retorna text/csv com cabeçalho e todos os registros sem paginação.

Backend

backend/src/customers/customers.service.ts — usa agregação MongoDB para agrupar pedidos por customerPhone.

Relacionados

• Pedidos
• Relatórios