feat: configurable broadcasts + /core reload

New fr.luc.crcore.broadcast module: - BroadcastAudience enum (NONE, LEADER, TEAM, ADMIN, ALL). - BroadcastContext (fluent: team + involvedPlayerId + placeholders). - BroadcastService interface + YamlBroadcastService impl. - CRCoreBroadcastListener (Bukkit listener) wires the 12 native events (9 team + 3 player) to broadcasts.broadcast(eventKey, ctx). Same single-per-plugin file pattern as messages: <plugin-dataFolder>/<plugin-name-lowercase>-broadcasts.yml. Defaults bundled at resources/crcore-broadcasts.yml, copied on first boot (game plugin's own resource of the same name takes priority as the template). In-memory fallback so new CR-Core keys work without admin edit. Routes (who) vs templates (what) are separated: broadcasts.yml lists audiences per eventKey, messages.yml contains the templates under keys <eventKey>.broadcast. Admin can change either independently. 12 new *.broadcast keys added to crcore-messages.yml with sensible French defaults and color codes. Listener injects standard placeholders (name, team_name, tag, color, visibility, player, new_leader, old/new_value, etc.). ADMIN audience resolved via crcore.broadcast.admin permission. Multi- audiences via YAML list (e.g., [TEAM, ADMIN]); union of resolved players, no duplicate. New /core reload subcommand (permission crcore.reload) hot-reloads both messages and broadcasts from disk without restart. CRCore: protected buildBroadcastService() override point, getter broadcasts(), wire of CRCoreBroadcastListener at enable(). CoreCommand constructor extended to take BroadcastService, registers the reload subcommand. Docs/features.md: new section 9 "Service de broadcasts". docs/setup.md: updated to mention both YAML files. decisions.md logs the routes-vs- templates split, the audience model, and the reload semantics. New diagram broadcasts-class-diagram.puml. README updated. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 11:16:34 +02:00
parent 923f48ffc7
commit a94bc56a5b
15 changed files with 1060 additions and 22 deletions
@@ -30,6 +30,12 @@ d'initialisation côté plugin de jeu :
  YAML `<plugin>-messages.yml` dans le dataFolder du plugin de jeu,
  avec defaults CR-Core en fallback. L'admin édite un seul fichier,
  placeholders nommés, codes couleur `&` natifs.
+- **Broadcasts configurables** — `BroadcastService` route chaque event
+  CR-Core vers une liste d'audiences (`NONE`, `LEADER`, `TEAM`, `ADMIN`,
+  `ALL`) définie dans `<plugin>-broadcasts.yml`. Séparation routes /
+  templates. Un listener interne wire les 12 events natifs ; les game
+  plugins peuvent broadcast leurs propres events. `/core reload` recharge
+  les deux fichiers à chaud.
 - **Bootstrap unique** — `new CRCore(this).enable()` dans le `onEnable()`
  du plugin de jeu, et tout est branché.

@@ -55,6 +61,7 @@ d'initialisation côté plugin de jeu :
 | [events-diagram.puml](diagrams/events-diagram.puml) | Classe | Évènements Bukkit team + player |
 | [database-diagram.puml](diagrams/database-diagram.puml) | Classe | Wrapper SQLite + table builder |
 | [messages-class-diagram.puml](diagrams/messages-class-diagram.puml) | Classe | Service de messages YAML |
+| [broadcasts-class-diagram.puml](diagrams/broadcasts-class-diagram.puml) | Classe | Service de broadcasts YAML + listener |
 | [bootstrap-sequence.puml](diagrams/bootstrap-sequence.puml) | Séquence | `CRCore.enable()` côté plugin de jeu |

 ## Conventions
@@ -367,6 +367,42 @@ Format léger : une décision = un titre + contexte + choix + raison.
  bases existantes, ALTER TABLE manuel ou suppression du fichier
  (les bases d'event sont jetables).

+## 2026-06-10 — Système de broadcasts configurables + `/core reload`
+
+- **Choix** : nouveau module `fr.luc.crcore.broadcast` avec
+  `BroadcastService` + `BroadcastAudience` enum + `BroadcastContext` data
+  class + `YamlBroadcastService` impl. Un listener Bukkit interne
+  (`CRCoreBroadcastListener`) écoute les 12 events CR-Core et les traduit
+  en appels `broadcast(eventKey, ctx)`.
+- **Modèle « un seul fichier par plugin »** identique à messages :
+  `<plugin-dataFolder>/<plugin-name-lowercase>-broadcasts.yml`. Defaults
+  bundlés dans le jar à `crcore-broadcasts.yml`, copiés au premier boot
+  (avec priorité au template du plugin de jeu sous le même nom s'il en
+  fournit un).
+- **Séparation routes / templates** :
+  - **Routes** = qui reçoit quoi = `<plugin>-broadcasts.yml` (liste
+    d'audiences par event)
+  - **Templates** = quel texte = `<plugin>-messages.yml` (clés
+    `<eventKey>.broadcast`)
+  - L'admin peut modifier l'un sans toucher à l'autre. Modulaire.
+- **5 audiences** : `NONE`, `LEADER`, `TEAM`, `ADMIN`, `ALL`.
+  Multi-cibles via liste, union sans doublon.
+- **Permission ADMIN** : `crcore.broadcast.admin` (granular,
+  configurable côté LuckPerms).
+- **Listener Bukkit interne** : `CRCoreBroadcastListener` est instancié
+  et enregistré dans `CRCore.enable()`. Les game plugins n'ont rien à
+  faire pour bénéficier du broadcast des events natifs CR-Core ; pour
+  leurs propres events, ils appellent `core.broadcasts().broadcast(...)`.
+- **Pas de cancellation** : le broadcast est post-event ; si une route
+  est mal configurée, on ne casse pas la logique métier — au pire un
+  message non envoyé ou envoyé trop large.
+- **Nouvelle commande `/core reload`** : permission `crcore.reload`,
+  recharge `messages` + `broadcasts` depuis les fichiers user. Les
+  defaults en jar restent fixes. Hot reload utile en dev / pour ajuster
+  les routes sans restart.
+- **Override de l'impl** : `CRCore.buildBroadcastService(messages)` est
+  `protected` — comme pour les autres services.
+
 ## 2026-06-09 — Réorganisation packages : `impl/` et `exception/` séparés

 - **Choix** : pour chaque domaine (`team`, `player`, `message`), les
@@ -0,0 +1,102 @@
+@startuml broadcasts-class-diagram
+title CR-Core — Broadcast service (class diagram)
+
+skinparam classAttributeIconSize 0
+hide empty members
+
+package "fr.luc.crcore.broadcast" {
+
+  enum BroadcastAudience {
+    NONE
+    LEADER
+    TEAM
+    ADMIN
+    ALL
+  }
+
+  class BroadcastContext {
+    - team: Team
+    - involvedPlayerId: UUID
+    - placeholders: Map<String, String>
+    --
+    + {static} of(team): BroadcastContext
+    + {static} empty(): BroadcastContext
+    + involving(playerId): BroadcastContext
+    + with(key, value): BroadcastContext
+    + getTeam(): Optional<Team>
+    + getInvolvedPlayerId(): Optional<UUID>
+    + getPlaceholders(): Map<String, String>
+    + toPlaceholderPairs(): Object[]
+  }
+
+  interface BroadcastService {
+    + broadcast(eventKey, context): void
+    + getAudiences(eventKey): List<BroadcastAudience>
+    + reload(): void
+  }
+
+  class CRCoreBroadcastListener {
+    - broadcasts: BroadcastService
+    + registerOn(plugin: JavaPlugin): void
+    --
+    @ onTeamCreate(TeamCreateEvent)
+    @ onTeamDissolve(TeamDissolveEvent)
+    @ onTeamMemberAdd(TeamMemberAddEvent)
+    @ onTeamMemberRemove(TeamMemberRemoveEvent)
+    @ onPlayerJoinTeam(PlayerJoinTeamEvent)
+    @ onLeadershipTransfer(TeamLeadershipTransferEvent)
+    @ onVisibilityChange(TeamVisibilityChangeEvent)
+    @ onTeamScoreChange(TeamScoreChangeEvent)
+    @ onTeamSpawnChange(TeamSpawnPointChangeEvent)
+    @ onProfileCreate(PlayerProfileCreateEvent)
+    @ onProfileDelete(PlayerProfileDeleteEvent)
+    @ onPlayerScoreChange(PlayerScoreChangeEvent)
+  }
+  CRCoreBroadcastListener ..|> "org.bukkit.event.Listener"
+
+  package "fr.luc.crcore.broadcast.impl" {
+    class YamlBroadcastService {
+      - plugin: JavaPlugin
+      - messages: MessagesService
+      - defaults: Map<String, List<BroadcastAudience>>
+      - audiences: Map<String, List<BroadcastAudience>>
+      - userFile: File
+      --
+      + YamlBroadcastService(plugin, messages)
+      - loadDefaultsFromResource(): void
+      - ensureUserFile(): void
+      - rebuildEffectiveAudiences(): void
+      - resolveRecipients(list, ctx): Set<Player>
+    }
+    YamlBroadcastService ..|> BroadcastService
+  }
+
+  BroadcastService ..> BroadcastContext : consumes
+  BroadcastContext --> BroadcastAudience
+  YamlBroadcastService --> "fr.luc.crcore.message.MessagesService" : reads templates
+  CRCoreBroadcastListener --> BroadcastService : delegates
+  CRCoreBroadcastListener ..> BroadcastContext : builds
+}
+
+package "fr.luc.crcore" {
+  class CRCore {
+    + broadcasts(): BroadcastService
+    # buildBroadcastService(messages): BroadcastService
+  }
+  CRCore "1" *-- "1" BroadcastService : owns
+  CRCore ..> CRCoreBroadcastListener : registers
+}
+
+note bottom of YamlBroadcastService
+  Modèle "un seul fichier par plugin" :
+
+  Sources en mémoire :
+    1. crcore-broadcasts.yml         ← jar (fallback)
+    2. <plugin>-broadcasts.yml       ← dataFolder (édité par l'admin)
+
+  Séparation routes / templates :
+    - Routes = ce fichier (qui reçoit quoi)
+    - Templates = MessagesService (clés <event>.broadcast)
+end note
+
+@enduml
@@ -684,7 +684,130 @@ placeholders documentés en commentaire.

 ---

-## 9. Bootstrap `CRCore`
+## 9. Service de broadcasts (`fr.luc.crcore.broadcast`)
+
+**Statut** : implémenté. Un seul listener Bukkit interne route les 12
+événements CR-Core vers le {@code BroadcastService} qui décide à qui
+envoyer le message selon la config YAML.
+
+### Séparation routes / templates
+
+- **Routes** (« qui reçoit quoi ») → `<plugin>-broadcasts.yml`
+- **Templates** (« quel texte ») → `<plugin>-messages.yml`, clés
+  `<eventKey>.broadcast` (ex. `team.create.broadcast`)
+
+Les deux fichiers sont modifiables indépendamment. L'admin peut couper
+tous les broadcasts en passant tout en `[NONE]` sans toucher aux templates,
+ou inversement changer la formulation sans toucher aux routes.
+
+### `BroadcastAudience` — qui reçoit
+
+| Audience | Résolution |
+|---|---|
+| `NONE`   | Personne (équivalent à liste vide). |
+| `LEADER` | Le chef de l'équipe concernée (s'il est en ligne). |
+| `TEAM`   | Tous les membres en ligne de l'équipe concernée. |
+| `ADMIN`  | Joueurs en ligne ayant la perm `crcore.broadcast.admin`. |
+| `ALL`    | Tous les joueurs en ligne sur le serveur. |
+
+Multi-cibles : une clé d'event mappe sur une **liste** d'audiences. Union
+(pas de doublon : un joueur dans deux audiences reçoit un seul message).
+
+### Le fichier `<plugin>-broadcasts.yml` — exemple
+
+```yaml
+team:
+  create: [ADMIN]                    # admins voient les créations
+  dissolve: [TEAM, ADMIN]
+  member:
+    add: [TEAM]
+    remove: [TEAM]
+  player:
+    join: [TEAM]
+  leadership:
+    transfer: [TEAM, ADMIN]
+  visibility:
+    change: [LEADER]
+  score:
+    change: [NONE]                   # noisy par défaut
+  spawn:
+    change: [LEADER]
+
+player:
+  profile:
+    create: [NONE]
+    delete: [ADMIN]
+  score:
+    change: [NONE]
+```
+
+### Liste des `eventKey` (= mapping listener)
+
+| Bukkit event | Clé broadcasts.yml | Clé messages.yml |
+|---|---|---|
+| `TeamCreateEvent` | `team.create` | `team.create.broadcast` |
+| `TeamDissolveEvent` | `team.dissolve` | `team.dissolve.broadcast` |
+| `TeamMemberAddEvent` | `team.member.add` | `team.member.add.broadcast` |
+| `TeamMemberRemoveEvent` | `team.member.remove` | `team.member.remove.broadcast` |
+| `PlayerJoinTeamEvent` | `team.player.join` | `team.player.join.broadcast` |
+| `TeamLeadershipTransferEvent` | `team.leadership.transfer` | `team.leadership.transfer.broadcast` |
+| `TeamVisibilityChangeEvent` | `team.visibility.change` | `team.visibility.change.broadcast` |
+| `TeamScoreChangeEvent` | `team.score.change` | `team.score.change.broadcast` |
+| `TeamSpawnPointChangeEvent` | `team.spawn.change` | `team.spawn.change.broadcast` |
+| `PlayerProfileCreateEvent` | `player.profile.create` | `player.profile.create.broadcast` |
+| `PlayerProfileDeleteEvent` | `player.profile.delete` | `player.profile.delete.broadcast` |
+| `PlayerScoreChangeEvent` | `player.score.change` | `player.score.change.broadcast` |
+
+### Placeholders injectés par le listener
+
+Pour les events team, le contexte inclut toujours : `{name}`, `{team_name}`
+(alias), `{tag}`, `{color}` (code couleur ChatColor), `{visibility}`.
+Quand pertinent, en plus : `{player}` (nom du joueur impliqué),
+`{new_leader}`, `{old_leader}`, `{old_visibility}`, `{new_visibility}`,
+`{score_name}`, `{old_value}`, `{new_value}`, `{delta}`.
+
+### API pour les game plugins
+
+```java
+// Broadcast custom depuis un game plugin
+core.broadcasts().broadcast("mygame.round.start",
+    BroadcastContext.empty()
+        .with("round", String.valueOf(currentRound))
+        .with("map", mapName));
+
+// Lecture des audiences configurées (debug)
+List<BroadcastAudience> who = core.broadcasts().getAudiences("team.create");
+
+// Hot reload
+core.broadcasts().reload();
+```
+
+Pour ajouter ses propres events broadcast, le game plugin :
+1. Ajoute la clé dans son `<plugin>-broadcasts.yml` (ex.
+   `mygame.round.start: [ALL]`)
+2. Ajoute le template dans `<plugin>-messages.yml` (clé
+   `mygame.round.start.broadcast`)
+3. Appelle `core.broadcasts().broadcast(...)` quand l'event survient
+
+### Override de l'impl
+
+`CRCore.buildBroadcastService(messages)` est `protected`. Sous-classe
+{@code CRCore} pour fournir une impl alternative (base de données, queue
+externe, etc.).
+
+### Commande `/core reload`
+
+Permission : `crcore.reload`. Recharge à la fois `messages` et `broadcasts`
+depuis les fichiers user du dataFolder. Les defaults en jar ne bougent pas
+(pas re-chargés).
+
+### Diagramme
+
+- Classes : [broadcasts-class-diagram.puml](diagrams/broadcasts-class-diagram.puml)
+
+---
+
+## 10. Bootstrap `CRCore`

 **Statut** : implémenté. Point d'entrée unique pour les plugins de jeu.

@@ -265,6 +265,24 @@ CitesPlugin/                                 # dossier IntelliJ (renommer plus t
            └── SqlitePlayerProfileRepository.java
 ```

+## Fichiers de config générés au premier `enable()`
+
+Au premier démarrage, CR-Core crée DEUX fichiers dans le dataFolder :
+
+| Fichier | Rôle |
+|---|---|
+| `<plugin-name-lowercase>-messages.yml` | Templates de tous les messages (commandes + broadcasts) |
+| `<plugin-name-lowercase>-broadcasts.yml` | Routes : qui reçoit quel event |
+
+Les deux suivent le même pattern : si ton plugin de jeu bundle un fichier
+au même nom dans ses ressources, c'est lui qui sert de template initial à
+la place des defaults CR-Core. Les defaults restent en mémoire en
+fallback — donc les clés non présentes dans le fichier user marchent quand
+même.
+
+Hot reload : `/core reload` (permission `crcore.reload`) relit les deux
+fichiers sans restart.
+
 ## Fichier messages

 Au premier `enable()`, CR-Core crée :