<?php
/**
 * ASPIC — moteur_consignes.php
 *
 * Moteur générique du chantier des consignes (6 septembre 2026, voir
 * Réflexions stratégiques). Lit ASP_Consignes/ASP_Fonctions à l'exécution et
 * applique ce qu'il y trouve — l'objectif explicite de Jean-Marc étant que
 * l'ajout d'une ligne dans ASP_Consignes change le comportement réel de
 * l'application sans qu'aucun fichier PHP/JS ne soit retouché, sauf si une
 * fonction nouvelle doit être écrite dans consignes_fonctions.php (ou en cas
 * de bug). Ce fichier ne doit donc plus jamais contenir la moindre référence
 * à un champ ou une consigne précis — tout vient de la base.
 *
 * Portée de cette première version, volontairement limitée :
 * - Un seul champ à la fois (CNS_Champ NULL — consigne transverse à la fiche
 *   entière, ex. futur contrôle de doublon — n'est PAS encore géré ; ces
 *   lignes sont ignorées pour l'instant, à reprendre quand un vrai cas se
 *   présentera).
 * - CNS_Moment n'est PAS distingué ici : temps réel (Saisie) abandonné pour
 *   cette version (décision de Jean-Marc, 6 septembre 2026 — priorité à la
 *   robustesse plutôt qu'au retour immédiat à l'écran). Toute consigne
 *   active s'applique donc au moment de l'enregistrement, qu'elle porte
 *   Saisie ou Validation.
 * - Un seul message d'erreur retourné (le premier test en échec) — pas
 *   d'accumulation de plusieurs erreurs à la fois pour ce premier chantier.
 *
 * CNS_Portee : 'Mise à jour' est traité comme un mot-clé signifiant "les deux
 * moments" (Création et Modification), à côté de valeurs plus précises
 * ('Création' ou 'Modification' seules seraient possibles plus tard pour une
 * règle d'immuabilité — voir Réflexions stratégiques).
 */

/**
 * @param PDO    $pdo      Connexion déjà ouverte (voir db.php).
 * @param string $contexte Ex. 'Contacts' (ASP_Consignes.CNS_Contexte).
 * @param string $portee   'Création' ou 'Modification'.
 * @param array  $data     Données du formulaire, par référence — les
 *                          traitements silencieux (ex. majuscules) modifient
 *                          directement ce tableau.
 * @return string|null     Message d'erreur du premier test en échec (déjà le
 *                          texte à renvoyer tel quel au front-end), ou null
 *                          si tout est passé.
 */
function appliquerConsignes(PDO $pdo, string $contexte, string $portee, array &$data): ?string
{
    $sql = "SELECT c.CNS_Champ, c.CNS_Nature, c.CNS_MessageErreur, f.FON_NomPHP
            FROM ASP_Consignes c
            LEFT JOIN ASP_Fonctions f
                   ON f.FON_Nom = c.CNS_Fonction AND f.FON_Active = 'O'
            WHERE c.CNS_Contexte = ?
              AND c.CNS_Active = 'O'
              AND c.CNS_Champ IS NOT NULL
              AND (c.CNS_Portee = 'Mise à jour' OR FIND_IN_SET(?, c.CNS_Portee))
            ORDER BY c.CNS_Incr";
    $stmt = $pdo->prepare($sql);
    $stmt->execute([$contexte, $portee]);
    $consignes = $stmt->fetchAll();

    // Traitements d'abord (silencieux, jamais de message) : une consigne de
    // test lue ensuite doit voir la valeur déjà mise en forme (ex. le nom
    // déjà en majuscules avant de vérifier qu'il n'est pas vide).
    foreach ($consignes as $c) {
        if ($c['CNS_Nature'] !== 'Traitement') continue;
        if (!$c['FON_NomPHP'] || !function_exists($c['FON_NomPHP'])) continue;
        $valeurActuelle = (string)($data[$c['CNS_Champ']] ?? '');
        $data[$c['CNS_Champ']] = call_user_func($c['FON_NomPHP'], $valeurActuelle);
    }

    // Puis les tests, sur les valeurs déjà transformées ci-dessus.
    foreach ($consignes as $c) {
        if ($c['CNS_Nature'] !== 'Test') continue;
        if (!$c['FON_NomPHP'] || !function_exists($c['FON_NomPHP'])) continue;
        $valeur = (string)($data[$c['CNS_Champ']] ?? '');
        if (!call_user_func($c['FON_NomPHP'], $valeur)) {
            return $c['CNS_MessageErreur'] ?: 'Consigne non respectée.';
        }
    }

    return null;
}