docs: ajout de la suite de documentation complète dans /docs et mise à jour du README

2026-08-23 18:04:36 +02:00
parent a2ccf0eb8c
commit 81edbea01d
8 changed files with 821 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 🛡️ Validation & Double Confirmation - betterMcCommands
+
+La bibliothèque intègre des mécanismes pour valider les pré-requis métier et sécuriser les actions destructrices ou sensibles.
+
+---
+
+## 📑 Sommaire
+- [1. Validation Métier au Niveau de la Commande](#1-validation-métier-au-niveau-de-la-commande)
+- [2. Validation au Niveau d'un Argument](#2-validation-au-niveau-dun-argument)
+- [3. Confirmation Préalable & Double Validation (`.requireConfirmation`)](#3-confirmation-préalable--double-validation-requireconfirmation)
+
+---
+
+## 1. Validation Métier au Niveau de la Commande
+
+La méthode `.validate(...)` permet d'exécuter des assertions logiques avant que le gestionnaire principal ne soit appelé. Si la validation échoue, le message d'erreur est automatiquement envoyé et la commande s'interrompt.
+
+### Exemple : Validation simple par prédicat
+```java
+BetterMcCommands.builder("level-reward")
+    .playerOnly()
+    // Teste si le joueur a le niveau requis
+    .validate(ctx -> ctx.getPlayer().getLevel() >= 10, "Vous devez posséder le niveau 10 minimum !")
+    .executes(ctx -> {
+        ctx.replySuccess("Récompense de niveau 10 réclamée !");
+    })
+    .register();
+```
+
+### Exemple : Validateur complexe (`CommandValidator`)
+```java
+BetterMcCommands.builder("claim")
+    .playerOnly()
+    .validate(ctx -> {
+        Player p = ctx.getPlayer();
+        if (economy.getBalance(p) < 500) {
+            return ValidationResult.invalid("Solde insuffisant : 500 $ requis.");
+        }
+        if (territoryManager.isProtected(p.getLocation())) {
+            return ValidationResult.invalid("Cette zone est déjà protégée !");
+        }
+        return ValidationResult.valid();
+    })
+    .executes(ctx -> {
+        ctx.replySuccess("Territoire revendiqué avec succès !");
+    })
+    .register();
+```
+
+---
+
+## 2. Validation au Niveau d'un Argument
+
+Vous pouvez également restreindre les valeurs acceptées par un argument :
+
+```java
+BetterMcCommands.builder("setprice")
+    .argument(Arguments.decimal("prix")
+        // Vérification personnalisée de la valeur
+        .validate(prix -> prix > 0, "Le prix doit être strictement supérieur à 0 !")
+        .validate(prix -> prix <= 1000000, "Le prix maximal autorisé est de 1 000 000 $.")
+    )
+    .executes(ctx -> {
+        double prix = ctx.getDouble("prix");
+        ctx.replySuccess("Prix configuré : <gold>" + prix + " $</gold>.");
+    })
+    .register();
+```
+
+---
+
+## 3. Confirmation Préalable & Double Validation (`.requireConfirmation`)
+
+Pour les commandes irréversibles (suppression de données, dissolution de guilde, réinitialisation de statistiques), activez la confirmation préalable avec `.requireConfirmation(...)` :
+
+```java
+BetterMcCommands.builder("disband")
+    .description("Dissout votre guilde")
+    .playerOnly()
+    // Délai de 15 secondes pour confirmer avec message d'avertissement
+    .requireConfirmation(Duration.ofSeconds(15), "<red><bold>ATTENTION</bold> : Cette action est irréversible ! Retapez <yellow>/disband</yellow> dans les 15 secondes pour confirmer.</red>")
+    .executes(context -> {
+        Player p = context.getPlayer();
+        guildManager.disbandGuild(p);
+        context.replySuccess("Votre guilde a été dissoute.");
+    })
+    .register();
+```
+
+### Comment fonctionne le cycle de confirmation ?
+1. **1ère exécution** : L'émetteur tape `/disband`.
+   - La commande est suspendue.
+   - Une demande de confirmation temporaire est enregistrée dans le `ConfirmationManager`.
+   - Le message d'avertissement est envoyé au joueur.
+   - L'événement `CommandConfirmationRequiredEvent` est diffusé.
+2. **2ème exécution (dans les 15s)** : L'émetteur retape `/disband`.
+   - La confirmation active est détectée et consommée.
+   - Le code du gestionnaire métier `.executes(...)` s'exécute normalement.
+3. **Expiration** : Si le joueur ne retape pas la commande dans le délai, la confirmation expire automatiquement.
+
+---
+
+> 📖 **Étape suivante** : Découvrez les cooldowns et répétitions dans [06_COOLDOWNS_AND_REPEAT.md](06_COOLDOWNS_AND_REPEAT.md).