Description du Script

# 🏴 O-Gang — Système de Gangs Avancé pour FiveM

> Système complet, professionnel et sécurisé de création et de gestion de gangs, comparable aux systèmes des gros serveurs GTA RP. Configuration 100 % en jeu via une interface NUI moderne — **aucune ligne de code à toucher pour créer un gang**.

**Framework :** ESX Legacy · **UI :** ox_lib + NUI custom · **Base de données :** oxmysql · **Inventaire :** ox_inventory · **Interactions :** ox_target · **Intérieurs :** bob74_ipl

---

## ✨ Vue d'ensemble

O-Gang permet à vos administrateurs de créer et configurer entièrement un gang depuis un menu graphique : identité, chef, membres, grades et permissions, quartier général, coffre, armurerie, garage et banque. Chaque chef de gang gère ensuite son organisation de façon autonome selon les permissions de son grade.

Tout est **validé côté serveur** (permissions, montants, positions, données) et **chaque action importante est loggée** en base de données et sur un webhook Discord.

---

## 🎯 Fonctionnalités détaillées

### Création & identité du gang
- Nom, tag court, description
- Couleur principale du gang (l'interface entière se teinte automatiquement à cette couleur)
- Logo personnalisé (URL)
- **Blip carte configurable** : activation, nom, sprite, couleur, taille, et visibilité (membres uniquement ou tout le monde)
- **Annonce du gang (MOTD)** 📢 : message épinglé dans le menu, diffusé automatiquement aux membres connectés à chaque modification

### Chef & gestion des membres
- Attribution d'un chef à la création
- Invitation de joueurs par ID (avec fenêtre d'acceptation côté invité)
- Expulsion de membres (dans le respect de la hiérarchie)
- Changement de grade
- Transfert de la direction du gang à un autre membre
- Statut en ligne / hors ligne des membres en temps réel
- **Historique complet des actions du gang** (50 dernières)

### Grades & permissions personnalisables
Système de grades illimité et entièrement modifiable en jeu :
- Nom du grade, niveau hiérarchique
- 7 permissions attribuables : gérer les membres, modifier les véhicules, accéder au coffre, déposer, retirer, utiliser l'armurerie, modifier les paramètres du gang
- Grades par défaut fournis : Recrue → Membre → Soldat → Bras droit → Sous-chef → Chef

### Quartier Général (QG)
- **7 types d'intérieurs prêts à l'emploi** via bob74_ipl : petit appartement, entrepôt, villa, bureau (Maze Bank Tower), clubhouse de motards, boîte de nuit, penthouse du casino
- Position extérieure (porte) et intérieure (arrivée) configurables
- **Téléportation entrée/sortie via ox_target**
- Blip du QG réservé aux membres
- Compatible avec vos propres MLO (coordonnées modifiables)

### Coffre du gang 📦
- **Point physique** placé dans le QG (interaction ox_target)
- Stash partagé ox_inventory : objets, armes, argent sale/propre
- Slots et poids configurables par gang
- Accès contrôlé par permission de grade
- **Position vérifiée côté serveur** (anti-triche)

### Armurerie du gang 🔫
- **Point physique** placé dans le QG (interaction ox_target)
- Achats d'armes, munitions et items payés directement avec la **banque du gang**
- Grade minimum requis par article
- Catalogue et prix entièrement configurables
- **Position + permission + solde + grade vérifiés côté serveur**

### Garage du gang 🚗
- Point d'ouverture du garage (ox_target)
- Point de sortie du véhicule avec rotation
- Rangement du véhicule via ox_target directement sur le véhicule
- Liste de véhicules configurable : nom, modèle, catégorie, grade minimum
- **Couleur unique du gang** appliquée automatiquement à tous les véhicules sortis
- Plaques d'immatriculation générées au tag du gang

### Banque du gang 💰
- Solde partagé
- Dépôt / retrait avec permissions par grade
- **Historique des transactions** (dépôts, retraits, achats d'armurerie)

### Chat de gang 💬
- Commande `/gc <message>`
- Visible uniquement par les membres connectés
- Affiché aux couleurs du gang avec le tag en préfixe

### Interface d'administration (NUI)
- Créer / modifier / supprimer un gang
- Gérer membres, grades, QG, garage, véhicules, coffre
- Boutons **📍 Ma position** pour remplir les coordonnées sans quitter le jeu
- Ajout/retrait de membres, promotion, nomination de chef

### Interface joueur (NUI)
- Aperçu (banque, membres, en ligne, véhicules, annonce)
- Membres, grades, banque, garage, paramètres, historique
- Onglets affichés dynamiquement selon les permissions du joueur

---

## 🔒 Sécurité

- Architecture **serveur-autoritaire** : le client n'affiche que des données, toutes les actions repassent par des callbacks serveur validés
- Vérification des permissions, montants, coordonnées et listes à chaque action
- Vérification de la **position réelle** du joueur pour le coffre et l'armurerie
- Anti-spam sur le dispatcher d'actions
- Requêtes SQL préparées (protection contre l'injection)

---

## 🛠️ Technique

- **Code propre, commenté et optimisé** (~3 400 lignes)
- Threads optimisés, aucune boucle inutile côté client
- Base de données relationnelle avec clés étrangères (`ON DELETE CASCADE`)
- Cache serveur des gangs pour des performances optimales
- **Logs Discord webhook** pour toutes les actions importantes
- Configuration centralisée et documentée dans `config.lua`
- Installation en 3 étapes (import SQL + `ensure`)

## 📦 Dépendances

| Ressource | Rôle |
|---|---|
| es_extended (ESX Legacy) | Framework |
| ox_lib | UI, callbacks, zones |
| oxmysql | Base de données |
| ox_inventory | Coffre & items de l'armurerie |
| ox_target | Points d'interaction |
| bob74_ipl | Intérieurs des QG |