Manual do Admin (Painel Web)

Manual do Admin (Painel Web) — MOC Fidelidade

Painel web da empresa-operadora. Tudo que o AppEmpresa (mobile) faz, o Admin também — com a vantagem de tela maior, mais dados em paralelo, e fluxos de cadastro mais ágeis (digitação, importação, atalhos de teclado).

Pra quem é este painel: administradores e operadores das empresas. Acesso pelo navegador, sem instalar nada.

---

1. Acesso

URL: https://admin.mocfidelidade.com.br (produção) ou local em desenvolvimento.

Primeiro acesso

1. Já criou empresa pelo site? Use o mesmo e-mail/senha que cadastrou.
2. Operador convidado por um admin? Faça "Esqueci minha senha" com seu e-mail pra ativar a conta.

Login

• Formulário tradicional e-mail + senha.
• Botões de Google e Facebook se você quer entrar com login social.
• "Esqueci minha senha" → código de 4 dígitos no e-mail → criar senha nova.

Sessão dura 7 dias. Depois pede login de novo.

---

2. Selecionar empresa ativa

Logou e tem mais de uma empresa? Aparece um seletor.

• Em qualquer momento, troque no popover do topo (clique no nome da empresa atual ao lado do logo).
• O popover mostra empresas ativas e papel (Admin/Operador).
• Se só houver uma, o painel pula direto pro dashboard.

---

3. Concluir cadastro (onboarding)

Empresa nova precisa de CNPJ + razão + fantasia + modelo de fidelidade pra liberar todas as funções.

• Banner laranja no topo do dashboard te leva pra /onboarding.
• Modelo: Marcação (mrc) ou Pontuação (ptc).
• Em mrc: define meta de marcações (ex: 10).
• Em ptc: define pontos por R$ (ex: 1).
• Salvar — pronto, painel reflete o modelo.

---

4. Dashboard

Tela inicial pós-login. Mostra:

• Cards KPI (códigos do dia, marcações/pontos creditados, recompensas pendentes, clientes ativos).
• Gráfico de série temporal dos últimos 30 dias (configurável).
• Top clientes (10 maiores saldos).
• Faturas próximas do vencimento (até 5).
• Tarja vermelha se há fatura atrasada.

---

5. Códigos

Sidebar → "Códigos".

• Coluna esquerda: form de gerar código novo (Quantidade + Expira em minutos + botão Gerar).
• Coluna direita: "Último código gerado" com QR Code grande, código de 5 dígitos e status em tempo real.

Atualização ao vivo

O painel atualiza sozinho a cada 2 segundos quando o cliente usa o código:

• Overlay verde sobre o QR.
• Cartão com foto/nome/e-mail/horário do cliente + quantidade creditada.

Sem precisar dar F5.

Lista histórica

Logo abaixo, lista paginada de códigos com filtros por status (ativo/usado/expirado/cancelado).

Cancelar código ativo

Cada linha da lista tem o botão Cancelar na coluna "Ações" (só aparece em códigos com status Ativo). Fluxo de 2 cliques:

1. Clique em Cancelar.
2. Botão muda pra "Cancelar 12345?" — confirme.

O código vira Cancelado (badge vermelho) e ninguém mais consegue usar. Se o cliente tentar escanear pelo app, recebe a mensagem "Código cancelado pela empresa". Use isso quando perceber que gerou errado, ou que o código vazou pra alguém indevido.

Códigos Usados ou Expirados não precisam (e não podem) ser cancelados.

---

6. Clientes

Sidebar → "Clientes".

Lista

• Paginada com busca (nome/e-mail/telefone).
• Sort por nome, e-mail, data de cadastro.
• Saldo conforme modelo (marcações ou pontos).

Cadastro manual

Botão "Novo cliente" → modal com nome, e-mail, telefone, celular. Idempotente no e-mail.

Detalhe (/clientes/:id)

• Header com foto, nome, e-mail, telefone.
• Saldo atual (card destacado).
• Histórico paginado (marcações ou pontuações), com colunas: data, quantidade, origem (código/resgate/ajuste), operador, observação.
• Ações:
  • Ajustar pontos — modal pra creditar/debitar com observação.
  • Produtos disponíveis — o que esse cliente já consegue resgatar agora.

---

7. Recompensas

Sidebar → "Recompensas".

Lista paginada com filtros por status (solicitada/aprovada/entregue/cancelada).

Cada linha mostra: produto, cliente, data, pontos gastos, status, ações.

Ações

• Solicitada → Aprovar / Cancelar.
• Aprovada → Marcar como entregue / Cancelar.
• Entregue / Cancelada → sem ações (final).

Premiar direto

Botão "Premiar cliente" abre modal pra dar recompensa imediata (debita pontos em ptc, status já entra como entregue) — útil pra premiação avulsa.

---

8. Produtos

Sidebar → "Produtos".

Lista

• Paginada com busca + filtro por categoria + filtro por ativo/inativo.
• Mostra thumb, nome, categoria, preço, pontos de resgate.

Criar/editar

• Foto (upload no MinIO; preview imediato).
• Nome, descrição, preço (BRL), pontos para resgate.
• Categoria (dropdown).
• Ativo (toggle).

Excluir

• Confirmação modal.
• Grava snapshot em produto_exclusao_log (visível em /produtos/excluidos) — não perde histórico.

---

9. Categorias

Submenu de Produtos ou link direto /categorias.

CRUD simples: lista + criar + renomear + ativar/desativar + excluir.

409 se houver produto vinculado — mude os produtos primeiro.

---

10. Plano (Admin only)

Sidebar → "Plano" ou popover de empresa.

Display do plano atual:

• Nome + valor mensal.
• Janela de trial (se aplicável).
• Próxima fatura.
• Limite de clientes ativos.

Trocar plano: botão "Trocar plano" abre modal com planos disponíveis. Antes do onboarding ser concluído, troca preserva o trial original. Depois, ajuste é proporcional (pro-rated).

---

11. Faturas (Admin only)

Sidebar → "Faturas".

Lista

• Paginada com filtro por status (aberta/atrasada/paga/cancelada).
• Colunas: id curto, valor, vencimento, status, ações.

Detalhe da fatura

• Hero colorido por status com valor + vencimento.
• Linhas da fatura (detalhamento do que está sendo cobrado).
• Métodos de pagamento:
  • PIX: QR + copia-e-cola.
  • Boleto: linha digitável + link do PDF.
  • Cartão: redireciona pro Checkout Pro do Mercado Pago.
• Marcar como paga manualmente (caso de pagamento offline — TED, dinheiro).

Tarja vermelha

Se há fatura atrasada, tarja vermelha persistente no topo do painel até regularizar. Endpoints de mutação devolvem HTTP 402.

---

12. Operadores (Admin only)

Sidebar → "Operadores".

Lista de vínculos ADM/OPERADOR da empresa ativa.

Convidar

• E-mail + nome (opcional) + tipo (Admin/Operador).
• Se e-mail já existe no MOC: vincula direto.
• Senão: cria conta com senha aleatória + envia e-mail de boas-vindas com link de "esqueci minha senha" pra operador ativar.

Cota do plano

• O número exibido em "Operadores adicionais" na tela /plano é quanto você pode convidar além de você. Proprietário (dono da conta) não consome cota — é só pra operadores funcionários.
• Ex.: plano Start (1 operador adicional) → você + 1 funcionário = 2 pessoas. Profissional (3) → você + 3 = 4 pessoas. E assim em diante.

Remover

• Botão de lixeira → confirmação → remoção imediata.

---

13. Suporte

Sidebar → "Suporte".

• Lista de tickets que você ou seus operadores abriram pro time MOC.
• Filtros por status (aberto/em_atendimento/fechado).
• Abrir ticket com assunto + mensagem inicial.
• Detalhe do ticket = thread de mensagens + composer pra responder.

---

14. Configurações da empresa

Sidebar → "Configurações" (ou clique no nome da empresa no topo → "Editar empresa").

• Dados: razão, fantasia, CNPJ, endereço, contato.
• Imagem da empresa: upload.
• Modelo de fidelidade: mrc / ptc (não recomendamos trocar após operação iniciada — clientes ficam confusos).
• Meta de marcações (mrc).
• Pontos por R$ (ptc).

---

15. Estatísticas (/stats)

Endpoint da API que alimenta gráficos do dashboard. No painel:

• Marcações: quantidade total + gráfico por dia.
• Pontuações: total de registros + soma de pontos + gráfico por dia.
• Recompensas: quantidade total por status.
• Clientes: total atual (sem série, por limitação do esquema legado).
• Por cliente: histórico paginado de marcações/pontuações no detalhe do cliente.

---

16. Atalhos e dicas

• Logo MOC no canto superior esquerdo sempre leva pro dashboard.
• Popover de empresa (clique no nome ao lado do logo) — troca empresa ativa rapidamente.
• Search global em algumas listas — comece a digitar enquanto a lista está focada.
• F5 normalmente desnecessário — telas de operação atualizam sozinhas (códigos via polling, recompensas/produtos via re-fetch após ação).

---

17. Permissões

Função	ADM	OPERADOR
Ver dashboard	✓	✓
Gerar código	✓	✓
Ler QR do cliente	✓	✓
Listar/cadastrar clientes	✓	✓
Ajustar saldo manual	✓	✓
Aprovar/cancelar recompensas	✓	✓
CRUD produtos e categorias	✓	✓
Ver faturas	✓	—
Pagar fatura	✓	—
Trocar plano	✓	—
Convidar/remover operador	✓	—
Editar dados da empresa	✓	—

---

18. Browsers suportados

• Chrome / Edge (recomendado).
• Firefox.
• Safari (macOS / iOS).

Versões dos últimos 2 anos. IE não é suportado.

---

19. Bloqueio por inadimplência

Igual ao mobile: tarja vermelha + endpoints de mutação devolvem 402.

• Você pode acessar a conta e pagar a fatura — esses endpoints continuam liberados.
• Após pagamento, a tarja some sozinha (webhook do PSP confirma em até alguns minutos).

---

20. FAQ

Painel fica "carregando…" infinito após login: Cookie de sessão pode estar corrompido. Tente logout (botão no canto superior direito) + login novamente. Se persistir, abra ticket.

"Saldo insuficiente" ao debitar: O cliente não tem saldo pra completar o débito. Confira histórico.

"Categoria com produto vinculado": Mude esses produtos pra outra categoria primeiro.

O cliente diz que escaneou mas não creditou: Verifique no histórico do cliente se a marcação/pontuação foi registrada. Se sim, o app dele pode estar com cache — peça pra puxar pra baixo na Home. Se não foi registrada, o código pode ter expirado entre gerar e escanear.

Como exportar lista de clientes? Funcionalidade futura. Por enquanto, use a busca + scroll. Se precisar de exportação massiva, abra ticket — fazemos manualmente.

Logo da empresa cortado? Use imagem quadrada (1:1) ou faça pequeno crop antes de subir. PNG transparente fica melhor.

Posso integrar com meu PDV / ERP? Sim, via API REST. Veja a doc Swagger em https://api.mocfidelidade.com.br/api.

---

21. Suporte

• Dentro do painel: sidebar → "Suporte" → "Abrir ticket".
• E-mail: contato@mocfidelidade.com.br
• Site: https://mocfidelidade.com.br

Datas e horários no painel aparecem em horário de São Paulo (UTC-3), independente do timezone do seu computador.