# Documentation du Bot Kuby

## Table des matières
1. [Présentation générale](#présentation-générale)
2. [Architecture du bot](#architecture-du-bot)
3. [Installation et configuration](#installation-et-configuration)
4. [Modules et fonctionnalités](#modules-et-fonctionnalités)
5. [Système de sécurité](#système-de-sécurité)
6. [Gestion des tickets](#gestion-des-tickets)
7. [Système de logs](#système-de-logs)
8. [API REST](#api-rest)
9. [Commandes disponibles](#commandes-disponibles)
10. [Base de données](#base-de-données)
11. [Dépannage](#dépannage)

---

## Présentation générale

Kuby est un bot Discord multifonctionnel développé en Python utilisant la bibliothèque `discord.py`. Il est conçu pour offrir une gestion complète de serveur Discord avec des fonctionnalités de modération, sécurité, gestion de tickets, et bien plus encore.

### Caractéristiques principales
- **Système de whitelist** pour contrôler l'accès aux commandes
- **Gestion de tickets** avancée avec permissions configurables
- **Système de sécurité** anti-spam et anti-raid
- **Logs détaillés** des activités du serveur
- **Messages de bienvenue/départ** personnalisables
- **Modération** avec blacklist et scan de sécurité
- **Système de rôles automatique** pour les membres rejoignant
- **API REST** pour intégration externe et monitoring

---

## Architecture du bot

### Fichiers principaux

#### `kuby.py` - Point d'entrée
- Charge les variables d'environnement
- Initialise et démarre le bot
- Gère les erreurs critiques de démarrage

#### `bot.py` - Classe principale du bot
- Définit la classe `MyBot` héritant de `commands.Bot`
- Configure les intents Discord
- Charge toutes les extensions/modules
- Implémente les événements Discord principaux

### Structure des dossiers

```
kuby/
├── bot.py                 # Classe principale du bot
├── kuby.py               # Point d'entrée
├── commandes/            # Modules de commandes
│   ├── ticket/          # Système de tickets
│   ├── modules_security/ # Modules de sécurité
│   ├── whitelist.py     # Gestion whitelist
│   ├── blacklist.py     # Gestion blacklist
│   └── ...
├── src/                 # Utilitaires et core
│   ├── api/            # API REST module
│   │   ├── app.py      # Application Flask
│   │   ├── routes.py   # Routes API
│   │   └── config.py   # Configuration API
│   ├── logger.py       # Système de logging
│   └── advanced_logger.py # Logs avancés
├── data/                # Données de configuration
├── utils/               # Fonctions utilitaires
└── requirements.txt     # Dépendances Python
```

---

## Installation et configuration

### Prérequis
- Python 3.8+
- Un token de bot Discord

### Installation
1. Cloner le repository
2. Installer les dépendances :
   ```bash
   pip install -r requirements.txt
   ```

### Configuration
Créer un fichier `.env` avec les variables suivantes :
```env
# Discord Configuration
DISCORD_TOKEN=votre_token_discord
APPLICATION_ID=votre_id_application

# API Configuration
API_HOST=127.0.0.1
API_PORT=5000
API_DEBUG=False
API_SECRET_KEY=votre-cle-secrete-api

# Partner Server IDs (for API)
PARTNER_IDS=111111111111111111,222222222222222222,333333333333333333
```

### Dépendances principales
- `discord.py>=2.3.0` - API Discord
- `python-dotenv>=1.0.0` - Gestion variables d'environnement
- `Pillow>=10.0.0` - Traitement d'images
- `aiohttp>=3.8.0` - Requêtes HTTP asynchrones
- `flask>=2.3.0` - Framework API REST
- `flask-cors>=4.0.0` - Support CORS pour l'API

---

## Modules et fonctionnalités

### 1. Système de Whitelist (`whitelist.py`, `whitelist_monitor.py`)
- **Fonction** : Contrôle l'accès aux commandes du bot
- **Mécanisme** : Vérification globale avant l'exécution de toute commande
- **Exceptions** : 
  - Propriétaire du bot (bypass automatique)
  - Utilisateurs avec permissions tickets pour commandes spécifiques

### 2. Messages de bienvenue/départ (`welcome.py`, `goodbye.py`)
- **Fonctionnalités** :
  - Messages personnalisables avec images
  - Templates de bannières
  - Support de polices personnalisées
  - Restauration automatique des rôles

### 3. Système de sécurité (`security.py`)
- **Scan de sécurité** : Analyse des comptes suspects
- **Gestion des menaces** : Actions automatiques configurables
- **Logs de sécurité** : Traçabilité des incidents

### 4. Modules de sécurité avancés (`modules_security/`)
- **Anti-spam** : Détection et blocage des spams
- **Anti-raid** : Protection contre les raids massifs
- **Logs manager** : Gestion centralisée des logs
- **Rules** : Gestion des règles du serveur

### 5. Gestion des tickets (`ticket/`)
- **Création de tickets** : Interface complète pour les utilisateurs
- **Permissions** : Système granulaire d'accès
- **Configuration** : Paramètres par serveur
- **Support** : Outils de modération intégrés

---

## Système de sécurité

### Niveaux de protection
1. **Whitelist globale** : Contrôle d'accès aux commandes
2. **Anti-spam** : Détection de messages répétitifs
3. **Anti-raid** : Protection contre les arrivées massives
4. **Scan de sécurité** : Analyse des comptes suspects
5. **Blacklist** : Bannissement automatique

### Configuration de sécurité
- Paramètres stockés par serveur
- Actions configurables (kick, ban, avertissement)
- Logs détaillés pour audit

---

## Gestion des tickets

### Fonctionnalités
- **Création** : Interface utilisateur simple
- **Catégories** : Organisation par type de demande
- **Permissions** : Accès contrôlé par rôles
- **Transcription** : Sauvegarde des conversations
- **Statistiques** : Suivi des tickets

### Configuration
```python
# Exemple de configuration ticket
config = {
    "category_id": 123456789,
    "support_role_id": 987654321,
    "log_channel_id": 555666777,
    "transcript_channel_id": 888999000
}
```

---

## API REST

Le bot Kuby inclut une API REST basée sur Flask qui permet d'accéder à certaines fonctionnalités du bot via des requêtes HTTP.

### Configuration de l'API

L'API se configure via les variables d'environnement :
- `API_HOST` : Adresse d'écoute (défaut: 127.0.0.1)
- `API_PORT` : Port d'écoute (défaut: 5000)
- `API_DEBUG` : Mode debug (défaut: False)
- `API_SECRET_KEY` : Clé secrète pour la sécurité

### Endpoints disponibles

#### `GET /api/user/<user_id>`
Retourne les informations d'un utilisateur Discord.

**Réponse :**
```json
{
  "username": "Nom d'utilisateur",
  "avatar_url": "https://cdn.discordapp.com/avatars/user_id/avatar.png"
}
```

#### `GET /api/partners`
Retourne la liste des serveurs partenaires configurés.

**Réponse :**
```json
[
  {
    "name": "Nom du serveur",
    "icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png",
    "member_count": 150
  }
]
```

#### `GET /api/status`
Retourne le statut actuel du bot.

**Réponse :**
```json
{
  "status": "online",
  "username": "Kuby",
  "guild_count": 5,
  "total_members": 1250
}
```

#### `GET /api/guilds`
Retourne la liste des serveurs où le bot est présent.

**Réponse :**
```json
[
  {
    "id": 123456789,
    "name": "Serveur Discord",
    "icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png",
    "member_count": 250,
    "owner_id": 987654321
  }
]
```

### Utilisation

L'API démarre automatiquement avec le bot et est accessible sur `http://127.0.0.1:5000` par défaut.

**Exemple d'utilisation :**
```bash
# Obtenir les infos d'un utilisateur
curl http://127.0.0.1:5000/api/user/123456789

# Obtenir le statut du bot
curl http://127.0.0.1:5000/api/status
```

### Sécurité

- L'API utilise CORS pour permettre les requêtes cross-origin
- Les logs d'accès sont enregistrés via le système de logging du bot
- L'API s'exécute dans un thread séparé pour ne pas bloquer le bot Discord

---

## Système de logs

### Types de logs
1. **Logs standards** (`kuby_logs.log`) : Activités générales
2. **Audit logs** (`kuby_audit.log`) : Actions de modération
3. **Error logs** (`kuby_errors.log`) : Erreurs et exceptions
4. **Performance logs** : Métriques de performance

### Fonctionnalités avancées
- **Advanced Logger** : Suivi détaillé des événements
- **Restauration de rôles** : Mémorisation des rôles des membres
- **Notifications** : Messages de départ/arrivée
- **Voice tracking** : Suivi des salons vocaux

---

## Commandes disponibles

### Commandes de modération
- `!whitelist` : Gestion de la whitelist
- `!blacklist` : Gestion de la blacklist
- `!scan` : Analyse de sécurité
- `!security` : Configuration sécurité

### Commandes de tickets
- `!ticket` : Gestion des tickets
- `!ticketconfig` : Configuration du système
- `!ticketsetup` : Initialisation rapide

### Commandes utilitaires
- `!snipe` : Récupération de messages supprimés
- `!bug_report` : Rapport de bugs
- `!sendbotmessages` : Messages automatisés

### Commandes de configuration
- `!welcome` : Messages de bienvenue
- `!goodbye` : Messages de départ
- `!nolink` : Filtrage des liens

---

## Base de données

### Fichiers de données
- `config.db` : Configuration principale (SQLite)
- `whitelist.json` : Liste des utilisateurs autorisés
- Données par serveur dans le dossier `data/`

### Structure de la base de données
```sql
-- Tables principales
- guilds : Configuration par serveur
- users : Données utilisateurs
- tickets : Historique des tickets
- audit_logs : Logs de modération
```

---

## Dépannage

### Problèmes courants

#### Token Discord invalide
```
❌ Erreur: Token Discord non trouvé
```
**Solution** : Vérifier le fichier `.env` et le token Discord

#### Extensions non chargées
```
❌ Erreur lors du chargement de l'extension
```
**Solution** : Vérifier les imports et la syntaxe dans les modules

#### Permissions manquantes
```
❌ Vous n'êtes pas autorisé à utiliser cette commande
```
**Solution** : Ajouter l'utilisateur à la whitelist ou vérifier les permissions

### Logs utiles pour le dépannage
- `kuby_errors.log` : Erreurs détaillées avec stack traces
- `debug.log` : Informations de débogage
- Console output : Logs en temps réel

### Commandes de maintenance
```python
# Redémarrage du bot
!restart

# Vérification du statut
!status

# Rechargement des modules
!reload <module_name>
```

---

## Bonnes pratiques

### Sécurité
- Garder le token Discord secret
- Utiliser la whitelist pour limiter l'accès
- Configurer correctement les permissions
- Surveiller régulièrement les logs

### Performance
- Limiter le nombre de commandes simultanées
- Optimiser les requêtes base de données
- Utiliser le cache pour les données fréquemment accédées
- Surveiller l'utilisation mémoire

### Maintenance
- Sauvegarder régulièrement la base de données
- Mettre à jour les dépendances
- Nettoyer les anciens logs
- Documenter les modifications

---

## Support et développement

### Pour obtenir de l'aide
1. Consulter les logs d'erreurs
2. Vérifier la configuration
3. Tester avec des commandes simples
4. Contacter le développeur si nécessaire

### Contributeurs
Le bot Kuby est développé avec une architecture modulaire pour faciliter l'ajout de nouvelles fonctionnalités. Chaque module est indépendant et peut être maintenu séparément.

---

*Document généré automatiquement - Dernière mise à jour : 2025*