# context.md # Projeto Orvox Influencers ## 1. Visão geral Estou desenvolvendo um sistema para gerenciar influenciadores vinculados a cupons de desconto de uma loja online. A loja inicial será a **Orvox**, que usa **Nuvemshop** como plataforma de e-commerce. O objetivo do sistema é permitir que influenciadores tenham acesso a um painel próprio para acompanhar: * Uso do seu cupom; * Pedidos gerados; * Pedidos pendentes; * Pedidos pagos; * Pedidos cancelados; * Pedidos reembolsados; * Valor previsto a receber; * Valor aprovado; * Valor já pago; * Histórico de pagamentos; * Produtos vendidos; * Dias e horários em que o cupom foi mais utilizado; * Progresso de metas; * Badges conquistadas; * Gamificação e bônus. O sistema deve ser construído inicialmente para a Orvox, mas já preparado para futuramente virar um mini-SaaS para pequenos empreendedores. --- # 2. Stack desejada O sistema será desenvolvido com: * Laravel 13; * Livewire; * Blade; * Tailwind CSS; * Banco relacional, preferencialmente MySQL; * Jobs/queues para sincronização com plataformas externas; * Webhooks para eventos da Nuvemshop; * Estrutura preparada para múltiplas lojas e múltiplos players no futuro. --- # 3. Decisão arquitetural principal Mesmo que o MVP seja usado inicialmente apenas pela Orvox, o sistema já deve nascer com uma estrutura preparada para mini-SaaS. A Orvox será cadastrada como o primeiro cliente/tenant do sistema. A Nuvemshop será cadastrada como o primeiro player/provider de integração. A Orvox terá uma loja vinculada à Nuvemshop, contendo as credenciais e dados necessários para integração. A estrutura conceitual será: ```text Tenant / Cliente → Loja → Player / Provider → Integração da loja → Influenciadores → Cupons → Pedidos → Comissões → Fechamentos → Gamificação ``` Exemplo inicial: ```text Tenant: Orvox Loja: Orvox Oficial Provider: Nuvemshop Integração: access_token, store_id/user_id e demais dados da Nuvemshop ``` O MVP não precisa ter ainda: * Cadastro público de clientes; * Planos SaaS; * Billing; * Assinaturas; * Limites por plano; * Onboarding self-service; * Integrações com outros players. Mas o banco e os relacionamentos já devem estar preparados para isso. --- # 4. Entidades principais sugeridas ## 4.1 Tenants Representa o cliente do sistema. Exemplo: Orvox. Campos esperados: ```text id name slug status created_at updated_at ``` --- ## 4.2 Stores Representa uma loja pertencente a um tenant. Campos esperados: ```text id tenant_id name slug status created_at updated_at ``` --- ## 4.3 Integration Providers Representa os players/plataformas de e-commerce. Exemplos futuros: ```text nuvemshop shopify woocommerce tray mercado_livre ``` Campos esperados: ```text id name slug status created_at updated_at ``` --- ## 4.4 Store Integrations Representa a integração de uma loja com um player. Para Nuvemshop, deve armazenar: ```text id tenant_id store_id provider_id external_store_id access_token refresh_token scopes status installed_at disconnected_at metadata created_at updated_at ``` Observação: Mesmo que a Nuvemshop use access_token sem expiração normal, manter `refresh_token` e `metadata` para compatibilidade futura com outros players. --- # 5. Influenciadores O admin poderá cadastrar influenciadores. Campos necessários: ```text id tenant_id store_id user_id name email instagram tiktok cpf_cnpj pix_key base_commission_percentage status internal_notes created_at updated_at ``` O influenciador fará login com e-mail e senha criada pelo administrador. Também deve existir: * Redefinição de senha; * Possibilidade do admin trocar senha; * Possibilidade de inativar influencer; * Histórico de comissões; * Histórico de pagamentos; * Histórico de cupons. --- # 6. Cupons ## 6.1 Regra geral Cada influenciador terá **um cupom ativo por vez**. Porém, o sistema deve manter histórico para permitir troca futura de cupom sem perder o vínculo dos pedidos antigos. Exemplo: ```text Influencer Ana Cupom antigo: ANA10 Cupom novo: ANA15 ``` Pedidos antigos continuam vinculados ao cupom antigo. --- ## 6.2 Criação do cupom O sistema deve criar o cupom diretamente na Nuvemshop. Fluxo desejado: 1. Admin cadastra influencer; 2. Admin define código do cupom, percentual de desconto e demais configurações; 3. Sistema cria o cupom na Nuvemshop; 4. Sistema salva o vínculo cupom → influencer; 5. Se a criação do cupom falhar, o influencer/cupom não deve ser ativado. --- ## 6.3 Validação do cupom Como o sistema criará o cupom na Nuvemshop, ele deve validar a criação. Regras: * Validar no cadastro; * Impedir cupom duplicado; * Salvar retorno da Nuvemshop; * Manter rotina de conferência para identificar cupom removido ou alterado diretamente na Nuvemshop. --- ## 6.4 Maiúsculas e minúsculas O sistema deve salvar: ```text coupon_code_original coupon_code_normalized ``` Exemplo: ```text coupon_code_original = "Maria10" coupon_code_normalized = "MARIA10" ``` A comparação interna deve usar o código normalizado. A exibição pode manter o código original. --- # 7. Pedidos e vendas ## 7.1 Quando um pedido conta como venda Um pedido só conta como venda válida quando estiver pago. Pedidos criados ou pendentes podem aparecer como uso preliminar do cupom, mas não entram em comissão nem gamificação até confirmação do pagamento. --- ## 7.2 Pedidos pendentes Pedidos pendentes aparecem no dashboard como movimentação do cupom, mas: * Não geram comissão; * Não entram em gamificação; * Não contam como venda válida. --- ## 7.3 Pedido cancelado antes do fechamento Pedido cancelado antes do fechamento: * Não gera comissão; * Pode continuar aparecendo como uso bruto do cupom; * Não conta como venda válida; * Não entra em metas/gamificação. --- ## 7.4 Pedido cancelado depois do fechamento Pedido cancelado depois do fechamento mensal: * Não reabre fechamento anterior; * Gera estorno no próximo fechamento; * O sistema deve lançar ajuste negativo vinculado ao pedido original. --- ## 7.5 Pedido cancelado depois que o influencer já recebeu Se o influencer já recebeu e depois o pedido for cancelado ou reembolsado: * A comissão será estornada no próximo pagamento; * O sistema deve registrar ajuste negativo com referência ao pedido original; * Em casos excepcionais, o admin principal poderá revisar manualmente. --- # 8. Comissão ## 8.1 Comissão base A comissão base inicial será de 8%. Regras: * 8% padrão para todos; * Pode ser personalizada por influencer; * Deve haver histórico de alteração; * Cada pedido deve salvar o percentual aplicado na época. --- ## 8.2 Base de cálculo da comissão A comissão será calculada sobre: ```text Valor pago dos produtos após desconto do cupom, sem considerar frete. ``` Regras: * Não calcular comissão sobre frete; * Não calcular sobre valores não relacionados a produtos; * Inicialmente não descontar taxas de gateway/maquininha para manter o cálculo simples e transparente; * O sistema deve salvar a base de cálculo congelada no pedido. Exemplo: ```text Produto: R$ 200,00 Cupom: 10% Cliente paga pelos produtos: R$ 180,00 Frete: R$ 20,00 Base de comissão: R$ 180,00 Comissão de 8%: R$ 14,40 ``` --- ## 8.3 Mudança de comissão Se a comissão de um influencer mudar de 8% para 10% no meio do mês: * Pedidos antigos continuam com 8%; * Nova comissão passa a valer apenas para pedidos futuros; * O sistema deve salvar no pedido o percentual aplicado no momento da venda/pagamento. Campos importantes no pedido/comissão: ```text commission_percentage commission_base_amount commission_amount ``` --- ## 8.4 Status da comissão Os status da comissão devem ser: ```text Pendente Prevista Aprovada Liberada para pagamento Paga Cancelada Estornada ``` Significado: ```text Pendente: Pedido identificado com cupom, mas ainda sem pagamento confirmado. Não gera comissão ainda. Prevista: Pedido pago e comissão calculada, mas ainda sujeita a validação, cancelamento, reembolso ou prazo de segurança. Aprovada: Comissão validada e considerada válida para o fechamento mensal. Liberada para pagamento: Comissão já incluída no fechamento e pronta para ser paga ao influencer. Paga: Comissão paga ao influencer. Cancelada: Comissão removida porque o pedido foi cancelado/reembolsado antes de ser paga. Estornada: Comissão que já havia sido aprovada ou paga, mas precisou ser descontada em fechamento futuro por cancelamento/reembolso posterior. ``` Fluxo esperado: ```text Pedido com cupom e pagamento pendente → Comissão pendente Pedido pago → Comissão prevista Passou validação / prazo de segurança → Comissão aprovada Fechamento mensal finalizado → Liberada para pagamento Admin pagou o influencer → Paga Pedido cancelado antes do pagamento → Cancelada Pedido cancelado depois de aprovada/paga → Estornada ``` --- # 9. Fechamento mensal ## 9.1 Período O fechamento será do dia 1 ao último dia do mês. --- ## 9.2 Data usada no fechamento O fechamento deve considerar a data de pagamento do pedido. Regra: ```text Pedido criado em junho, mas pago em julho, entra no fechamento de julho. ``` --- ## 9.3 Prazo de segurança A comissão ficará em validação por 7 dias antes de ser liberada. --- ## 9.4 Pagamento do influencer No MVP, o pagamento será feito manualmente fora do sistema. O sistema deve permitir: * Gerar planilha de fechamento; * Listar influencer; * ID do influencer; * Cupom; * Valor bruto; * Estornos; * Valor final; * Chave Pix; * Status; * Campo para data de pagamento; * Campo para status do pagamento; * Importar planilha preenchida para atualizar pagamentos; * Marcar pagamento manualmente pela tela; * Registrar usuário/admin que confirmou; * Registrar data e hora da confirmação; * Opcionalmente anexar comprovante. Integração futura com gateway/Pix, como Efí, pode ficar para fase posterior. --- # 10. Gamificação ## 10.1 Regra geral A gamificação será baseada em desempenho mensal. No MVP, a principal métrica será: ```text Valor vendido no mês ``` Mas a estrutura deve permitir futuramente metas por: ```text Valor vendido Quantidade de pedidos pagos Quantidade de usos do cupom Ticket médio Produtos específicos Categorias específicas ``` --- ## 10.2 Bônus O bônus da gamificação será um percentual extra somado à comissão base. Exemplo: ```text Comissão base: 8% Bônus por meta: +2% Comissão final no período: 10% ``` --- ## 10.3 Regras não acumulativas O admin poderá configurar várias regras, mas o sistema aplicará apenas a maior regra atingida no período. Exemplo: ```text R$ 1.000 vendidos → Bronze +1% R$ 3.000 vendidos → Prata +2% R$ 5.000 vendidos → Ouro +4% ``` Se o influencer vender R$ 5.200, recebe apenas +4%, e não +1 +2 +4. --- ## 10.4 Badges Badges conquistadas serão permanentes. Porém: * Badge é permanente/histórica; * Bônus financeiro vale apenas para o período em que a meta foi atingida; * Badge não será removida depois; * Cancelamento posterior ajusta comissão, mas não remove badge antiga. --- ## 10.5 Cancelamentos e gamificação Pedidos cancelados ou reembolsados não contam para metas de gamificação. Se o cancelamento ocorrer depois do fechamento: * Comissão será ajustada por estorno; * Badge já conquistada não será removida. --- # 11. Dashboard do influenciador O influencer poderá ver: * Resumo geral; * Valor a receber no mês; * Comissão prevista; * Comissão aprovada; * Comissão paga; * Quantidade de usos do cupom; * Vendas confirmadas; * Vendas pendentes; * Vendas canceladas; * Pedidos individuais; * Produtos vendidos; * Total vendido; * Ticket médio; * Dias de maior uso; * Horários de maior uso; * Gráficos por dia; * Gráficos por horário; * Gráficos por dia da semana; * Gráficos por mês; * Evolução da comissão; * Progresso da meta; * Próxima meta; * Badges conquistadas; * Histórico mensal; * Histórico de pagamentos; * Exportar relatório. --- ## 11.1 Dados de clientes O influencer não verá dados pessoais dos clientes. Não mostrar: * Nome do cliente; * E-mail; * Telefone; * CPF/CNPJ; * Endereço; * Dados pessoais em geral. Pode mostrar: * Número do pedido; * Data do pedido; * Status; * Valor considerado para comissão; * Comissão calculada; * Produtos comprados. --- # 12. Painel administrativo O admin deve conseguir: * Login; * Cadastrar influenciadores; * Editar influenciadores; * Inativar influenciadores; * Alterar senha; * Criar/vincular cupom; * Alterar comissão base; * Ver todos os pedidos; * Ver relatório por influencer; * Ver relatório geral; * Configurar regras de gamificação; * Fazer fechamento mensal; * Marcar comissão como paga; * Lançar ajustes manuais; * Exportar relatórios; * Gerenciar integrações; * Ver status da sincronização; * Ver falhas de integração; * Reprocessar pedidos; * Reprocessar fechamento, se necessário. Ajustes manuais só devem ser permitidos para admin principal. --- # 13. Integração com Nuvemshop ## 13.1 Tipo de integração O sistema deve usar: * Webhooks; * Importação agendada. Webhooks serão usados para atualização rápida. Importação agendada será usada como fallback e reconciliação. --- ## 13.2 Frequência A importação agendada deve rodar a cada 1 hora. Também é recomendável ter um job diário de reconciliação dos últimos 30 dias para corrigir eventuais falhas de webhook. --- ## 13.3 Eventos importantes Eventos que o sistema precisa acompanhar: * Pedido criado; * Pedido pago; * Pedido cancelado; * Pedido reembolsado; * Pedido atualizado; * Cupom criado; * Cupom alterado; * Cupom removido. Mesmo que alguns eventos fiquem para fase posterior, a estrutura deve permitir recebê-los. --- ## 13.4 Autenticação Nuvemshop O sistema deve ser preparado para OAuth da Nuvemshop. Dados importantes: ```text client_id client_secret redirect_uri access_token store_id / user_id scopes ``` Separar: ## Credenciais globais do app São credenciais do aplicativo criado na Nuvemshop: ```text client_id client_secret redirect_uri ``` Essas podem ficar em `.env` ou configuração global segura. ## Credenciais da loja São dados da loja conectada: ```text store_id / user_id access_token scopes status installed_at disconnected_at metadata ``` Essas ficam vinculadas a tenant/store/store_integration. --- # 14. Segurança e LGPD O sistema deve salvar o mínimo possível de dados pessoais de clientes. Regras: * Influencer nunca vê dados pessoais do cliente; * Admin pode ver apenas o necessário; * Evitar salvar JSON completo do pedido com dados sensíveis, exceto se for necessário para auditoria; * Se salvar payload bruto, restringir acesso; * Armazenar tokens de integração de forma segura; * Registrar logs de sincronização; * Registrar ações administrativas sensíveis; * Registrar quem alterou comissão, quem fez fechamento e quem marcou pagamento. --- # 15. Relatórios O sistema deve ter relatórios de: * Comissão por influencer; * Vendas por cupom; * Vendas por período; * Ranking de influencers; * Fechamento mensal; * Estornos; * Cancelamentos; * Reembolsos; * Gamificação; * Exportação CSV; * Exportação Excel. PDF pode ficar para depois. --- # 16. MVP ## 16.1 O MVP deve conter obrigatoriamente * Login do admin; * Login do influencer; * Cadastro de influencer; * Criação/vínculo de cupom na Nuvemshop; * Importação de pedidos da Nuvemshop; * Webhooks principais; * Cálculo de comissão; * Dashboard básico do influencer; * Relatório administrativo; * Fechamento mensal; * Marcação de comissão como paga; * Gamificação básica; * Badges; * Gráficos principais; * Exportação CSV/Excel; * Estrutura com tenants/stores/providers preparada para futuro mini-SaaS. --- ## 16.2 Pode ficar para depois * Multi-tenant completo com onboarding público; * Planos SaaS; * Billing; * Assinaturas; * Integração com outros players; * Integração Pix/Efí; * Área pública de cadastro de clientes; * Limites por plano; * PDF avançado; * Automação completa de pagamentos. --- # 17. Resumo das decisões principais ## Comissão será calculada sobre ```text Valor pago dos produtos após desconto do cupom, sem considerar frete. Inicialmente, taxas de gateway/maquininha não serão descontadas da base de cálculo. ``` ## Pedido válido será ```text Pedido com pagamento confirmado. Pedidos pendentes aparecem como movimentação do cupom, mas não geram comissão nem contam para gamificação. ``` ## Cancelamento após fechamento será tratado como ```text Cancelamentos ou reembolsos após fechamento gerarão estorno/ajuste negativo no próximo fechamento, sem reabrir o fechamento anterior. ``` ## Cupom por influencer será ```text Um cupom ativo por influencer. O sistema deve manter histórico para permitir troca futura sem perder vínculo dos pedidos antigos. ``` ## Gamificação será baseada em ```text No MVP, principalmente em valor vendido no mês. A estrutura deve permitir futuramente regras por valor vendido, quantidade de pedidos ou quantidade de usos do cupom. ``` ## Bônus será ```text Percentual extra somado à comissão base. O sistema aplicará apenas o maior bônus atingido no período, sem acumular múltiplas regras. ``` ## Influencer verá dados de pedidos? ```text Sim, poderá ver pedidos individuais sem dados pessoais do cliente. Pode ver número do pedido, data, status, valor, comissão e produtos comprados, mas não nome, e-mail, telefone, CPF/CNPJ ou endereço. ``` ## MVP terá obrigatoriamente ```text Login de admin e influencer, cadastro de influencer, criação/vínculo de cupom na Nuvemshop, importação de pedidos, webhooks, cálculo de comissão, dashboard do influencer, painel administrativo, fechamento mensal, marcação de pagamento, gamificação básica, badges, gráficos e exportação CSV/Excel. ``` --- # 18. Orientação para o novo chat Ao continuar este projeto em outro chat, considerar este arquivo como a fonte principal de contexto. Antes de gerar código, o próximo passo recomendado é transformar este contexto em: 1. Escopo técnico fechado; 2. Lista de módulos; 3. Modelagem de banco; 4. Fluxos principais; 5. Migrations; 6. Models; 7. Services; 8. Jobs; 9. Webhooks; 10. Livewire components; 11. Telas do admin; 12. Dashboard do influencer; 13. Ordem de implementação. Não iniciar criando telas antes de fechar a modelagem de dados e os fluxos de comissão/pedidos.