# Manuais Documentação MOC Fidelidade — Manuais # Bem-vindo aos Manuais # Manuais de usuário — MOC Fidelidade Manuais completos em pt-BR pra cada um dos produtos da plataforma. Tudo publicado em **[docs.mocsolucoes.com.br](https://docs.mocsolucoes.com.br)** com busca, índice e versão atualizada automaticamente via CI. ## Por onde começar | Você é… | Use… | Tempo de leitura | |---|---|---| | **Dono ou gerente da empresa** | [Manual do Admin (web)](admin.md) | 20 min | | **Atendente/operador da empresa** | [Manual do AppEmpresa](app-empresa.md) | 15 min | | **Cliente final** | [Manual do AppCliente](app-cliente.md) | 8 min | > **Quick start:** [admin.md#primeiro-acesso](admin.md#primeiro-acesso) — em 5 passos seu programa de fidelidade está no ar. ## Links rápidos por necessidade - **Cadastrar primeira empresa:** [admin.md#primeiro-acesso](admin.md#primeiro-acesso) - **Gerar QR Code pra colar no balcão:** [admin.md#qr-code-da-empresa](admin.md#qr-code-da-empresa) - **Convidar operadores da equipe:** [admin.md#operadores](admin.md#operadores) - **Criar primeira recompensa:** [admin.md#recompensas](admin.md#recompensas) - **Trocar/escolher um plano:** [admin.md#plano-e-faturas](admin.md#plano-e-faturas) - **Como o cliente acumula:** [app-cliente.md#vincular-empresa](app-cliente.md#vincular-empresa) - **Operação no balcão (gerar código de marcação/pontos):** [app-empresa.md#gerar-codigo](app-empresa.md#gerar-codigo) - **Configurar pagamento (PIX/boleto/cartão):** [admin.md#pagamento](admin.md#pagamento) - **Reembolso ou cancelamento de conta:** [admin.md#encerrar-empresa](admin.md#encerrar-empresa) ## Treinamento ao vivo Empresas em plano Pro ou superior têm direito a 1h de treinamento em vídeo no primeiro mês de contrato. Para agendar, abra ticket em **Suporte > Treinamento** dentro do painel ou escreva pra [contato@mocfidelidade.com.br](mailto:contato@mocfidelidade.com.br). ## Para quem escreve / contribui - Linguagem **acessível** — evita jargão técnico, explica conceito quando precisa. - Foco em **tarefa** ("como fazer X") em vez de descrição de feature. - **Screenshots** podem ser adicionadas depois; manuais são auto-suficientes em texto puro pra serem renderizados como markdown em qualquer lugar. ## Versionamento Os manuais devem ser atualizados sempre que houver mudança de UX ou fluxo. Em particular: - Feature nova entrou em produção. - Passo a passo de algo já documentado mudou. - Mensagem de erro descrita mudou. Toda alteração em `docs/manuais/*.md` é sincronizada automaticamente pra BookStack (docs.mocsolucoes.com.br) e Wiki do GitLab via pipeline CI. ## Distribuição - **Online (recomendado):** [docs.mocsolucoes.com.br](https://docs.mocsolucoes.com.br) — sempre na última versão, com busca e formatação rica. - **Site institucional:** linkado na seção [FAQ](https://mocfidelidade.com.br/faq). - **Dentro do Admin:** menu lateral **Suporte > Manuais**. - **GitLab Wiki:** espelho versionado pra time interno. - **Markdown bruto:** este diretório, pra leitura em editor ou IDE. # 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. # Manual do AppCliente # Manual do AppCliente — MOC Fidelidade Bem-vindo! Este manual cobre tudo que você precisa pra usar o **MOC Fidelidade** como cliente — desde a instalação até resgate de recompensas. > **Pra quem é este app:** clientes que querem acompanhar pontos/marcações em programas de fidelidade das empresas que usam a plataforma MOC. --- ## 1. Instalação ### Android 1. Abra a **Play Store** no celular. 2. Procure por **"MOC Fidelidade"**. 3. Toque em **Instalar**. ### iPhone (iOS) 1. Abra a **App Store**. 2. Procure por **"MOC Fidelidade"**. 3. Toque em **Obter**. > O app é gratuito e não tem propaganda dentro. --- ## 2. Primeiro acesso Ao abrir, você vê uma tela de boas-vindas com o logo MOC. Daí pode escolher entre dois caminhos: ### a) Explorar sem conta Você pode **buscar empresas e ver o catálogo** sem precisar criar conta. Só precisa logar quando for **acumular pontos ou resgatar recompensas**. ### b) Entrar ou criar conta Toque em **"Entrar / Criar conta"** no menu lateral. Há quatro jeitos: - **E-mail e senha** — formulário tradicional, com recuperação por e-mail (código de 4 dígitos). - **Google** — usa sua conta Google. - **Facebook** — usa sua conta Facebook. - **Cadastro novo** — se ainda não tem conta, preencha nome, e-mail, telefone (opcional) e senha. > **Esqueceu a senha?** Toque em **"Esqueci minha senha"** na tela de login. Digite o e-mail, receba um código de 4 dígitos por e-mail, valide, e crie uma senha nova. O código vale por 24 horas. --- ## 3. Vincular-se a uma empresa Antes de acumular pontos, você precisa "entrar" no programa de fidelidade de cada empresa. Tem três jeitos: ### Buscar pelo nome 1. No menu lateral, toque em **"Buscar empresas"** (ou **"Trocar empresa"** se já estiver em uma). 2. Toque em **"Buscar empresa"** (botão flutuante). 3. Digite o nome da loja, café, restaurante. 4. Toque em **"Vincular"** ao lado do resultado. ### Escanear QR Code da loja 1. Na empresa parceira, a loja tem um QR Code visível (no balcão, vitrine, cartão). 2. No app, toque em **"Escanear QR Code da empresa"** no buscador, ou em qualquer tela use **"Escanear QR"** pelo menu. 3. Aponte a câmera. O app reconhece e oferece o vínculo. ### Clicar em um link compartilhado Se a loja te mandar um link `mocfidelidade.com.br/e/` por WhatsApp/SMS, basta clicar — o AppCliente abre direto na tela de vínculo (precisa estar instalado). > **Tudo precisa de login:** se você tentar vincular sem estar logado, o app pede o login primeiro e depois retoma o vínculo automaticamente. --- ## 4. Acumular marcações ou pontos Existem **dois modelos** de fidelidade, configurados por cada empresa: - **Marcações (mrc):** cartão fidelidade tradicional. Ex: "10 cafés = 1 grátis". A cada compra, você marca 1. - **Pontuação (ptc):** acumula pontos por consumo (ex: 1 ponto = R$ 1), troca pontos por recompensas. Pra registrar marcação/pontuação, a loja te entrega um **código de 5 dígitos** (ou um QR equivalente). Toque em **"Pontuar / Marcar"** (botão flutuante na tela principal) e: - **Escanear QR Code:** aponta a câmera, código entra automático. - **Digitar código:** abre teclado, digita os 5 dígitos. Pronto — saldo atualizado imediatamente. > Cada código serve **uma vez só**. Depois de usado, expira. --- ## 5. Tela principal (Home) Mostra a empresa ativa e seu saldo: - **Modelo marcação:** N estrelinhas preenchidas (ex: ★★★☆☆☆☆☆☆☆) + texto "faltam X pra recompensa". - **Modelo pontuação:** número grande de pontos disponíveis. Abaixo, **"Últimas atividades"** — histórico das últimas marcações/pontuações. > **Cartão laranja centralizado** com texto em negrito = saldo de pontuação. --- ## 6. Resgatar recompensas 1. No menu lateral, toque em **"Recompensas"**. 2. Há duas abas: - **Disponíveis** — produtos que você já consegue resgatar com seu saldo atual. - **Minhas** — histórico de resgates seus. 3. Toque na recompensa desejada → **"Solicitar resgate"**. O que acontece depois: - **Pontuação:** pontos são debitados imediatamente. Resgate fica **"solicitado"** até a loja entregar. - **Marcação:** marcações são debitadas e o status fica **"solicitado"**. A loja vai aprovar (ou cancelar) e marcar como **entregue** quando você retirar. --- ## 7. Ver várias empresas Se você participa de mais de um programa, troque entre elas: 1. Menu lateral → **"Trocar empresa"**. 2. Lista mostra todas em que você está vinculado. 3. Toque na empresa pra ativar. O saldo de cada empresa é **independente** — pontos de uma loja não somam com os de outra. --- ## 8. Catálogo - Menu lateral → **"Catálogo"**. - Vê todos os produtos da empresa ativa (mesmo os que ainda não consegue resgatar). - Cada produto mostra preço, pontos pra resgate e descrição. > Útil pra ver "quantos pontos faltam pro produto X". --- ## 9. Perfil e configurações ### Meus dados Menu lateral → **"Meus dados"**. Edita nome, telefone e e-mail (limitado). ### Alterar senha Menu lateral → **"Alterar senha"**. Pede senha atual + nova senha (mínimo 6 caracteres). ### Contato Menu lateral → **"Contato"** ou **"Fale com a gente"**. - **Logado:** abre um ticket vinculado à sua conta (histórico aparece dentro do app no time da loja). - **Deslogado:** preenche nome/e-mail/telefone + mensagem. Resposta chega no e-mail informado. ### Sobre Mostra versão do app, links pro site, política de privacidade e termos. --- ## 10. Notificações push Quando uma recompensa for aprovada/entregue, você recebe **notificação push** no celular. Pra ativar: - **Primeiro login:** o app pede permissão. Toque em **"Permitir"**. - **Negou por engano?** Vá em **Configurações do celular → Apps → MOC Fidelidade → Notificações** e ative. --- ## 11. Atualizar o app Quando uma nova versão sai, ao abrir o app você vê um **aviso de atualização**: - **Atualização opcional:** botão "Atualizar depois" disponível. - **Atualização obrigatória:** só dá pra prosseguir após atualizar (geralmente quando houve mudança crítica). Em ambos os casos, toque em **"Atualizar agora"** que vai pra Play Store/App Store. --- ## 12. Sair da conta Menu lateral → **"Sair"** (em vermelho, no rodapé). > Sair **não desvincula** das empresas. Quando logar de novo, suas empresas continuam ativas. --- ## 13. Perguntas frequentes (FAQ) **Posso usar a mesma conta em vários celulares?** Sim. Basta logar com o mesmo e-mail. **Perco meus pontos se desinstalar o app?** Não. Os pontos ficam no servidor, vinculados à sua conta. Reinstale e logue de novo. **Por que meu saldo não atualizou?** Puxe a tela pra baixo (refresh) na Home. Se persistir, abra um ticket pelo "Contato". **A loja diz que eu fiz uma compra mas não veio marcação. O que faço?** 1. Confirme com a loja que ela gerou um código MOC. 2. Se sim, verifique se você digitou/escaneou esse código no seu app. 3. Sem sucesso, abra ticket de suporte — informe data, valor e nome da loja. **A loja não aparece quando busco. E aí?** Pode ser que a loja ainda não esteja cadastrada no MOC. Você pode sugerir que ela visite **mocfidelidade.com.br** pra contratar o programa. **É seguro entrar com Google/Facebook?** Sim. A gente recebe só **nome + e-mail** do provedor — nunca senha. Você sempre pode desvincular depois em "Meus dados". **Como fechar minha conta?** Mande um ticket pelo "Contato" pedindo o encerramento. Atendemos em até 5 dias úteis. --- ## 14. Suporte - Dentro do app: menu **"Contato"**. - E-mail: **contato@mocfidelidade.com.br** - Site: **https://mocfidelidade.com.br** > Tudo em **horário de São Paulo (UTC-3)** — datas e horários no app já vêm convertidos. # Manual do AppEmpresa # Manual do AppEmpresa — MOC Fidelidade App mobile da **empresa-operadora** do MOC Fidelidade. Use no balcão, na recepção, no caixa — onde for atender o cliente. > **Pra quem é este app:** **administradores** e **operadores** das empresas que contratam o MOC Fidelidade. Tudo que o painel web (Admin) faz, esse app faz também. --- ## 1. Instalação ### Android 1. Abra a **Play Store**. 2. Procure por **"MOC Fidelidade - Empresa"**. 3. Toque em **Instalar**. ### iPhone 1. Abra a **App Store**. 2. Procure por **"MOC Fidelidade - Empresa"**. 3. Toque em **Obter**. > Existem **dois apps diferentes** no MOC: o **cliente** (pra quem acumula pontos) e o **empresa** (pra quem opera). Instale o certo! --- ## 2. Acessar a sua conta ### Primeiro acesso (já criou empresa pelo site) 1. Abra o app. 2. Toque em **"Entrar"**. 3. Use o **mesmo e-mail e senha** que você cadastrou no site **mocfidelidade.com.br** ao contratar. 4. Pronto — entra direto no painel da sua empresa. ### Esqueceu a senha? 1. Toque em **"Esqueci minha senha"**. 2. Digite seu e-mail → receba código de 4 dígitos no e-mail. 3. Valide o código. 4. Crie uma senha nova (mínimo 6 caracteres). ### Ainda não tem empresa cadastrada? Toque em **"Quero cadastrar uma empresa nova"** na tela de login — abre o site no navegador, onde o fluxo completo de cadastro (plano + dados) é feito. > **Operador convidado** (sem ser dono da empresa): você ganhou acesso por um convite. Faça o **"Esqueci minha senha"** com seu e-mail pra ativar a conta. --- ## 3. Escolher a empresa ativa Se você administra **mais de uma empresa**, após login aparece a tela **"Selecionar empresa"**: - Toque na empresa pra ativar. - Mostra seu papel: **Administrador** (gerencia tudo) ou **Operador** (opera o dia-a-dia). - Se só houver uma, o app pula direto pro dashboard. Pode trocar a empresa ativa depois: **menu lateral → "Trocar empresa"**. --- ## 4. Concluir cadastro (banner no dashboard) Se sua empresa foi recém-criada e ainda **não definiu CNPJ + razão social + nome fantasia + modelo de fidelidade**, aparece um **banner laranja** no dashboard pedindo pra concluir. 1. Toque em **"Concluir"** no banner. 2. Preencha: - CNPJ (opcional) - Razão social - Nome fantasia - **Modelo de fidelidade**: Marcações ou Pontos - Meta de marcações (se mrc) **ou** Pontos por R$ (se ptc) 3. Toque em **"Concluir cadastro"**. Após concluir, todas as telas refletem o modelo escolhido. --- ## 5. Dashboard (tela inicial) Mostra: - **Hero laranja:** modelo de fidelidade + total de clientes ativos. - **KPIs do dia:** códigos gerados/usados, marcações ou pontos creditados, recompensas pendentes. - **Ações rápidas:** atalhos pra gerar código, ler QR de cliente, ver clientes, recompensas etc. **Alertas que podem aparecer no topo:** - **Tarja vermelha — Cobrança em atraso:** fatura atrasada bloqueia operações novas (gerar código, criar produto). Toque em **"Ver"** pra pagar. - **Banner laranja — Concluir cadastro:** onboarding incompleto. --- ## 6. Gerar código pra cliente Operação principal do dia-a-dia. Cliente está no caixa, fez uma compra, hora de creditar marcação/pontuação. 1. Menu lateral → **"Códigos"** (ou ação rápida no dashboard). 2. Toque em **"Gerar código"** (botão flutuante). 3. Defina: - **Quantidade** — quantas marcações OU quantos pontos creditar. - **Expira em (minutos)** — padrão 60. Use menor pra códigos "de balcão", maior pra códigos por WhatsApp. 4. Toque em **"Gerar código"**. O app mostra um **QR Code grande** + **código de 5 dígitos** (toque pra copiar). O cliente: - **Escaneia o QR** pela câmera do celular (abre o AppCliente direto). - **OU digita** os 5 dígitos no AppCliente dele. ### Visual da tela - **Aguardando:** QR colorido + código grande. - **Usado (verde):** overlay verde com check + nome/avatar/horário de quem usou + quantidade creditada. **Atualiza em ~2 segundos** após o cliente usar — sem precisar atualizar manualmente. - **Expirado:** overlay cinza com "EXPIRADO". ### Histórico de códigos Toque no **ícone de histórico** (relógio) no topo. Lista os 200 mais recentes. Filtre por **Ativos / Usados / Expirados / Cancelados**. ### Cancelar um código ativo No histórico, cada código com status **Ativo** mostra um ícone vermelho de bloqueio no canto direito. Toque, confirme no diálogo, e o código fica **Cancelado** — não pode mais ser usado. Útil quando você gerou errado ou descobriu que ele vazou pra alguém que não devia receber. Códigos já **Usados** ou **Expirados** não precisam ser cancelados. --- ## 7. Ler QR Code do cliente Cliente está apresentando uma recompensa? Quer identificar o cliente rapidamente? 1. Menu lateral → **"Ler QR do cliente"** (ou ação rápida). 2. Aponte a câmera pro QR que o cliente está mostrando. 3. App identifica o cliente e abre a tela **detalhe do cliente** automaticamente. > Funciona com flash (toque no raio no topo) e câmera frontal (toque no switch). --- ## 8. Clientes Menu lateral → **"Clientes"**. - **Lista** todos os clientes vinculados à empresa ativa, ordenados por nome. - **Busca** por nome, e-mail ou telefone (debounced — digita e busca sozinho em meio segundo). - **Cada item** mostra saldo (marcações OU pontos, conforme modelo). ### Cadastrar cliente manual Toque em **"Novo cliente"**: - Nome (obrigatório) - E-mail (obrigatório) - Telefone (opcional) > **Idempotente no e-mail:** se já existe usuário com esse e-mail no MOC, vincula direto. Senão, cria conta nova com senha aleatória — cliente ativa via "esqueci minha senha". ### Detalhe do cliente Toque em um cliente. Mostra: - Foto/nome/e-mail. - **Card hero** do saldo (marcações ou pontos). - **Histórico** unificado: créditos, débitos, ajustes — cada item mostra origem (`código`, `resgate`, `ajuste manual`) + observação se houver. ### Ajustar saldo manualmente Toque em **"Ajustar saldo"** (botão flutuante) no detalhe do cliente. - Escolha **Creditar** ou **Debitar** (botão segmentado). - Digite **quantidade** (sempre positiva — o botão escolhe o sinal). - **Observação** (opcional, máx 255 caracteres) — fica visível no histórico do cliente. Use para: - Estornar marcação errada. - Premiar cliente por motivo especial. - Corrigir saldo após problema. --- ## 9. Recompensas Menu lateral → **"Recompensas"**. Lista os resgates da empresa. Filtre por status: - **Solicitadas** — cliente pediu o resgate, aguardando você aprovar. - **Aprovadas** — você aprovou, aguardando entrega. - **Entregues** — finalizadas. - **Canceladas** — descartadas. ### Ações inline (botões no card) - **Solicitada:** **Aprovar** (vira aprovada) ou **Cancelar** (devolve pontos no modelo ptc). - **Aprovada:** **Marcar como entregue** (finaliza) ou **Cancelar**. > Ação é **imediata** no card — sem confirmação extra. Em caso de erro, o card volta ao status anterior e mostra uma mensagem. --- ## 10. Produtos (catálogo) Menu lateral → **"Produtos"**. - Lista produtos da empresa com preview da foto, preço (em BRL), pontos pra resgate (modelo ptc). - **Inativos** aparecem riscados. ### Criar/editar produto Toque em **"Novo produto"** (FAB) ou em um produto existente. - **Foto** — tira foto ou escolhe da galeria. Upload em background com indicador. - **Nome** (obrigatório, máx 180 caracteres). - **Descrição** (opcional). - **Preço** em R$ (opcional). - **Pontos para resgate** (só aparece em modelo ptc). - **Categoria** (opcional, dropdown — aparecem só categorias ativas). - **Ativo** — toggle (inativo some das listas pro cliente). > **Remover foto?** Toque em **"Remover imagem"** abaixo da preview. ### Excluir produto Menu de 3 pontos (⋮) no item → **Excluir**. Confirmação modal. Resgates anteriores ficam intactos. --- ## 11. Categorias Menu lateral → **"Categorias"** (ou ícone de categoria no topo da tela de Produtos). - Lista das categorias da empresa. - CRUD simples: criar, renomear, ativar/desativar, excluir. > **Categoria com produto não pode ser excluída.** O backend devolve erro 409 e o app mostra mensagem. --- ## 12. Plano (só Admin) Menu lateral → **"Plano"**. Mostra: - Plano atual + valor mensal. - Janela de **trial** (se aplicável). - **Próxima fatura** (data prevista). - Limite de clientes ativos. Pra **trocar de plano**, use o site **mocfidelidade.com.br** ou o painel Admin (web). --- ## 13. Faturas (só Admin) Menu lateral → **"Faturas"**. Lista todas as faturas da empresa. Filtre por status: - **Abertas** — aguardando pagamento dentro do prazo. - **Atrasadas** — vencidas (bloqueia operações novas). - **Pagas** — quitadas. ### Detalhe da fatura Toque em uma fatura. - **Hero colorido** por status com valor e vencimento. - **Métodos de pagamento** (PIX, Boleto, Cartão) — toque pra iniciar checkout. #### PIX - Mostra **QR Code** + **código copia-e-cola**. - Toque em **"Copiar código PIX"** pra copiar pro clipboard. #### Boleto - **Linha digitável** (botão de copiar). - **Abrir boleto** — abre PDF no navegador. #### Cartão - Abre Checkout Pro do **Mercado Pago** no navegador. > **Idempotente:** se você já gerou o PIX/boleto, tocar de novo no método **não cria outro** — devolve o mesmo enquanto não expirar. --- ## 14. Operadores (só Admin) Menu lateral → **"Operadores"**. Lista todos os operadores vinculados à empresa, com badge **Admin** ou **Operador**. ### Convidar novo operador Toque em **"Convidar"** (FAB). - E-mail (obrigatório). - Nome (opcional — usado se for cadastro novo). - **Tipo:** - **Operador** — opera dia-a-dia (códigos, clientes, recompensas). - **Admin** — pode gerenciar plano, faturas, operadores e cadastros. > **Se o e-mail já tiver conta MOC**, vincula direto. Senão, cria com senha aleatória — o operador ativa via **"esqueci minha senha"**. ### Cota do plano O número de operadores que o plano permite é **adicional ao proprietário** — você (dono da conta) não consome a cota. Plano Start (1) = você + 1 funcionário. Profissional (3) = você + 3. E por aí vai. Pra saber quantos operadores adicionais seu plano permite, abra **Plano** no menu lateral. ### Remover operador Lixeira ao lado do operador → confirmação modal → remoção imediata. > **Operadores comuns** veem a lista mas não podem convidar/remover (botões somem). --- ## 15. Suporte (tickets MOC) Menu lateral → **"Suporte"**. - Lista tickets que você abriu pro time MOC, filtrados por status. - **Abrir ticket:** botão flutuante. Assunto + mensagem. ### Detalhe do ticket - Thread de mensagens com avatar e timestamp. - **Composer** no rodapé pra responder enquanto o ticket está **aberto** ou **em atendimento**. - **Fechar ticket:** ícone X no topo (não pode reabrir, mas pode criar outro depois). --- ## 16. Meus dados, Senha, Sobre ### Meus dados Menu lateral → **"Meus dados"**. Edita nome e telefone. E-mail é fixo. ### Alterar senha Menu lateral → **"Alterar senha"**. Pede senha atual + nova + confirmação (mínimo 6 caracteres). ### Sobre - Versão do app. - Links pra Site, Política, Termos. --- ## 17. Sair Menu lateral → **"Sair"** (em vermelho, no rodapé). Limpa a sessão local. Próximo acesso pede login. --- ## 18. Notificações push Quando um cliente solicita resgate, faz alguma operação relevante, ou uma fatura está perto de vencer, você recebe **notificação push**. - Permita no primeiro login. - Pra reativar depois: **Config do celular → Apps → MOC Fidelidade - Empresa → Notificações**. --- ## 19. Bloqueio por inadimplência Se sua empresa tem **fatura atrasada**, operações de mutação ficam bloqueadas (gerar código, criar produto, ajustar saldo). Aparece a tarja vermelha no dashboard. **Liberadas mesmo inadimplente:** - Login / leitura. - Ver clientes, faturas, plano. - **Pagar a fatura** (PIX/Boleto/Cartão). Após pagamento confirmado (webhook do PSP), a tarja some sozinha — pode demorar alguns minutos. --- ## 20. FAQ — Erros comuns **"Código não encontrado" ao cliente tentar usar:** - Cliente errou o código. - Código expirou (verifique TTL ao gerar). - Código já foi usado por outra pessoa (cada código é one-shot). **"Saldo insuficiente" ao debitar:** - Cliente não tem saldo pra completar o débito. - Verifique histórico no detalhe do cliente. **"Falha no checkout" da fatura:** - Mercado Pago instável — espere 1 minuto e tente de novo. - Verifique se o boleto não está vencido (depois de 30 dias o link some). **"Categoria com produto vinculado":** - Você tentou excluir uma categoria que tem produtos. Mude esses produtos pra outra categoria primeiro. **App pede pra atualizar e não deixa entrar:** - Atualização **obrigatória** por mudança crítica. Atualize na loja. --- ## 21. Limites do plano Cada plano tem **limite de clientes ativos no mês**. "Cliente ativo" = cliente que recebeu ao menos uma marcação/pontuação no mês corrente. Atingiu o limite? Operações de gerar código pra clientes **novos no mês** bloqueiam até o próximo ciclo. Considere **upgrade de plano**. --- ## 22. Suporte - **Dentro do app:** menu **"Suporte"**. - **E-mail:** **contato@mocfidelidade.com.br** - **Site:** **https://mocfidelidade.com.br** > Todos os horários no app aparecem em **horário de São Paulo (UTC-3)**.