feat(guild): implement complete domain model, spatio-temporal pricing, repository, and managers with full javadoc

2026-08-20 17:16:05 +02:00
parent 0ba297a648
commit efd57a3a1e
32 changed files with 3348 additions and 1021 deletions
@@ -0,0 +1,92 @@
+# 📜 Instructions & Consignes du Projet - GamingCore (Système de Guilde)
+
+Ce document consigne les directives d'architecture, règles de développement et spécifications fonctionnelles du projet **GamingCore**.
+
+---
+
+## 🎯 1. Vision du Projet
+Développement d'un système de **Guilde complet, modulaire et hautement configurable** pour Minecraft (Paper 1.20.1+ / Java 21 LTS - target Java 17).
+
+---
+
+## 📐 2. Règles & Standards de Développement
+
+### 🔹 Conception du Code
+* **Méthodes & Logique Métier d'Abord** : Tout le système doit reposer sur des méthodes et services métier découplés (Managers, Repositories, Calculators), indépendants du système de commande ou d'UI.
+* **Dynamisme & Modularité** : Le code doit être découpé en parties logiques claires et évolutives.
+* **Documentation Obligatoire** : **Chaque méthode** doit comporter une Javadoc / un commentaire détaillé explicitant :
+  * Son rôle et son comportement.
+  * Ses paramètres (`@param`).
+  * Sa valeur de retour (`@return`).
+  * Les éventuelles exceptions levées (`@throws`).
+
+### 🔹 Dépendances & Intégrations
+* **Paper API 1.20.4** : API Bukkit/Paper cross-version.
+* **Vault API 1.7.1** : Gestion de l'économie (dépôt, retrait, vérification de solde).
+* **WorldGuard 7.0.9 & WorldEdit 7.3.0** : Intégration et compatibilité régionale.
+* **Kyori Adventure & MiniMessage** : Couleurs HEX, gradients et composants de texte modernes.
+* **XSeries 13.0.0** : Abstraction des matériaux, sons et particules.
+
+---
+
+## 🏰 3. Spécifications Métier du Système de Guilde
+
+### 1. Structure d'une Guilde
+* Création soumise à un coût économique (Vault) et au claim obligatoire du chunk initial.
+* Données : `UUID`, `nom`, `tag`, `description`, `solde bancaire`, `point de ralliement (home)`, `membres`, `rangs`, `claims`.
+
+### 2. Rangs & Permissions Dynamiques par Guilde
+* Chaque guilde peut créer, renommer, hiérarchiser (priorité) et supprimer ses propres rangs.
+* Rangs initiaux par défaut à la création :
+  * **👑 Chef (Leader)** : Priorité maximale (100), toutes les permissions, non supprimable.
+  * **⚔ Officier (Officer)** : Priorité intermédiaire (50), gestion des membres et claims.
+  * **🛡 Membre (Member)** : Priorité de base (1), rang par défaut des recrues.
+* Permissions granulaires configurables par rang :
+  * `CLAIM`, `UNCLAIM`, `SET_HOME`, `HOME`, `INVITE`, `KICK`, `PROMOTE`, `DEMOTE`, `MANAGE_RANKS`, `BANK_DEPOSIT`, `BANK_WITHDRAW`, `BUILD`, `BREAK`, `INTERACT`, `CONTAINER`.
+
+### 3. Moteur Économique & Calcul Spatio-Temporel des Chunks
+Le prix d'acquisition d'un nouveau chunk suit la formule spatio-temporelle avec surchauffe glissante sur 24h :
+
+$$\text{PrixFinal}(N, R) = \left[ P_{\text{base}} \times (1 + \text{Taux})^{(N - 1)^\alpha} + (N - 1) \times \text{Palier} \right] \times \left[ 1 + \left( k_{\text{base}} + k_{\text{taille}} \times \left(\frac{N}{10}\right) \right) \times R^{\delta} \right]$$
+
+* **$N$** : Nombre total de chunks possédés.
+* **$R$** : Nombre de chunks achetés dans les dernières 24h (décroissance automatique).
+* **Effet d'échelle** : La surchauffe temporelle est plus sévère pour une grande guilde que pour une petite.
+
+### 4. Banque de Guilde
+* Solde partagé avec dépôts libres et retraits sécurisés par permissions de rang.
+
+### 5. Invitations
+* Invitations temporaires expirables (ex: 60s) avec acceptation/refus.
+
+### 6. Protection Territoriale & Listeners
+* Protection des blocs, conteneurs, portes et explosions sur les chunks de guilde en fonction des permissions de rang du joueur.
+
+---
+
+## 🗂️ 4. Organisation des Packages
+
+```
+fr.luc.gamingcore/
+ ├── Main.java                          (Point d'entrée du plugin)
+ ├── model/                             (Entités et Enums du domaine)
+ │    ├── Guild.java
+ │    ├── GuildMember.java
+ │    ├── GuildRank.java
+ │    ├── GuildPermission.java
+ │    ├── GuildClaim.java
+ │    └── GuildInvite.java
+ ├── economy/                           (Gestion économique & Formule mathématique)
+ │    ├── EconomyManager.java
+ │    └── ChunkPriceCalculator.java
+ ├── database/                          (Persistance SQLite/MySQL)
+ │    ├── DatabaseManager.java
+ │    └── GuildRepository.java
+ ├── manager/                           (Logique métier et services)
+ │    ├── GuildManager.java
+ │    └── InviteManager.java
+ ├── listener/                          (Interception des événements et protection)
+ │    └── TerritoryProtectionListener.java
+ └── util/                              (Utilitaires de texte et formatage)
+      └── TextUtil.java
+```