Perimetres de notification et rattachement des modeles

docs/NOTIFICATIONS.md

@@ -0,0 +1,91 @@
+# Notifications par périmètre
+
+Un modèle de service sans notification ne sert à rien en production. Enclume génère donc
+aussi la chaîne de notification : le calendrier, la commande, les paramètres des contacts,
+et le script PHP qui met en forme le message.
+
+## Le principe
+
+Un **périmètre** regroupe ce qui différencie réellement un domaine d'un autre :
+
+| Élément | Rôle |
+|---|---|
+| Calendrier | quand la notification a le droit de partir (objet `TP` de Centreon) |
+| Destinataires | contacts existants et groupe à créer |
+| États déclencheurs | distincts pour l'hôte et le service |
+| Contexte métier | application, responsable, criticité, impact, procédure de reprise |
+| Sujets | pour l'hôte et pour le service, avec les macros de Centreon |
+
+Un incident sur la chaîne de facturation et un disque plein sur un serveur de rebond
+n'appellent ni le même destinataire, ni le même horaire, ni le même message. C'est
+exactement ce que le périmètre permet de séparer.
+
+## Ce qui est généré
+
+Pour chaque périmètre :
+
+- deux commandes de type `notif`, `<Périmètre>-Notify-Host` et `-Notify-Service` ;
+- un script `notifications/notif-<périmètre>.php`, avec le shebang
+  `#!/usr/bin/php -c /etc/php.ini` ;
+- les paramètres de notification de chaque contact : `hostnotifperiod`, `svcnotifperiod`,
+  `hostnotifopt`, `svcnotifopt`, `hostnotifcmd`, `svcnotifcmd` ;
+- le groupe de contacts, s'il est demandé.
+
+Et pour l'ensemble du projet, `notifications/installer.sh`, qui dépose les scripts sur le
+serveur.
+
+## Rattacher un modèle à un périmètre
+
+C'est ce qui referme la boucle. Un modèle d'hôte ou de service porte un champ **périmètre de
+notification** ; renseigné, la génération ajoute au modèle :
+
+```
+HTPL;setparam;App-Facturation-custom;notifications_enabled;1
+HTPL;setparam;App-Facturation-custom;notification_period;Heures-Ouvrees
+HTPL;setparam;App-Facturation-custom;notification_options;d,u,r
+HTPL;setparam;App-Facturation-custom;notification_interval;15
+HTPL;setcontactgroup;App-Facturation-custom;CG-Facturation
+```
+
+Le modèle de service reçoit le même traitement, avec ses propres états déclencheurs — un
+service en alerte et un hôte indisponible ne se notifient pas selon les mêmes règles.
+
+Conséquence pratique : un hôte qui hérite de `App-Facturation-custom` arrive dans Centreon
+avec sa chaîne de notification complète. Rien à reprendre à la main dans l'interface.
+
+## Installation
+
+Les scripts ne s'installent pas tout seuls — comme le CLAPI, Enclume les écrit et vous les
+jouez, après relecture :
+
+```bash
+cd notifications
+./installer.sh          # vérifie la syntaxe PHP, puis dépose dans le répertoire cible
+```
+
+Le script d'installation contrôle chaque fichier avec `php -l` avant de le copier, et
+l'installe en `0750` pour l'utilisateur du moteur de supervision.
+
+Un agent de transport de courrier doit être en place sur la machine : le script utilise la
+fonction `mail()` de PHP, qui passe par `sendmail`. L'adresse d'expédition se règle par la
+variable d'environnement `ENCLUME_EXPEDITEUR`, à défaut `centreon@<nom de la machine>`.
+
+## Le message produit
+
+Un message HTML avec un bandeau coloré selon l'état — vert rétabli, orange alerte, rouge
+critique —, un tableau des informations de l'événement, la sortie du plugin en police fixe,
+les champs métier du périmètre, et un lien vers la procédure de reprise quand elle est
+renseignée.
+
+Toutes les valeurs passent par `htmlspecialchars` : la sortie d'un plugin peut contenir
+n'importe quoi, y compris des caractères qui casseraient la mise en page.
+
+## Ce qu'Enclume ne fait pas
+
+**Créer les contacts.** Ils doivent exister sur le central, avec leur adresse de courriel.
+Enclume règle leurs paramètres de notification, il ne les invente pas.
+
+**Envoyer le message.** Le site n'exécute rien, ici comme ailleurs.
+
+**Gérer les escalades.** Elles ne sont pas exposées par CLAPI et restent à définir dans
+l'interface de Centreon.