Kuby/README.md

# 🤖 Kuby - Bot Discord Multi-Fonctions

Kuby est un bot Discord complet développé en Python avec `discord.py`. Il offre une suite complète d'outils de modération, de sécurité, de sauvegarde et de gestion communautaire.

---

## 📋 Table des Matières

1. [✨ Fonctionnalités](#-fonctionnalités)
2. [🛠️ Installation](#️-installation)
3. [⚙️ Configuration](#️-configuration)
4. [📖 Commandes](#-commandes)
5. [🏗️ Architecture](#️-architecture)
6. [🔐 Système de Permissions](#-système-de-permissions)
7. [📊 Système de Logs](#-système-de-logs)
8. [🧪 Tests](#-tests)

---

## ✨ Fonctionnalités

### 🛡️ Sécurité
- **Anti-Raid** : Protection contre les attaques de raid
- **Anti-Spam** : Détection et sanction du spam (5 msgs/5s par défaut)
- **Anti-Link** : Blocage des liens non autorisés (discord.gg, http, https, www)
- **Anti-Mention** : Protection contre les mentions abusives
- **Anti-Nuke** : Protection contre la suppression massive de salons/ rôles

### 💾 Sauvegardes
- **Backup Complet** : Sauvegarde rôles, catégories, salons, membres
- **Export des Messages** : Option pour inclure l'historique des messages
- **Archives ZIP** : Fichiers compressés pour faciliter le stockage

### 🎫 Système de Tickets
- Création de tickets via bouton interactif
- Gestion des permissions par rôle staff
- Logs des actions
- Réouverture et suppression

### 👋 Bienvenue / Au Revoir
- Images de bienvenue personnalisées avec avatar
- Messages DM automatisés
- Images d'au revoir avec temps de présence

### 📝 Logs & Monitoring
- Logs des événements membres (join/leave)
- Logs des messages (édit/ suppression)
- Logs vocaux (connexion/ déconnection)
- Restauration des rôles à la reconnexion

### 🔒 Gestion des Utilisateurs
- **Whitelist** : Liste d'utilisateurs autorisés à utiliser les commandes sensibles
- **Blacklist Réseau** : Système de blacklist global pour tous les serveurs partenaires

### 🎮 Commandes Fun
- Commandes variées pour animer le serveur

---

## 🛠️ Installation

### Prérequis

- Python 3.10 ou supérieur
- pip (gestionnaire de paquets Python)

### 1. Cloner le Repository

```bash
git clone <url-du-repo>
cd backup_kuby
```

### 2. Créer un Environnement Virtuel (Recommandé)

```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
.\venv\Scripts\activate   # Windows
```

### 3. Installer les Dépendances

```bash
pip install -r requirements.txt
```

Les dépendances incluent :
- `discord.py>=2.3.0` - Framework Discord
- `python-dotenv>=1.0.0` - Variables d'environnement
- `PIL` - Traitement d'images (pour les images de bienvenue)
- `aiohttp` - Requêtes HTTP asynchrones

---

## ⚙️ Configuration

### 1. Créer un Fichier `.env`

Créez un fichier `.env` à la racine du projet avec le contenu suivant :

```env
# Token de votre bot Discord
DISCORD_TOKEN=your_bot_token_here

# ID de l'application Discord (optionnel)
APPLICATION_ID=your_application_id_here
```

### 2. Obtenir le Token du Bot

1. Allez sur le [Discord Developer Portal](https://discord.com/developers/applications)
2. Créez une nouvelle application
3. Allez dans l'onglet "Bot"
4. Créez un bot et copiez le token
5. Activez les intents nécessaires :
   - `SERVER MEMBERS INTENT`
   - `MESSAGE CONTENT INTENT`
   - `VOICE STATES`

### 3. Inviter le Bot sur votre Serveur

Générez un lien d'invitation avec les permissions suivantes :
- `Administrator` (recommandé pour toutes les fonctionnalités)

---

## 📖 Commandes

### 🔐 Sécurité

| Commande | Description |
|----------|-------------|
| `/security` | Ouvrir le panneau de configuration de sécurité |

Le panneau de sécurité permet de configurer :
- **Anti-Raid** : Protection contre les raids
- **Anti-Spam** : Bloque le spam excessif
- **Anti-Link** : Interdit les liens non autorisés
- **Anti-Mention** : Protection contre les mentions de masse
- **Anti-Nuke** : Protection contre la suppression de salons/rôles
- **Logs** : Activer/désactiver les logs

### 💾 Sauvegardes

| Commande | Description |
|----------|-------------|
| `/backup create` | Créer une sauvegarde complète du serveur |
| `/backup list` | Lister les sauvegardes disponibles |

Options pour `/backup create` :
- `save_messages` : Inclure les messages (défaut: True)
- `privacy_notice` : Afficher un avertissement public (défaut: True)
- `message_limit_per_channel` : Limite de messages par salon (défaut: 10000)

### 🎫 Tickets

| Commande | Description |
|----------|-------------|
| `/ticket setup` | Configurer le système de tickets |
| `/ticket panel [channel]` | Créer un panneau de création de tickets |

**Fonctionnement :**
1. Les utilisateurs cliquent sur "Créer un ticket"
2. Un salon privé est créé automatiquement
3. Les membres staff peuvent fermer/rouvrir

### 👋 Bienvenue / Au Revoir

| Commande | Description |
|----------|-------------|
| `/setwelcome <channel> [message_dm]` | Configurer le salon de bienvenue et message DM |
| `/setgoodbye <channel>` | Configurer le salon d'au revoir |

**Variables pour les messages DM :**
- `{username}` - Nom d'utilisateur
- `{servername}` - Nom du serveur
- `{member_count}` - Nombre de membres

### 👥 Whitelist

| Commande | Description |
|----------|-------------|
| `/whitelist ajouter <utilisateur>` | Ajouter un utilisateur à la whitelist |
| `/whitelist retirer <utilisateur>` | Retirer un utilisateur de la whitelist |
| `/whitelist liste` | Lister les utilisateurs whitelistés |

### 🔒 Blacklist (Agents uniquement)

| Commande | Description |
|----------|-------------|
| `/blacklist <utilisateur> [raison]` | Blacklister un utilisateur du réseau |
| `/unblacklist <utilisateur>` | Retirer de la blacklist |

---

## 🏗️ Architecture

```
backup_kuby/
├── bot.py                    # Point d'entrée principal du bot
├── kuby.py                   # Script de lancement alternatif
├── requirements.txt          # Dépendances Python
├── .env                      # Variables d'environnement (à créer)
├── README.md                 # Documentation
│
├── commandes/                # Cog Discord (modules de commandes)
│   ├── whitelist.py         # Gestion de la whitelist
│   ├── whitelist_monitor.py # Monitoring whitelist
│   ├── security.py          # Panneau de sécurité
│   ├── ticket.py            # Système de tickets
│   ├── backup.py            # Sauvegardes serveur
│   ├── blacklist.py         # Blacklist réseau
│   ├── welcome.py           # Messages de bienvenue
│   ├── goodbye.py           # Messages d'au revoir
│   ├── fun.py               # Commandes fun
│   ├── snipe.py             # Commande snipe
│   ├── scan.py              # Scan de sécurité
│   ├── no_link.py           # Anti-liens basique
│   │
│   └── modules_security/    # Modules de sécurité avancés
│       ├── antispam.py      # Anti-spam & Anti-liens
│       ├── antiraid.py      # Anti-raid
│       └── logs_manager.py  # Gestion des logs
│
├── data/                    # Données et configurations
│   ├── config.db            # Base SQLite (welcome/goodbye)
│   ├── whitelist.json       # Utilisateurs whitelistés
│   ├── blacklist.json       # Utilisateurs blacklistés
│   ├── security_settings.json # Paramètres de sécurité
│   ├── agents.json          # Agents de la blacklist
│   ├── tickets_blacklist.json # Tickets blacklist
│   │
│   ├── logs/                # Logs d'événements
│   │   ├── member_events_*.json
│   │   ├── messages_*.json
│   │   └── voice_*.json
│   │
│   ├── security_backups/    # Sauvegardes serveur
│   └── member_logs/         # Historique des rôles membres
│
├── ressources/              # Ressources statiques
│   └── assets/
│
└── src/                     # Code source utilitaire
    ├── logger.py            # Système de logging
    └── advanced_logger.py   # Logging avancé & historique
```

---

## 🔐 Système de Permissions

### Whitelist

La whitelist est un système de permissions qui contrôle l'accès aux commandes sensibles. Seuls les utilisateurs whitelistés peuvent utiliser certaines commandes administratives.

**Fichiers :**
- `data/whitelist.json` - Stockage des utilisateurs whitelistés

**Gestion :**
- Les propriétaires de serveur sont automatiquement whitelistés
- Gestion via `/whitelist ajouter/retirer/liste`

### Rôles de Staff

Pour le système de tickets, les rôles staff sont définis lors de la configuration. Ces rôles ont accès aux tickets des utilisateurs.

### Permissions Requises

Le bot nécessite les permissions suivantes sur le serveur :
- `Administrator` (recommandé) OU
- `Manage Roles` - Pour la modération
- `Manage Channels` - Pour les tickets
- `Ban Members` - Pour la sécurité
- `Manage Messages` - Pour l'anti-spam
- `View Audit Log` - Pour les logs

---

## 📊 Système de Logs

### Types d'Événements Trackés

#### Événements Membres
- **Join** : Arrivée d'un nouveau membre
- **Leave** : Départ d'un membre
- **Restauration de rôles** : Les rôles sont restaurés si le membre revient

#### Événements Messages
- **Suppression** : Message supprimé (contenu, auteur, salon)
- **Édition** : Message modifié (avant/après)

#### Événements Vocaux
- **Connexion** : Arrivée dans un salon vocal
- **Déconnexion** : Départ d'un salon vocal
- **Déplacement** : Changement de salon vocal

### Fichiers de Logs

Les logs sont stockés dans `data/logs/` avec la structure suivante :
- `member_events_YYYY-MM-DD.json` - Événements membres
- `messages_YYYY-MM-DD.json` - Événements messages
- `voice_YYYY-MM-DD.json` - Événements vocaux

### Restauration des Rôles

Le système `advanced_logger.py` сохраняе l'historique des rôles des membres dans `data/member_logs/{user_id}.json`. Lorsqu'un membre rejoint à nouveau, ses rôles précédents sont automatiquement restaurés.

---

## 🧪 Tests

### Lancer le Bot

```bash
# Méthode 1 : Via kuby.py
python kuby.py

# Méthode 2 : Via bot.py (avec gestion d'erreur)
python bot.py
```

### Vérifier le Fonctionnement

1. Le bot doit apparaître en ligne sur Discord
2. Vérifiez les logs dans la console
3. Testez les commandes :
   - `/whitelist liste` - Doit fonctionner
   - `/security` - Doit ouvrir le panneau
   - `/backup create` - Doit créer une sauvegarde

### Dépannage

**Problèmes Courants :**

1. **Token manquant**
   ```
   Erreur: Token Discord non trouvé dans les variables d'environnement!
   ```
   ➡️ Vérifiez le fichier `.env`

2. **Intentions manquantes**
   ```
   discord.IntentsRequired: ...
   ```
   ➡️ Activez les intents sur le portail développeur

3. **Permissions insuffisantes**
   ```
   Je n'ai pas la permission d'exclure ce membre
   ```
   ➡️ Vérifiez la position du bot dans la hiérarchie des rôles

---

## 📝 Notes de Développement

### Structure des Cogs

Chaque module est un "Cog" Discord.py qui permet une organisation modulaire du code :

```python
class NomDuModule(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
    
    # Commandes slash
    @app_commands.command(name="commande", description="Description")
    async def ma_commande(self, interaction: discord.Interaction):
        # Logique
        pass

async def setup(bot):
    await bot.add_cog(NomDuModule(bot))
```

### Système de Logging

Le bot utilise un système de logging personnalisé via `src/logger.py` :
- `kuby_logger.info()` - Informations générales
- `kuby_logger.debug()` - Messages de débogage
- `kuby_logger.error()` - Erreurs
- `kuby_logger.audit()` - Audits de sécurité

---

## 📄 Licence

Ce projet est développé pour le réseau **Omega Kube**. Toute utilisation est soumise aux conditions du projet.

---

## 🤝 Contribution

Pour contribuer au projet :
1. Forkez le repository
2. Créez une branche (`git checkout -b feature/ma-fonctionnalite`)
3. Commitez vos changements (`git commit -m 'Ajout de...'`)
4. Push sur la branche (`git push origin feature/ma-fonctionnalite`)
5. Ouvrez une Pull Request

---

Développé avec ❤️ pour Omega Kube