Guia da loja do servidor no Levlix

O módulo de loja do Levlix permite que os admins do servidor ofereçam itens que podem ser comprados com a moeda virtual de pontos do servidor. Os membros podem navegar pelos itens disponíveis, comprá-los com seu saldo de pontos e ver todo o histórico de compras, seja pelos comandos de barra do Discord ou diretamente pelo painel web.

Onde os membros podem comprar

Há duas formas igualmente válidas de navegar e comprar:

1. No Discord, usando os comandos de barra /shop documentados abaixo.
2. No painel web, em Economia → Loja. Os membros veem o mesmo catálogo que os admins do servidor configuraram, com o saldo de pontos atual, selos de disponibilidade e o histórico completo de compras.

Comprar pelo painel passa exatamente pelas mesmas verificações de segurança que o comando de barra: datas de disponibilidade, término, limites de compra, estoque e pagamento são todos verificados no servidor. O desconto dos pontos e a atribuição do código acontecem em uma única transação no banco de dados, então uma compra que falha no meio do caminho (por exemplo, porque o estoque de códigos acabou naquele exato momento) nunca custa pontos: ninguém é cobrado por um código que não recebeu.

Comandos para membros

Há um único comando para membros:

/shop

Ele abre o painel da loja com duas abas:

A opção tab permite abrir o painel diretamente em uma aba. Itens que você já comprou até o limite e itens esgotados não são oferecidos.

Depois de uma compra confirmada:

1. O Levlix verifica seu saldo atual e o estoque do item.
2. O código do item é enviado a você por mensagem direta.
3. Se suas mensagens diretas estiverem fechadas, o código é mostrado em uma mensagem efêmera (que só você vê).
4. Seu saldo de pontos é reduzido pelo preço do item.

Para itens entregues pelo bot não há código: o item é aplicado a você e a confirmação informa isso. A aba Minhas compras lista primeiro os seus efeitos ativos.

Se você não tiver pontos suficientes, o Levlix informa quantos pontos são necessários e quantos você tem no momento.

Comprando pelo painel

Abra Economia → Loja no painel web do Levlix. Os membros caem direto na vitrine da loja; quem gerencia o servidor vê por padrão a tela de gerenciamento e pode abrir a loja como os membros a veem acrescentando ?view=store ao URL da loja.

A página da loja mostra:

Revelando um código que você comprou

Para proteger os códigos comprados caso alguém espie sua tela, o histórico de compras mostra por padrão apenas os últimos quatro caracteres de cada código. Clique em Revelar em uma linha para buscar o valor completo quando precisar. Cada revelação é registrada, então você sempre tem a prova do que resgatou e quando.

Compras de itens entregues pelo bot mostram o que você comprou e o status (ativo até, agendado, usado, expirado, revogado, reembolsado) em vez de um código.

Itens esgotados e agendados

• Itens esgotados aparecem em cinza e não podem ser comprados. Eles continuam na página para que os membros vejam o que já foi oferecido.
• Itens agendados mostram a data em que serão liberados. O botão de compra fica desativado até que available_from seja atingido.
• Itens expirados continuam listados com o selo Expirado e não podem ser comprados.

Admin: gerenciando a loja

Os admins adicionam, editam e removem itens da loja pelo painel web do Levlix. Cada item tem as seguintes opções de configuração:

Quando todos os códigos de um item são vendidos, o item é marcado automaticamente como esgotado e some da lista da loja.

Um item que ninguém comprou ainda pode ser excluído. Assim que alguém o compra, o cartão dele mostra Encerrar agora em vez de Excluir: as compras e quaisquer cargos, bônus ou apelidos em andamento continuam vinculados ao item, então ele é encerrado em vez de removido. Encerrar agora define a data de término para o momento atual, o item sai da loja na hora e permanece na lista de gerenciamento em Expirados. Para vendê-lo de novo, dê a ele uma nova data de término em Editar.

Para um gerenciamento rápido dentro do Discord, abra /setup, escolha Engajamento e depois Loja. O painel da loja lista os seus itens e tem os botões Criar item, Publicar vitrine e Verificar expiração agora, além de um menu que publica um único item em um canal. Gerentes da loja sem a permissão Gerenciar servidor chegam ao mesmo painel com o botão Gerenciar loja em /shop. O painel web continua sendo a forma mais confortável de trabalhar com vários itens ao mesmo tempo.

Filtrar itens da loja por status

A página de gerenciamento tem um filtro de status (Todos, Ativos, Agendados, Expirados, Esgotados) para você ir direto aos itens que precisam de atenção. O status é derivado das mesmas regras que a loja aplica aos membros, o que significa que as duas telas nunca podem divergir.

Itens entregues pelo bot

Além de códigos, a loja pode vender coisas que o próprio bot aplica. Escolha o tipo ao criar o item; o tipo não pode ser alterado depois, mas as configurações dele podem.

Todo item entregue pelo bot pode ter um estoque (quantas unidades existem no total), um limite de compras por membro, os dois ou nenhum. Itens de código continuam calculando o estoque pelo número de códigos não usados.

Como funciona a entrega

• Comprar no Discord aplica o item na hora. Comprar no painel passa a tarefa ao bot, que a aplica em no máximo alguns minutos, mesmo que estivesse offline no momento da compra.
• Comprar de novo um item com duração prolonga o item: o novo período começa quando o atual termina.
• Um bônus de XP pessoal nunca se acumula com um bônus do servidor inteiro. Vale o multiplicador maior.
• Os escudos de sequência são usados automaticamente: quando um membro perde dias, um escudo por dia perdido é consumido e a sequência continua. Sem escudos suficientes, a sequência é zerada e os escudos são mantidos.
• Um item de apelido deixa o membro digitar o texto; o bot o encaixa no seu modelo (por exemplo VIP {text}). O texto passa pelos filtros de palavras da moderação do servidor quando o módulo de moderação está ativado.
• Quando um item termina, o bot remove o cargo ou restaura o apelido anterior. Um cargo que o membro já tinha antes da compra nunca é removido, e um apelido que o membro mudou nesse meio-tempo não é tocado.

Reembolsos

Se o bot não conseguir aplicar um item (o cargo foi excluído, falta a permissão ao bot, o membro saiu ou o dono do servidor comprou um apelido), a compra é reembolsada automaticamente: os pontos voltam ao saldo, a unidade do estoque é liberada e o comprador recebe uma mensagem direta com o motivo. A compra aparece como Reembolsado no histórico.

Revogando uma concessão

Os gerentes veem quem tem no momento um item entregue pelo bot em Concessões, no cartão do item, e podem revogar uma concessão ali. O bot a desfaz em poucos minutos. Revogar não gera reembolso.

Anúncios de compra

Ative Anunciar compras e escolha um canal para que o bot publique uma mensagem curta sempre que alguém comprar o item. Os membros são mencionados nessa mensagem.

As Configurações da loja, no topo da página de gerenciamento, guardam os padrões que todo item herda: um canal de anúncios padrão e se os novos itens começam com os anúncios ativados. Um item sem canal próprio publica no canal padrão; os resultados dos sorteios da loteria usam o mesmo recurso. Sem um canal padrão, cada item com anúncios precisa escolher o próprio canal. O Nível do gerente da loja continua nas Configurações do servidor.

Loteria

Um item de loteria funciona em rodadas. Cada bilhete comprado paga seu preço, menos a taxa da casa, ao pote da rodada; a taxa da casa simplesmente sai de circulação. No horário do sorteio, o bot escolhe um bilhete ao acaso (cada bilhete conta uma vez, então mais bilhetes significam mais chances), paga o pote inteiro em pontos a esse membro, publica o resultado no canal de resultados e abre a próxima rodada. Uma rodada sem bilhetes é encerrada sem aviso.

Os gerentes podem usar Sortear agora (o sorteio acontece em até um minuto) e Cancelar rodada (todos os bilhetes são reembolsados e a próxima rodada começa; o bot publica um aviso curto). Um item de loteria não pode ser excluído enquanto a rodada aberta tiver bilhetes: sorteie ou cancele antes. Deixar o item expirar interrompe a venda de bilhetes, mas a rodada aberta ainda é sorteada.

O cartão na loja mostra o pote atual, quantos bilhetes há nele, os seus próprios bilhetes e o horário do próximo sorteio. A tela /shop do Discord mostra a mesma linha.

Cargo de gerente da loja

Por padrão, só os admins do servidor podem gerenciar a loja. Se você quiser permitir que outro cargo (por exemplo um gerente de comunidade ou uma equipe da loja dedicada) crie e edite itens, defina o Nível do gerente da loja em Configurações do servidor como Moderadores+ ou Administradores e dono. A hierarquia de cargos (user → moderator → admin → owner) determina quem vê a tela de gerenciamento e quem vê a loja.

Membros abaixo do cargo configurado sempre caem na vitrine da loja, mesmo que abram diretamente o URL de gerenciamento. Gerentes que visualizam a loja mantêm o link Voltar ao gerenciamento para nunca se perderem.

Gerenciando os saldos dos usuários

Os administradores do servidor podem adicionar, remover ou ajustar manualmente o saldo de pontos de um membro pelo painel web do Levlix. Toda alteração fica registrada no histórico de auditoria, com total transparência.

Casos especiais e notas de segurança

• Verificação de membro em toda compra pelo painel. O URL da loja é público para qualquer pessoa com uma conta Levlix, mas só os membros do servidor podem de fato comprar: o processamento da compra confere a participação no servidor antes de tocar no estoque de códigos.
• Sempre um código por comprador. Um breve bloqueio no banco de dados é aplicado à linha do comprador enquanto a compra está em andamento, então clicar duas vezes no botão de compra (ou a mesma pessoa abrir duas abas) nunca resgata dois códigos com um só pagamento.
• Bot fora do ar? As compras continuam funcionando. As compras pelo painel são publicadas via Redis para que o bot possa mandar uma mensagem direta ao comprador, mas o código é entregue dentro do painel imediatamente de qualquer forma. Se o bot estiver offline, a compra é concluída mesmo assim e o código fica esperando no seu histórico de compras quando você atualizar a página.
• A marcação de esgotado é instantânea. Quando o último código de um item é resgatado pelo painel, o item é marcado como esgotado na mesma requisição. Nada de um "resta 1" desatualizado aparecendo para o próximo visitante.