🤖 Lucy Bot

Lucy é um bot Discord simples desenvolvido para a comunidade Dev's Cafe, seguindo a Metodologia KISS (Keep It Simple, Stupid). Focamos no essencial: funcionar bem sem complicação desnecessária.

Personalidade do Bot

Lucy é amigável, apesar de estar sempre cansada por causa das deadlines. Ela adora ajudar com comandos úteis, mas não gosta de complicações. Seu lema é "menos é mais"!

Ela curte um café expresso forte e tem um senso de humor sarcástico. Lucy é dedicada mesmo sendo desastrada às vezes. Ela valoriza a simplicidade e eficiência acima de tudo.

Interesses: programação, café, memes de tecnologia, e ajudar a comunidade Dev's Cafe, animes, e jogos retrô.

Coisas preferidas: Frieren, C++, café, sorvete, e engenharia de software.

Imagem:

1m 50cm de altura
Cabelos castanhos, dois rabos de cavalo longs
Olhos castanhos, com algumas olheiras
Sempre usa um moleton azul, com algumas estampas que lembram sorvete

🎯 Metodologia KISS

KISS = Keep It Simple, Stupid

Este projeto segue religiosamente o princípio KISS:

✅ Um arquivo principal: Todo o bot em index.js
✅ Sem abstrações desnecessárias: Código direto ao ponto
✅ Mínimo de dependências: Apenas o essencial
✅ Configuração simples: Só .env e pronto
✅ Docker básico: PostgreSQL + Bot, acabou
✅ Web minimalista: HTML puro que funciona
❌ Sem over-engineering: Nada de classes complexas, managers, abstrações
❌ Sem microserviços: Um bot simples não precisa de arquitetura distribuída
❌ Sem frameworks pesados: JavaScript puro é suficiente

Filosofia: Se funciona e é simples, está perfeito! 🎯

✨ Características

🎯 Funcionalidades Core:

15 comandos organizados por categoria
Sistema de XP/Levels automático
Economia virtual com daily rewards
Sistema de warnings para moderação
Help dinâmico que se adapta às permissões

🌐 Painel Administrativo:

Interface web moderna para administração
Controle total do bot via navegador
Monitoramento em tempo real
Logs visuais e relatórios automáticos
Backup/restore do banco de dados

🏗️ Arquitetura KISS:

Modular mas sem over-engineering
Database PostgreSQL com Prisma ORM
API REST simples para o painel web
Docker opcional para fácil deploy

🌐 Painel Administrativo

Lucy Bot inclui um painel web completo para administração remota:

🚀 Acesso Rápido:

npm start                    # Inicia bot + painel
# Acesse: http://localhost:3001/admin

🎮 Funcionalidades do Painel:

📊 Dashboard: Estatísticas em tempo real
🎮 Controles: Reiniciar, recarregar comandos, desligar bot
📝 Logs: Visualização de logs com auto-refresh
👥 Usuários: Gerenciamento de usuários e ações
📦 Comandos: Habilitar/desabilitar comandos
⚙️ Configurações: Alterar prefixo, status, XP
🛠️ Ferramentas: Backup, relatórios, manutenção

📱 Design Responsivo:

Interface moderna com gradientes
Funciona em desktop e mobile
Metodologia KISS aplicada ao design

🏗️ Arquitetura KISS (Keep It Simple)

O bot segue a metodologia KISS - mantendo tudo simples e direto ao ponto:

lucy/
├── index.js        # Arquivo principal - inicialização do bot
├── commands/       # Comandos simples do Discord
│   ├── ping.js
│   └── help.js
├── web/            # Painel admin minimalista
│   ├── index.html  # Interface simples
│   └── style.css   # Estilos básicos
├── prisma/         # Banco de dados
│   └── schema.prisma
└── .env            # Configurações

Princípios KISS Aplicados

Um arquivo principal: index.js contém toda a lógica do bot
Comandos simples: Cada comando é um arquivo básico sem abstrações
Web minimalista: HTML + CSS puro, sem frameworks complexos
Configuração direta: Apenas variáveis de ambiente essenciais
Sem abstrações: Código direto e fácil de entender

🚀 Instalação Simples

O que você precisa

Node.js 18+
PostgreSQL
Token do Discord Bot

Passos básicos

# 1. Clone e instale
git clone https://github.com/devscafecommunity/lucy.git
cd lucy
npm install

# 2. Configure o .env
cp .env.example .env
# Edite o .env com seu token

# 3. Configure o banco
npx prisma migrate dev

# 4. Rode o bot
npm start

Pronto! Sem complicação.

⚙️ Configuração Mínima

Arquivo .env essencial:

# Essencial
DISCORD_TOKEN=seu_token_aqui
DATABASE_URL="postgresql://user:pass@localhost:5432/lucydb"

# Opcional  
PREFIX=l~
NODE_ENV=development

É só isso que você precisa!

🗄️ Base de Dados

O projeto utiliza PostgreSQL como banco de dados principal com Prisma como ORM.

Configuração do PostgreSQL

Instale o PostgreSQL:
- Windows: Baixe do site oficial
- Linux: sudo apt-get install postgresql postgresql-contrib
- macOS: brew install postgresql

Crie o banco de dados:

CREATE DATABASE lucydb;
CREATE USER lucy WITH ENCRYPTED PASSWORD 'lucy123456789';
GRANT ALL PRIVILEGES ON DATABASE lucydb TO lucy;

Configure a URL de conexão no arquivo .env:

DATABASE_URL="postgresql://lucy:lucy123456789@localhost:5432/lucydb"

Prisma ORM

O projeto utiliza Prisma para gerenciamento do banco de dados:

Schema: Definido em prisma/schema.prisma
Migrações: Localizadas em prisma/migrations/
Seed: Scripts de população inicial em prisma/seed.js

Comandos Úteis do Prisma

# Gerar cliente Prisma
npx prisma generate

# Executar migrações
npx prisma migrate dev

# Resetar banco de dados
npx prisma migrate reset

# Visualizar banco de dados
npx prisma studio

# Criar nova migração
npx prisma migrate dev --name nome_da_migracao

Estrutura do Banco

O banco possui as seguintes tabelas principais:

guilds: Configurações dos servidores Discord
users: Dados dos usuários
members: Relação usuário-servidor
command_usage: Log de uso de comandos
moderation_actions: Ações de moderação
economy: Sistema de economia (coins, XP)

🌐 Painel de Administração

O bot inclui um painel web moderno para administração e monitoramento.

Tecnologias Utilizadas

Vite: Build tool e servidor de desenvolvimento
HTML5: Estrutura das páginas
CSS3: Estilização moderna
JavaScript ES6+: Funcionalidades interativas
Chart.js: Gráficos e dashboards

Funcionalidades do Painel

Dashboard: Visão geral de estatísticas do bot
Configuração de Servidores: Gerenciar configurações por servidor
Sistema de Moderação: Visualizar e gerenciar ações de moderação
Logs de Comandos: Monitorar uso de comandos
Estatísticas: Gráficos de atividade e uso
Gerenciamento de Usuários: Administrar usuários e permissões

Executar o Painel

# Desenvolvimento
npm run web:dev

# Build para produção
npm run web:build

# Preview da build
npm run web:preview

O painel estará disponível em http://localhost:3000 por padrão.

Estrutura do Painel Web

web/
├── src/
│   ├── components/
│   │   ├── Dashboard.js
│   │   ├── ServerConfig.js
│   │   └── UserManagement.js
│   ├── pages/
│   │   ├── index.html
│   │   ├── dashboard.html
│   │   └── settings.html
│   ├── styles/
│   │   ├── main.css
│   │   └── components.css
│   └── utils/
│       └── api.js
├── public/
│   ├── favicon.ico
│   └── assets/
├── index.html
└── vite.config.js

📁 Estrutura Simples

lucy/
├── index.js          # Bot principal - tudo em um lugar
├── commands/         # Comandos básicos
│   ├── ping.js
│   └── help.js
├── web/              # Painel simples
│   ├── index.html    # Interface básica
│   └── style.css     # Visual simples
├── prisma/           # Banco de dados
│   └── schema.prisma
├── .env              # Configurações
├── package.json      # Dependências
└── README.md         # Este arquivo

Princípio KISS: Apenas o necessário para funcionar!

🛠️ Como Desenvolver (Método KISS)

Criando um Novo Comando

Mantenha simples! Apenas crie um arquivo em /commands/:

Exemplo: commands/meucomando.js

module.exports = {
  name: 'meucomando',
  description: 'Faz algo útil',
  
  execute(message, args) {
    // Sua lógica aqui
    message.reply(`Olá ${message.author.username}!`);
  }
};

É só isso! O bot carregará automaticamente.

Adicionando Funcionalidades

Direto no index.js:

// Adicionar novo comando
client.on('messageCreate', message => {
  if (message.content === 'l~novocomando') {
    message.reply('Resposta do comando!');
  }
});

Simples e direto!

Usando o Banco de Dados

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

// Salvar dados do usuário
await prisma.users.create({
  data: {
    id: message.author.id,
    username: message.author.username
  }
});

// Buscar dados
const user = await prisma.users.findUnique({
  where: { id: message.author.id }
});

Pronto! Sem complicações.

🎯 Comandos Básicos

Comandos essenciais com prefixo l~:

l~ping - Testa se o bot está funcionando
l~help - Lista comandos disponíveis

Foco no essencial! Mais comandos são adicionados conforme a necessidade real.

🧪 Testes (Opcional)

Mantenha simples:

npm test  # Se quiser testar alguma coisa

Filosofia KISS: Teste apenas o que realmente importa.

🔧 Comandos Essenciais (KISS)

Scripts npm básicos:

npm start           # Rodar o bot
npm run dev         # Desenvolvimento com auto-reload
npm run db:setup    # Configurar banco de dados

Makefile simples:

make setup          # Instalar tudo
make start          # Iniciar com Docker
make stop           # Parar tudo
make clean          # Limpar tudo

Acabou! Sem complicação. 🎯

🤝 Contribuindo (Método KISS)

Regras simples:

Fork o projeto
Faça suas alterações (mantendo SIMPLES!)
Teste se funciona
Envie PR

Filosofia de contribuição:

✅ Se adicionar algo, pergunte: "Isso é realmente necessário?"
✅ Prefira 5 linhas diretas a 50 linhas "elegantes"
✅ Se quebrar a simplicidade, repense
❌ Não adicione abstrações "para o futuro"
❌ Não adicione dependências "por precaução"

KISS em ação: Mantenha Lucy simples e funcional! 🎯

📝 Logs e Debug

O bot possui sistema de logs detalhado:

# Logs de desenvolvimento
NODE_ENV=development npm start

# Logs de produção
NODE_ENV=production npm start

Tipos de Log

🤖 Bot Events: Inicialização e status
📦 Loading: Carregamento de componentes
⚡ Commands: Execução de comandos
❌ Errors: Erros e exceções
⚠️ Warnings: Avisos e alertas

🚀 Deploy em Produção

Lucy Bot está pronto para deploy com Docker otimizado e scripts automatizados!

⚡ Deploy Rápido

1. Clone e Configure:

git clone https://github.com/devscafecommunity/lucy.git
cd lucy
cp .env.example .env
# Edite .env com suas credenciais Discord

2. Deploy Automático:

# Windows
deploy.bat production

# Linux/Mac
chmod +x deploy.sh && ./deploy.sh production

3. Acesse:

🤖 Bot online no Discord
🌐 Painel Admin: http://localhost:3050

🏭 Características do Deploy

🐳 Docker Otimizado

Multi-stage build para imagens menores
Usuário não-root para segurança
Health checks automáticos
Resource limits configuráveis

🔒 Segurança em Produção

Variáveis sensíveis via environment
Rede isolada entre containers
API bind apenas no localhost
Logs rotativos automáticos

📊 Monitoramento

Health check endpoint: /api/health
Métricas de recursos em tempo real
Logs estruturados com timestamps
Restart automático em caso de falha

🛠️ Comandos Úteis

# Ver status
docker-compose -f docker-compose.prod.yml ps

# Logs em tempo real
docker-compose logs -f bot

# Restart do bot
docker-compose restart bot

# Backup do banco
docker exec lucy-postgres-prod pg_dump -U lucy lucydb > backup.sql

📚 Documentação Completa

Para guia detalhado de deploy, configuração avançada e troubleshooting:

👉 DEPLOY.md - Guia completo de produção

🐳 Docker Desenvolvimento

Para desenvolvimento local com Docker:

# Iniciar ambiente de desenvolvimento
docker-compose up -d

# Ver logs
docker-compose logs -f bot

# Parar ambiente
docker-compose down

🐛 Troubleshooting

O projeto inclui manifests completos para deploy em Kubernetes.

Pré-requisitos Kubernetes

Kubernetes 1.24+
kubectl configurado
Helm 3.0+ (opcional)
Ingress Controller (nginx-ingress)
Cert-Manager (para SSL)

Deploy Rápido

# Aplicar todos os manifests
kubectl apply -f k8s/

# Verificar status
kubectl get pods -n lucy-bot

# Ver logs
kubectl logs -f deployment/lucy-bot -n lucy-bot

Scripts npm para Kubernetes

# Deploy completo
npm run k8s:apply

# Remover deployment
npm run k8s:delete

# Ver logs do bot
npm run k8s:logs

Estrutura dos Manifests

k8s/
├── 00-namespace.yaml       # Namespace lucy-bot
├── 01-secrets.yaml         # Secrets (tokens, senhas)
├── 02-configmap.yaml       # ConfigMap (configurações)
├── 03-storage.yaml         # PVCs para PostgreSQL/Redis
├── 04-postgres.yaml        # PostgreSQL deployment
├── 05-redis.yaml           # Redis deployment
├── 06-bot.yaml             # Bot Discord deployment
├── 07-web.yaml             # Painel web + Ingress
└── 08-autoscaling.yaml     # HPA + PodDisruptionBudget

Configuração dos Secrets

# Criar secrets manualmente
kubectl create secret generic lucy-secrets \
  --from-literal=DISCORD_TOKEN="seu_token" \
  --from-literal=DATABASE_URL="postgresql://..." \
  --from-literal=JWT_SECRET="seu_secret" \
  -n lucy-bot

# Ou usar arquivo
echo -n "seu_token" | base64
# Cole o resultado no 01-secrets.yaml

Scaling e High Availability

Horizontal Pod Autoscaler (HPA)

# Configurado em 08-autoscaling.yaml
spec:
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        averageUtilization: 70

Pod Disruption Budget

spec:
  minAvailable: 1  # Sempre manter pelo menos 1 pod ativo

Ingress e SSL

# 07-web.yaml
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - lucy.seudominio.com
    secretName: lucy-tls

Monitoring com Prometheus

# Adicionar labels para monitoring
metadata:
  labels:
    app: lucy-bot
    version: v1.0.0
    component: discord-bot

Backup do Banco de Dados

# CronJob para backup automático
apiVersion: batch/v1
kind: CronJob
metadata:
  name: postgres-backup
spec:
  schedule: "0 2 * * *"  # Todo dia às 2h
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: postgres-backup
            image: postgres:15-alpine
            command:
            - /bin/bash
            - -c
            - pg_dump $DATABASE_URL > /backup/backup-$(date +%Y%m%d-%H%M%S).sql

�🐛 Troubleshooting

Bot não inicia

Verifique se o token está correto no .env
Confirme se o PostgreSQL está rodando
Verifique se as migrações foram executadas
Confirme se as permissões do bot estão configuradas

Painel Web não carrega

Verifique se a porta 3000 está disponível
Confirme se as variáveis de ambiente estão configuradas
Execute npm run web:build para garantir build atualizada

Erro de conexão com banco

Verifique se o PostgreSQL está rodando
Confirme se a DATABASE_URL está correta
Execute npx prisma migrate dev para atualizar schema

Comandos não funcionam

Verifique se o prefixo está correto (padrão: l~)
Confirme se o bot tem permissões necessárias no servidor
Verifique os logs para erros específicos

📋 Roadmap

✅ Concluído

Arquitetura modular básica
Sistema de comandos por prefixo
Integração com PostgreSQL + Prisma
Painel de administração web
Testes unitários com Jest

� Em Desenvolvimento

Sistema de economia completo
Sistema de níveis e XP
Comandos de moderação avançados
Dashboard com gráficos em tempo real
API REST para o painel

🔮 Planejado

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👥 Equipe

Dev's Cafe Community - Desenvolvimento e manutenção

🤝 Contribuições

Contribuições são sempre bem-vindas! Veja CONTRIBUTING.md para:

Como configurar o ambiente de desenvolvimento
Padrões de código e testes
Como submeter pull requests
Diretrizes da comunidade

Para mais informações ou dúvidas, entre em contato com a comunidade Dev's Cafe!

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
api		api
commands		commands
docs		docs
events		events
handlers		handlers
prisma		prisma
utils		utils
web		web
.env.example		.env.example
.env.production		.env.production
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOY.md		DEPLOY.md
DEPLOY_GUIDE.md		DEPLOY_GUIDE.md
DEPLOY_IMPROVEMENTS.md		DEPLOY_IMPROVEMENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
cleanup-docker.bat		cleanup-docker.bat
cleanup-docker.sh		cleanup-docker.sh
deploy.bat		deploy.bat
deploy.ps1		deploy.ps1
deploy.sh		deploy.sh
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
yarn.lock		yarn.lock

License

devscafecommunity/lucy

Folders and files

Latest commit

History

Repository files navigation