Sistema de Roles

🎭 Sistema de Roles

Sistema completo para la gestión automática de roles y roles por reacción en tu servidor.

✨ Características Principales

🎯 Roles por Reacción

• Mensajes con reacciones para obtener roles
• Panel visual con botones interactivos
• Configuración múltiple por servidor
• Roles exclusivos o acumulativos

🤖 Roles Automáticos

• Roles por nivel de XP
• Roles de bienvenida para nuevos miembros
• Roles temporales con expiración
• Condiciones personalizables

🛠️ Gestión Avanzada

• Panel de configuración intuitivo
• Vista previa en tiempo real
• Logs de asignación de roles
• Compatibilidad con jerarquías

🚀 Configuración de Roles por Reacción

Comando Principal

/setup-roles

Proceso de Configuración

1. Crear Mensaje Base

   • Título personalizable
   • Descripción con instrucciones
   • Color del embed configurable

2. Agregar Roles

   • Seleccionar rol del servidor
   • Elegir emoji (personalizado o unicode)
   • Descripción del rol
   • Configurar exclusividad

3. Configurar Comportamiento

   • Roles mutuamente exclusivos
   • Límite de roles por usuario
   • Requisitos previos

Ejemplo de Panel

🎭 Selecciona tus Roles

Reacciona con los emojis para obtener/quitar roles:

🎮 Gamer - Acceso a canales de juegos
🎨 Artista - Comparte tu arte en #galería
📚 Estudiante - Recursos educativos
🎵 Músico - Canales de música y jam sessions
💻 Developer - Charlas de programación

⚠️ Solo puedes tener un rol de categoría a la vez

🤖 Roles Automáticos

Por Nivel de XP

// Configuración automática por nivel
const autoRoles = [
  { level: 5, roleId: "123456", name: "Miembro Activo" },
  { level: 10, roleId: "789012", name: "Veterano" },
  { level: 25, roleId: "345678", name: "Experto" },
  { level: 50, roleId: "901234", name: "Leyenda" }
]

Para Nuevos Miembros

• Rol de bienvenida automático al unirse
• Verificación requerida para roles adicionales
• Tiempo de espera configurable

Roles Temporales

• Duración específica (horas, días, semanas)
• Auto-removal cuando expira
• Notificaciones de expiración

🎨 Tipos de Configuración

Roles Exclusivos

🏷️ Elige tu Equipo (Solo uno)

🔴 Equipo Rojo
🔵 Equipo Azul
🟢 Equipo Verde
🟡 Equipo Amarillo

⚠️ Solo puedes estar en un equipo

Roles Acumulativos

🎯 Intereses (Múltiples opciones)

🎮 Gaming
🎬 Películas
📚 Libros
🎵 Música
⚽ Deportes
🍕 Comida

✅ Puedes seleccionar todos los que quieras

Roles con Requisitos

🌟 Roles Especiales

💎 VIP - Requiere nivel 10
👑 Premium - Requiere rol @Miembro
🎖️ Moderador Trainee - Requiere aplicación

❗ Algunos roles tienen requisitos especiales

🔧 Panel de Configuración

Opciones Principales

1. 📝 Crear Panel - Nuevo panel de roles
2. ✏️ Editar Panel - Modificar panel existente
3. ➕ Agregar Rol - Añadir nuevo rol al panel
4. ➖ Quitar Rol - Remover rol del panel
5. 🎨 Personalizar - Cambiar colores y diseño
6. 📊 Estadísticas - Ver uso de roles

Configuración Avanzada

{
  "exclusiveGroups": [
    {
      "name": "Equipos",
      "roles": ["rojo", "azul", "verde"],
      "maxSelection": 1
    }
  ],
  "requirements": {
    "vip": {
      "level": 10,
      "requiredRoles": ["miembro"]
    }
  },
  "autoRemove": {
    "temporal": {
      "duration": "7d",
      "notify": true
    }
  }
}

📊 Gestión y Estadísticas

Panel de Administración

🎭 Gestión de Roles - Panel #1

📈 Estadísticas:
├─ Usuarios con roles: 234/450
├─ Rol más popular: 🎮 Gamer (89 usuarios)
├─ Interacciones hoy: 23
└─ Último uso: hace 5 minutos

🔧 Acciones Rápidas:
├─ ✏️ Editar panel
├─ 📊 Ver estadísticas detalladas
├─ 🗑️ Eliminar panel
└─ 📋 Duplicar configuración

Logs de Actividad

[ROLES] Usuario @Juan obtuvo rol @Gamer
[ROLES] Usuario @María perdió rol @Estudiante
[ROLES] Usuario @Pedro intentó obtener @VIP (sin requisitos)
[ROLES] Rol @Temporal expiró para @Ana

🛡️ Permisos y Seguridad

Jerarquía de Roles

• El bot debe estar por encima de los roles que gestiona
• Verificación automática de permisos
• Protección contra escalada de privilegios

Validaciones

// Verificaciones automáticas
const validations = {
  roleHierarchy: true,      // Bot sobre rol gestionado
  userPermissions: true,    // Usuario puede obtener rol
  roleConflicts: true,      // No conflictos con otros roles
  serverLimits: true        // Límites del servidor
}

🎯 Casos de Uso Comunes

Servidor de Gaming

🎮 Roles de Juegos

🔫 Call of Duty
⚔️ League of Legends
🏰 Minecraft
🚗 Rocket League
👑 Valorant

Obtén acceso a canales específicos de cada juego

Servidor Educativo

📚 Áreas de Estudio

🧮 Matemáticas
🧪 Ciencias
💻 Programación
🎨 Arte
📖 Literatura

Cada área tiene recursos y canales dedicados

Servidor de Comunidad

🌍 Ubicación Geográfica

🇪🇸 España
🇲🇽 México
🇺🇸 Estados Unidos
🇦🇷 Argentina
🌎 Otros países

Conecta con personas de tu región

🔮 Funcionalidades Avanzadas

Roles Dinámicos (Próximamente)

• Roles por actividad en el servidor
• Roles estacionales que cambian automáticamente
• Roles por logros específicos

Integración con Otros Sistemas

• Roles por nivel de XP automáticos
• Roles de tickets para staff temporal
• Roles de eventos para organizadores

API de Roles (En Desarrollo)

// Gestión programática de roles
await roleManager.addRole(userId, roleId, {
  reason: "Automatic assignment",
  duration: "7d",
  conditions: ["level >= 10"]
});

🔍 Troubleshooting

Problemas Comunes

El bot no puede asignar roles

• Causa: Jerarquía incorrecta
• Solución: Mover el rol del bot por encima de los roles gestionados

Los usuarios no pueden reaccionar

• Causa: Permisos del canal
• Solución: Dar permisos de “Agregar Reacciones” en el canal

Roles no se quitan automáticamente

• Causa: Configuración de exclusividad
• Solución: Verificar configuración en /setup-roles

Comandos de Debug

/role-debug @usuario

Muestra información detallada sobre los roles de un usuario y posibles problemas.

📊 Base de Datos

Estructura de Configuración

{
  "rolePanels": [
    {
      "id": "panel_1",
      "channelId": "123456789",
      "messageId": "987654321",
      "title": "Selecciona tus Roles",
      "description": "Reacciona para obtener roles",
      "color": "#5865F2",
      "roles": [
        {
          "roleId": "555666777",
          "emoji": "🎮",
          "name": "Gamer",
          "description": "Acceso a canales de juegos"
        }
      ],
      "settings": {
        "exclusive": false,
        "maxRoles": 5,
        "requirements": {}
      }
    }
  ]
}

🎯 Mejores Prácticas

Diseño de Paneles

1. Mantén la claridad - Descripciones concisas
2. Usa emojis relevantes - Fácil identificación
3. Agrupa roles relacionados - Mejor organización
4. Limita las opciones - Evita sobrecarga

Gestión de Roles

1. Establece jerarquías claras
2. Documenta los requisitos
3. Revisa regularmente la configuración
4. Monitorea el uso de los roles

Seguridad

1. No otorgues permisos peligrosos automáticamente
2. Verifica requisitos antes de asignar roles especiales
3. Mantén logs de todas las asignaciones
4. Revisa periódicamente los roles asignados

---

El sistema de roles está completamente integrado con el sistema de niveles y moderación del bot, permitiendo una gestión integral de tu servidor.