Merge pull request #376 from JLG-WOCFR-DEV/codex/continue-developpement-prioritaire

JLG-WOCFR-DEV · web-flow · commit 36671ba77195 · 2025-10-11T11:36:49.000+02:00
Add image scan metrics instrumentation
diff --git a/docs/ameliorations-et-tests.md b/docs/ameliorations-et-tests.md
@@ -3,7 +3,7 @@
 ## Fonctions prioritaires par rapport aux applications professionnelles
 
 - **`blc_schedule_manual_image_scan`** – Contrairement aux scans de liens, aucun identifiant de job ni compteur de tentatives n'est stocké ; la fonction se contente de lancer `wp_schedule_single_event()` et force `is_full_scan` à `true`, ce qui empêche de distinguer un balayage partiel ou de suivre un historique des relances. Les plateformes pro conservent ces métadonnées pour la supervision et la reprise manuelle. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L381-L460】
-- **`blc_perform_image_check`** – Le contrôleur d'images est exécuté sans instrumentation ni hook de télémétrie. À la différence de `blc_perform_check()`, aucun métrique (durée, throughput, état du lot) n'est publié pour alimenter l'historique ou les dashboards externes, ce qui laisse l'équipe support sans visibilité en cas de scan long ou bloqué. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L3948-L4005】
+- **`blc_perform_image_check`** – Le contrôleur d'images était exécuté sans instrumentation ni hook de télémétrie. À la différence de `blc_perform_check()`, aucun métrique (durée, throughput, état du lot) n'était publié pour alimenter l'historique ou les dashboards externes, ce qui laissait l'équipe support sans visibilité en cas de scan long ou bloqué. ✅ Ce manque est désormais comblé : la fonction publie des métriques structurées et un hook `blc_image_scan_metrics` alignés sur les scans de liens. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L4668-L4744】
 - **`blc_update_image_scan_status`** – La structure de statut n'expose ni `job_id` ni journal des transitions et ne notifie aucun hook dédié lors d'un changement d'état, ce qui complique l'audit et l'alignement avec les processus ITIL utilisés par les suites professionnelles. Harmoniser cette fonction avec `blc_update_link_scan_status()` (machine à états, journalisation) permettrait de tracer finement les scans d'images. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L867-L934】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L557-L666】
 - **`blc_update_image_scan_status`** – La structure de statut n'expose ni `job_id` ni journal des transitions et ne notifie aucun hook dédié lors d'un changement d'état, ce qui complique l'audit et l'alignement avec les processus ITIL utilisés par les suites professionnelles. Harmoniser cette fonction avec `blc_update_link_scan_status()` (machine à états, journalisation) permettrait de tracer finement les scans d'images. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L867-L934】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L557-L666】
 - **`blc_schedule_manual_image_scan`** – Contrairement au parcours des liens, la planification d'images ne retournait aucun identifiant de job ni tentative associée, empêchant de tracer les relances et de synchroniser l'interface avec le scan lancé. Une instrumentation équivalente est attendue côté solutions pro. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L1280-L1358】
@@ -25,6 +25,7 @@
 
 > ✅ `blc_update_image_scan_status` conserve maintenant un journal d'audit (transitions valides/invalides), persiste l'historique des jobs et propage `job_id`, `attempt` et `scheduled_at` pour l'observabilité, offrant un suivi équivalent à celui des scans de liens. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L1109-L1285】【F:tests/LinkScanStatusTest.php†L294-L372】
 > ✅ `blc_schedule_manual_image_scan` génère un identifiant de job déterministe, retente la planification en cas d'échec, journalise le contexte et renvoie les métadonnées nécessaires à l'interface et aux appels AJAX. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L1280-L1366】【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L3698-L3771】
+> ✅ `blc_perform_image_check` journalise désormais la durée, l'état et la progression du lot traité, enregistre un historique `blc_image_scan_metrics_history` persistant et expose le hook `blc_image_scan_metrics` pour la télémétrie externe. 【F:liens-morts-detector-jlg/includes/blc-scanner.php†L742-L779】【F:liens-morts-detector-jlg/includes/blc-scanner.php†L4668-L4744】
 
 ## Tests manuels recommandés
 
diff --git a/liens-morts-detector-jlg/includes/blc-scanner.php b/liens-morts-detector-jlg/includes/blc-scanner.php
@@ -739,6 +739,46 @@ function blc_record_link_scan_metrics(array $metrics) {
     }
 }
 
+if (!function_exists('blc_record_image_scan_metrics')) {
+    /**
+     * Store last image scan metrics for observability dashboards.
+     *
+     * @param array<string, mixed> $metrics
+     *
+     * @return void
+     */
+    function blc_record_image_scan_metrics(array $metrics) {
+        $history = get_option('blc_image_scan_metrics_history', []);
+        if (!is_array($history)) {
+            $history = [];
+        }
+
+        array_unshift($history, $metrics);
+        if (count($history) > 50) {
+            $history = array_slice($history, 0, 50);
+        }
+
+        update_option('blc_image_scan_metrics_history', $history, false);
+
+        if (isset($metrics['job_id'])) {
+            blc_update_image_scan_history_entry($metrics['job_id'], ['metrics' => $metrics]);
+        }
+    }
+}
+
+if (!function_exists('blc_get_image_scan_metrics_history')) {
+    /**
+     * Retrieve the persisted metrics history for image scans.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    function blc_get_image_scan_metrics_history() {
+        $history = get_option('blc_image_scan_metrics_history', []);
+
+        return is_array($history) ? $history : [];
+    }
+}
+
 if (!function_exists('blc_get_link_scan_metrics_history')) {
     /**
      * Retrieve the persisted metrics history for link scans.
@@ -4628,10 +4668,13 @@ function blc_perform_check($batch = 0, $is_full_scan = false, $bypass_rest_windo
 function blc_perform_image_check($batch = 0, $is_full_scan = true) {
     global $wpdb;
 
+    $execution_started_at = microtime(true);
     $table_name = (isset($wpdb) && isset($wpdb->prefix))
         ? $wpdb->prefix . 'blc_broken_links'
         : 'blc_broken_links';
 
+    $result = null;
+
     if (function_exists('blc_ensure_broken_links_table_exists') && !blc_ensure_broken_links_table_exists()) {
         $message = sprintf(
             /* translators: %s: database table name. */
@@ -4652,15 +4695,52 @@ function blc_perform_image_check($batch = 0, $is_full_scan = true) {
         }
 
         if (class_exists('WP_Error')) {
-            return new \WP_Error('blc_missing_broken_links_table', $message);
+            $result = new \WP_Error('blc_missing_broken_links_table', $message);
+        } else {
+            $result = false;
         }
+    } else {
+        $queue = blc_make_image_scan_queue();
+        $controller = blc_make_image_scan_controller($queue);
 
-        return false;
+        $result = $controller->run($batch, $is_full_scan);
+    }
+
+    if (function_exists('is_wp_error') && is_wp_error($result)) {
+        $message = $result->get_error_message();
+
+        blc_update_image_scan_status([
+            'state'      => 'failed',
+            'last_error' => $message,
+            'message'    => $message,
+        ]);
     }
 
-    $queue = blc_make_image_scan_queue();
-    $controller = blc_make_image_scan_controller($queue);
+    $status = blc_get_image_scan_status();
+    $duration_ms = (int) round((microtime(true) - $execution_started_at) * 1000);
+    $job_id = isset($status['job_id']) ? (string) $status['job_id'] : '';
+
+    $metrics = [
+        'job_id'             => $job_id,
+        'batch'              => (int) $batch,
+        'duration_ms'        => $duration_ms,
+        'timestamp'          => time(),
+        'state'              => isset($status['state']) ? (string) $status['state'] : 'unknown',
+        'success'            => !(function_exists('is_wp_error') && is_wp_error($result)) && (!isset($status['state']) || $status['state'] !== 'failed'),
+        'processed_batches'  => isset($status['processed_batches']) ? (int) $status['processed_batches'] : 0,
+        'total_batches'      => isset($status['total_batches']) ? (int) $status['total_batches'] : 0,
+        'processed_items'    => isset($status['processed_items']) ? (int) $status['processed_items'] : 0,
+        'total_items'        => isset($status['total_items']) ? (int) $status['total_items'] : 0,
+        'attempt'            => isset($status['attempt']) ? (int) $status['attempt'] : 0,
+        'is_full_scan'       => isset($status['is_full_scan']) ? (bool) $status['is_full_scan'] : (bool) $is_full_scan,
+    ];
+
+    blc_record_image_scan_metrics($metrics);
 
-    return $controller->run($batch, $is_full_scan);
+    if (function_exists('do_action')) {
+        do_action('blc_image_scan_metrics', $metrics, $result);
+    }
+
+    return $result;
 }
 
diff --git a/tests/BlcScannerTest.php b/tests/BlcScannerTest.php
@@ -1,6 +1,7 @@
 <?php
 
 namespace {
+    require_once __DIR__ . '/../vendor/autoload.php';
     require_once __DIR__ . '/translation-stubs.php';
 
     if (!class_exists('WP_Error')) {
@@ -72,6 +73,21 @@ function is_email($email)
         }
     }
 
+    if (!function_exists('esc_sql')) {
+        function esc_sql($value)
+        {
+            if (is_array($value)) {
+                return array_map('esc_sql', $value);
+            }
+
+            if (is_float($value) || is_int($value)) {
+                return $value;
+            }
+
+            return addslashes((string) $value);
+        }
+    }
+
 
     if (!class_exists('WP_Query')) {
         class WP_Query
@@ -4035,6 +4051,101 @@ public function test_blc_perform_image_check_records_remote_cdn_when_option_enab
         }
     }
 
+    public function test_blc_perform_image_check_records_metrics_history_and_triggers_hook(): void
+    {
+        global $wpdb;
+        $wpdb = $this->createWpdbStub();
+
+        $initialStatus = blc_get_default_image_scan_status();
+        $initialStatus['state'] = 'running';
+        $initialStatus['job_id'] = 'img-job-123';
+        $initialStatus['attempt'] = 2;
+        $initialStatus['processed_batches'] = 1;
+        $initialStatus['total_batches'] = 4;
+        $initialStatus['processed_items'] = 10;
+        $initialStatus['total_items'] = 40;
+        $initialStatus['is_full_scan'] = true;
+        $this->options['blc_image_scan_status'] = $initialStatus;
+        $this->options['blc_image_scan_history'] = [];
+
+        $controllerResult = ['processed' => 40];
+        $controller = new class($controllerResult) {
+            /** @var array<string, mixed> */
+            private array $result;
+
+            /**
+             * @param array<string, mixed> $result
+             */
+            public function __construct(array $result)
+            {
+                $this->result = $result;
+            }
+
+            /**
+             * @param int  $batch
+             * @param bool $is_full_scan
+             *
+             * @return array<string, mixed>
+             */
+            public function run($batch, $is_full_scan)
+            {
+                blc_update_image_scan_status([
+                    'state'             => 'completed',
+                    'processed_batches' => 4,
+                    'total_batches'     => 4,
+                    'processed_items'   => 40,
+                    'total_items'       => 40,
+                    'message'           => 'Scan terminé',
+                ]);
+
+                return $this->result;
+            }
+        };
+
+        \Brain\Monkey\Functions\when('blc_make_image_scan_controller')->alias(fn($queue) => $controller);
+
+        $result = blc_perform_image_check(0, true);
+
+        $this->assertSame($controllerResult, $result, 'Le contrôleur stub doit retourner le payload attendu.');
+
+        $this->assertArrayHasKey('blc_image_scan_metrics_history', $this->updatedOptions, 'Les métriques doivent être historisées.');
+        $history = $this->updatedOptions['blc_image_scan_metrics_history'];
+        $this->assertIsArray($history);
+        $this->assertNotEmpty($history, 'Le premier lot doit enregistrer une entrée de métriques.');
+        $metrics = $history[0];
+        $this->assertSame('img-job-123', $metrics['job_id']);
+        $this->assertSame(0, $metrics['batch']);
+        $this->assertArrayHasKey('duration_ms', $metrics);
+        $this->assertIsInt($metrics['duration_ms']);
+        $this->assertGreaterThanOrEqual(0, $metrics['duration_ms']);
+        $this->assertLessThan(5000, $metrics['duration_ms']);
+        $this->assertSame($this->utcNow, $metrics['timestamp']);
+        $this->assertSame('completed', $metrics['state']);
+        $this->assertTrue($metrics['success']);
+        $this->assertSame(4, $metrics['processed_batches']);
+        $this->assertSame(4, $metrics['total_batches']);
+        $this->assertSame(40, $metrics['processed_items']);
+        $this->assertSame(40, $metrics['total_items']);
+        $this->assertSame(2, $metrics['attempt']);
+        $this->assertTrue($metrics['is_full_scan']);
+
+        $actions = array_filter(
+            $this->triggeredActions,
+            static fn(array $action) => $action['hook'] === 'blc_image_scan_metrics'
+        );
+        $this->assertNotEmpty($actions, 'Le hook blc_image_scan_metrics doit être déclenché.');
+        $lastAction = array_pop($actions);
+        $this->assertSame($metrics, $lastAction['args'][0]);
+        $this->assertSame($controllerResult, $lastAction['args'][1]);
+
+        $this->assertArrayHasKey('blc_image_scan_history', $this->options, 'Le journal des jobs doit être maintenu.');
+        $historyEntries = $this->options['blc_image_scan_history'];
+        $this->assertNotEmpty($historyEntries);
+        $this->assertSame('img-job-123', $historyEntries[0]['job_id']);
+        $this->assertArrayHasKey('metrics', $historyEntries[0], 'Les métriques doivent être attachées à l’entrée du job.');
+        $this->assertSame($metrics, $historyEntries[0]['metrics']);
+    }
+
     public function test_blc_perform_image_check_detects_missing_srcset_variant(): void
     {
         global $wpdb;
