# 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.