Nero Discord Bot

Bot Discord modular multi-tenant com capacidades de IA, loja automatizada, whitelist Roblox e sistema de organizações.

---

Visao Geral

Nero e uma plataforma SaaS de bot Discord pronta para producao, projetada para servir multiplas comunidades simultaneamente com isolamento completo de dados. Combina IA generativa (Google Gemini), moderacao automatica, loja com pagamentos Pix, whitelist Roblox, sistema de organizacoes/clas e monitoramento completo.

Destaques

• Multi-tenant com isolamento real — Schema-per-tenant no PostgreSQL + namespacing no Redis
• IA com Gemini 2.0 — Chat contextual, analise de imagens, moderacao inteligente, OCR
• 50+ comandos prontos — Moderacao, utilidade, IA, tickets, loja, Roblox, organizacoes, broadcast
• Loja automatizada — Catalogo de produtos, pagamento Pix (Mercado Pago), entrega automatica, relatorios de vendas
• Whitelist Roblox — Verificacao de contas, anti-alt, vinculacao Discord↔Roblox
• Organizacoes/Clas — Criar orgs, hierarquia de ranks, canais e cargos automaticos
• Broadcast/Divulgacoes — Mensagens automaticas com cron, templates, rotacao de produtos
• Moderacao com contexto — Analise contextual que diferencia educacao de violacao
• Circuit Breaker + Retry — Resiliencia em todas as chamadas externas
• Monitoramento completo — Prometheus, Grafana, Elasticsearch, alertas automaticos
• Dashboard Web — Painel Next.js para gestao de tenants e configuracoes
• 100% TypeScript — Tipagem estrita em todo o projeto

---

Stack Tecnologica

Camada	Tecnologia
Runtime	Node.js 20+, TypeScript 5.3
Discord	discord.js 14
IA	Google Gemini 2.0 Flash
Banco de Dados	PostgreSQL 16 (schema-per-tenant)
Cache/Filas	Redis 7 (opcional, usa memoria por padrao)
Pagamentos	Mercado Pago (Pix)
Monitoramento	Prometheus + Grafana + Elasticsearch
Testes	Jest + fast-check (property-based)
Dashboard	Next.js 15
Infra	Docker Compose (opcional)

---

Arquitetura

nero-discord-bot/
├── src/
│   ├── ai/               # Servico de IA (Gemini 2.0)
│   ├── analytics/         # Engine de analytics e relatorios
│   ├── audit/             # Sistema de auditoria
│   ├── backup/            # Backup automatizado
│   ├── broadcast/         # Divulgacoes automaticas + templates
│   │   └── commands/      # divulgar, divulgacoes, pausar, retomar, template
│   ├── commands/          # Handler de comandos + implementacoes
│   │   └── implementations/
│   │       ├── admin/     # slowmode, lock, unlock, announce, nick
│   │       ├── ai/        # ask, analyze, ocr, document
│   │       ├── fun/       # 8ball, coinflip, dice, meme, poll
│   │       ├── info/      # serverinfo, userinfo, avatar, banner, roleinfo
│   │       ├── moderation/# ban, kick, mute, warn, clear
│   │       ├── scheduling/# schedule, schedules, cancel
│   │       ├── tickets/   # ticket, close, add, remove
│   │       └── utility/   # help, ping, info, config
│   ├── config/            # Configuracoes tipadas
│   ├── context/           # Analise contextual de mensagens
│   ├── core/              # BotCore, ModuleManager, BaseModule
│   ├── database/          # PostgreSQL + Redis clients + migrations
│   ├── documents/         # Processamento de documentos (PDF)
│   ├── health/            # Health checks
│   ├── moderation/        # Engine de moderacao + content filter
│   ├── monitoring/        # Prometheus + Elasticsearch exporters
│   ├── ocr/               # OCR para imagens
│   ├── orgs/              # Sistema de organizacoes/clas
│   │   └── commands/      # org (create, join, leave, kick, promote, demote, etc.)
│   ├── permissions/       # Sistema de permissoes granular
│   ├── plugins/           # Sistema de plugins
│   ├── resilience/        # Circuit breaker, retry, bulkhead
│   ├── roblox/            # Whitelist Roblox + anti-alt
│   │   └── commands/      # connect, wl, unwl, listwl
│   ├── scheduler/         # Agendamento de tarefas (cron)
│   ├── scripts/           # Scripts utilitarios (verify-setup)
│   ├── store/             # Loja automatizada
│   │   └── commands/      # loja, comprar, vendas, addproduto, removeproduto, estoque
│   ├── tickets/           # Sistema de tickets de suporte
│   ├── types/             # Tipos TypeScript compartilhados
│   ├── usage/             # Rastreamento de uso de API
│   ├── utils/             # Logger (Winston)
│   ├── webhooks/          # Webhooks para integracoes externas
│   └── welcome/           # Sistema de boas-vindas
├── dashboard/             # Painel web Next.js
├── monitoring/            # Configs Prometheus/Grafana
├── database/              # Scripts SQL de inicializacao
├── tests/                 # Testes unitarios e integracao
├── docs/                  # Documentacao tecnica
└── docker-compose.yml     # Infra completa (Postgres, Redis, Prometheus, Grafana, ES)

---

Comandos (50+)

Utilidade

Comando	Descricao
!ping	Latencia do bot e WebSocket
!help [cmd]	Lista de comandos ou ajuda detalhada
!info	Informacoes do bot
!config	Configuracao atual do bot

Moderacao

Comando	Descricao
!ban <user> [reason]	Banir usuario com DM e log
!kick <user> [reason]	Expulsar usuario
!mute <user> [duration]	Silenciar usuario
!warn <user> [reason]	Advertir usuario
!clear <amount>	Limpar mensagens do canal

Admin

Comando	Descricao
!slowmode <seconds>	Definir slowmode (0 a 21600s)
!lock [reason]	Trancar canal
!unlock	Destrancar canal
!announce <#canal> <msg>	Enviar anuncio embed
!nick <user> <nome>	Alterar apelido

Informacoes

Comando	Descricao
!serverinfo	Info detalhada do servidor
!userinfo [user]	Info do usuario (roles, datas, boost)
!avatar [user]	Avatar em alta resolucao
!banner [user]	Banner do perfil
!roleinfo <role>	Info da role (membros, perms, cor)

Diversao

Comando	Descricao
!8ball <pergunta>	Bola magica 8
!coinflip	Cara ou coroa
!dice [NdS]	Rolar dados (ex: 2d6, 1d20)
!meme [template]	Gerar meme texto
!poll Q | Op1 | Op2	Criar enquete com reacoes

IA (Gemini 2.0)

Comando	Descricao
!ask <pergunta>	Chat com IA contextual
!analyze <imagem>	Analise de imagem com Vision
!ocr <imagem>	Extrair texto de imagem
!document <arquivo>	Analisar documento PDF

Tickets

Comando	Descricao
!ticket <cat> <msg>	Abrir ticket de suporte
!close [reason]	Fechar ticket
!add <user>	Adicionar usuario ao ticket
!remove <user>	Remover usuario do ticket

Agendamento

Comando	Descricao
!schedule <cron> <msg>	Agendar mensagem recorrente
!schedules	Listar agendamentos
!cancel <id>	Cancelar agendamento

🛒 Loja Automatizada

Comando	Descricao
!loja [categoria]	Exibir catalogo de produtos com botoes de compra
!comprar <produto> [qtd]	Iniciar compra (gera Pix automaticamente)
!addproduto <nome> <preco> <estoque> <tipo> <conteudo>	Adicionar produto (Admin)
!removeproduto <id ou nome>	Remover/desativar produto (Admin)
!estoque [id]	Ver estoque geral ou de um produto (Admin)
!estoque set <id> <qtd>	Definir estoque de um produto (Admin)
!estoque add <id> <itens...>	Adicionar itens ao estoque tipo texto (Admin)
!vendas [periodo]	Relatorio de vendas: dia, semana, mes, ano, total (Admin)

🎮 Whitelist Roblox

Comando	Descricao
!connect <roblox_user>	Verificar/vincular conta Roblox ao Discord
!wl @user <roblox_user>	Forcar whitelist (Admin, ignora anti-alt)
!unwl [@user]	Remover verificacao (propria ou de outro, Admin)
!listwl [pagina]	Listar usuarios verificados com paginacao (Admin)

📢 Broadcast / Divulgacoes

Comando	Descricao
!divulgar <#canal> <cron> <msg ou template>	Criar divulgacao automatica (Admin)
!divulgacoes	Listar todas as divulgacoes ativas/pausadas (Admin)
!pausar <id>	Pausar divulgacao (Admin)
!retomar <id>	Retomar divulgacao pausada (Admin)
!template [list|view|preview|delete] [nome]	Gerenciar templates de divulgacao (Admin)

🏴 Organizacoes / Clas

Comando	Descricao
!org create <nome> <tag>	Criar organizacao
!org join <nome>	Entrar em uma org
!org leave	Sair da org atual
!org kick @user	Expulsar membro
!org promote @user	Promover membro
!org demote @user	Rebaixar membro
!org info [nome]	Ver info da org
!org members [nome]	Ver membros da org
!org list	Listar todas as orgs do servidor
!org logs	Historico de acoes (lider/co-lider)
!org delete	Dissolver org (lider)

---

Funcionalidades Tecnicas

Inteligencia Artificial

• Chat contextual com historico de conversas
• Analise de imagens com Gemini Vision
• OCR para extracao de texto de imagens
• Analise de PDFs com processamento de documentos
• Personalidade configuravel (tom, idioma, instrucoes)
• Circuit breaker para protecao contra falhas da API

Loja Automatizada

• Catalogo de produtos com embeds interativos e botoes de compra
• Pagamento Pix via Mercado Pago com QR code automatico
• Entrega automatica por tipo: text (codigos/chaves), file (URLs), role (cargos Discord), webhook
• Gerenciamento de estoque com alertas de estoque baixo
• Tickets de venda com canal privado para cada compra
• Assistente IA nas vendas (Gemini responde compradores no ticket)
• Relatorios completos — faturamento, top produtos, vendas por dia, taxa de conversao
• Webhook server para notificacoes de pagamento do Mercado Pago

Whitelist Roblox

• Verificacao self-service — usuarios vinculam sua conta com !connect
• Anti-alt completo — idade minima de conta Roblox/Discord, limite de contas por usuario, bloqueio de banidos
• Cargo automatico — atribui cargo de "verificado" e remove "nao verificado"
• Admin tools — force-whitelist, unlink, listagem com paginacao
• Cross-server — configuracao de compartilhamento entre servidores

Organizacoes / Clas

• Hierarquia de ranks — Lider, Co-lider, Oficial, Membro, Recruta
• Canais e cargos automaticos — cria canal de texto e cargo da org
• Sistema de pontos e niveis — progressao baseada em atividade
• Logs de auditoria — historico de acoes (kick, promote, demote, etc.)
• Limites configuraveis — maximo de membros por org

Broadcast / Divulgacoes

• Cron scheduling — agende mensagens com qualquer expressao cron
• Templates pre-definidos e personalizados — com variaveis dinamicas
• Rotacao de produtos — templates da loja alternam produtos automaticamente
• Controle total — pausar, retomar, listar, preview de templates

Moderacao Automatica

• Analise contextual — diferencia educacao de violacao real
• Content filter com blacklist/whitelist
• Acoes automaticas: warn, delete, mute, kick, ban
• 3 niveis de sensibilidade: low, medium, high

Infraestrutura

• Sem Docker necessario — cache em memoria + banco na nuvem
• Circuit Breaker com estados CLOSED/OPEN/HALF-OPEN
• Graceful shutdown em SIGTERM/SIGINT
• Rate limiting por usuario/comando/canal
• Sistema de permissoes granular com hierarquia de roles
• Deploy pronto — suporte a Railway (railway.json incluso)

---

Inicio Rapido

Pre-requisitos

• Node.js 20+
• PostgreSQL (cloud gratuito: Supabase, Neon, ou Railway)
• Chave de API do Google Gemini (https://aistudio.google.com/apikey)
• Token de bot Discord (https://discord.com/developers/applications)

Docker NAO e necessario! O bot usa cache em memoria e suporta banco de dados na nuvem.

Instalacao (sem Docker)

# 1. Instale as dependencias
npm install

# 2. Configure as variaveis de ambiente
cp .env.example .env
# Edite .env com suas credenciais (veja abaixo)

# 3. Execute as migrations
npm run db:migrate

# 4. Inicie o bot
npm run dev

Instalacao rapida (scripts automaticos)

# Windows
install.bat

# Linux/macOS
chmod +x install.sh && ./install.sh

Configuracao rapida do banco de dados

Opcao A — Supabase (gratuito, recomendado):

1. Crie um projeto em https://supabase.com
2. Va em Settings > Database > Connection string (URI)
3. No .env:

DATABASE_URL=postgresql://postgres:[SUA-SENHA]@db.[SEU-PROJETO].supabase.co:5432/postgres
DATABASE_SSL=true
REDIS_ENABLED=false

Opcao B — Neon (gratuito):

1. Crie um projeto em https://neon.tech
2. Copie a connection string
3. No .env:

DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/dbname?sslmode=require
DATABASE_SSL=true
REDIS_ENABLED=false

---

Scripts Disponiveis

# Desenvolvimento
npm run dev          # Hot-reload com tsx watch
npm run build        # Compilar TypeScript
npm start            # Iniciar em producao

# Qualidade
npm run lint         # ESLint
npm run format       # Prettier
npm test             # Jest
npm run test:watch   # Testes em modo watch

# Infraestrutura
npm run db:migrate   # Executar migrations
npm run verify       # Verificar setup
npm run docs         # Gerar documentacao TypeDoc
npm run docs:serve   # Servir documentacao na porta 8080

---

Configuracao

Todas as configuracoes sao via variaveis de ambiente. Veja .env.example para referencia completa.

Essenciais

Variavel	Descricao	Obrigatorio
DISCORD_TOKEN	Token do bot Discord	Sim
DISCORD_PREFIX	Prefixo dos comandos (padrao: !)	Nao
GEMINI_API_KEY	Chave API do Google Gemini	Sim
JWT_SECRET	Secret para tokens JWT	Sim

Banco de Dados

Variavel	Descricao	Obrigatorio
DATABASE_URL	Connection string PostgreSQL (cloud)	Sim*
DATABASE_SSL	Habilitar SSL (true para cloud)	Nao
DATABASE_HOST	Host do PostgreSQL (local)	Sim*
DATABASE_PORT	Porta do PostgreSQL (padrao: 5432)	Nao
DATABASE_NAME	Nome do banco	Nao
DATABASE_USER	Usuario do banco	Nao
DATABASE_PASSWORD	Senha do banco	Nao

*Use DATABASE_URL OU DATABASE_HOST/PORT/NAME/USER/PASSWORD — nao ambos.

Cache

Variavel	Descricao	Obrigatorio
REDIS_ENABLED	Habilitar Redis (false = usa memoria)	Nao
REDIS_HOST	Host do Redis	Nao
REDIS_PORT	Porta do Redis	Nao
REDIS_PASSWORD	Senha do Redis	Nao

Loja Automatizada

Variavel	Descricao	Obrigatorio
STORE_ENABLED	Habilitar modulo da loja (padrao: true)	Nao
MERCADOPAGO_ACCESS_TOKEN	Token de acesso Mercado Pago	Para pagamentos
NEXT_PUBLIC_MERCADOPAGO_PUBLIC_KEY	Chave publica Mercado Pago	Para pagamentos
WEBHOOK_BASE_URL	URL publica para webhooks de pagamento	Para pagamentos
WEBHOOK_PORT	Porta do servidor de webhooks (padrao: 3001)	Nao
PAYMENT_EXPIRATION_MINUTES	Expiracao do Pix em minutos (padrao: 30)	Nao
AUTO_CLOSE_TICKET_MINUTES	Fechar ticket apos pagamento (padrao: 5)	Nao
MAX_PENDING_SALES_PER_USER	Maximo de compras pendentes por usuario (padrao: 3)	Nao
AI_SALES_ASSISTANT	IA responde compradores no ticket (padrao: true)	Nao
SALE_TICKET_CATEGORY	Nome da categoria de tickets de venda	Nao
CURRENCY_SYMBOL	Simbolo da moeda (padrao: R$)	Nao

Whitelist Roblox

Variavel	Descricao	Obrigatorio
ROBLOX_ENABLED	Habilitar modulo Roblox (padrao: true)	Nao
ROBLOX_VERIFIED_ROLE_ID	ID do cargo de verificado	Para whitelist
ROBLOX_UNVERIFIED_ROLE_ID	ID do cargo a remover apos verificacao	Nao
ROBLOX_VERIFICATION_CHANNEL_ID	Canal do painel de verificacao	Nao
ROBLOX_LOG_CHANNEL_ID	Canal para logs de verificacao	Nao
ROBLOX_MIN_ACCOUNT_AGE_DAYS	Idade minima da conta Roblox (padrao: 30)	Nao
ROBLOX_MIN_DISCORD_AGE_DAYS	Idade minima da conta Discord (padrao: 7)	Nao
ROBLOX_MAX_ACCOUNTS_PER_DISCORD	Max contas Roblox por Discord (padrao: 1)	Nao
ROBLOX_MAX_DISCORD_PER_ROBLOX	Max contas Discord por Roblox (padrao: 1)	Nao
ROBLOX_ALLOW_CROSS_SERVER	Permitir verificacao cross-server	Nao
ROBLOX_BLOCK_BANNED	Bloquear contas Roblox banidas	Nao

Aplicacao e Monitoramento

Variavel	Descricao	Obrigatorio
NODE_ENV	Ambiente (development/production)	Nao
PORT	Porta da aplicacao (padrao: 3000)	Nao
LOG_LEVEL	Nivel de log (padrao: info)	Nao
ELASTICSEARCH_NODE	URL do Elasticsearch (requer Docker)	Nao

---

Testes

# Todos os testes
npm test

# Com cobertura
npm test -- --coverage

# Testes especificos
npm test -- path/to/test

# Modo watch
npm run test:watch

---

Docker Compose (opcional)

Se voce preferir rodar tudo localmente com Docker, o docker-compose.yml esta disponivel:

docker-compose up -d

Inclui: PostgreSQL 16, Redis 7, Prometheus, Grafana, Elasticsearch e exporters.

---

Deploy

Railway (recomendado)

O projeto inclui railway.json pronto para deploy:

1. Conecte seu repositorio ao Railway
2. Configure as variaveis de ambiente
3. Deploy automatico

Outros

O bot pode rodar em qualquer plataforma Node.js: Render, Fly.io, VPS, etc.

---

Documentacao

Documento	Descricao
ARCHITECTURE.md	Arquitetura detalhada
QUICKSTART.md	Guia de inicio rapido
COMMANDS.md	Documentacao completa de comandos
CONTRIBUTING.md	Como contribuir
MONITORING-INTEGRATION.md	Integracao de monitoramento
docs/	Documentacao tecnica completa
dashboard/README.md	Dashboard web

---

Licenca

MIT — Veja LICENSE para detalhes.