Merge pull request #386 from JLG-WOCFR-DEV/codex/implement-common-helper-for-scan-history

JLG-WOCFR-DEV · web-flow · commit 4670d24cdba9 · 2025-10-14T14:03:51.000+02:00
Log scan resets and expose reset hooks
diff --git a/README.md b/README.md
@@ -162,6 +162,24 @@ add_action('blc_link_mass_update_performed', function (array $context) {
 });
 ```
 
+### `blc_link_scan_status_reset` et `blc_image_scan_status_reset`
+Ces actions sont déclenchées lorsqu’un administrateur remet à zéro l’état du scanner (liens ou images). Une entrée est automatiquement ajoutée dans l’historique persistant (`blc_link_scan_history` / `blc_image_scan_history`) avec le motif `reset`, l’horodatage et l’utilisateur à l’origine de l’action. Les tableaux de bord peuvent ainsi suivre les remises à zéro manuelles, corréler l’évènement avec une reprise de scan et notifier les équipes de support.
+
+```php
+add_action('blc_link_scan_status_reset', function (array $historyEntry, array $context) {
+    error_log(sprintf(
+        '[BLC] Réinitialisation du scan liens (%s) par %s',
+        gmdate('c', $historyEntry['timestamp']),
+        $historyEntry['user']['display_name'] ?: $historyEntry['user']['login']
+    ));
+});
+
+add_action('blc_image_scan_status_reset', function (array $historyEntry) {
+    // Exemple : pousser l’évènement dans un tableau de bord interne.
+    my_dashboard()->pushEvent('blc_image_reset', $historyEntry);
+});
+```
+
 ## Pistes d'amélioration
 
 - **Intégration de rapports automatisés** : proposer un export planifié (PDF/CSV ou envoi vers Google Sheets) afin de partager les résultats des scans avec des équipes éditoriales sans accès à l’administration.
diff --git a/docs/roadmap-ameliorations.md b/docs/roadmap-ameliorations.md
@@ -52,6 +52,7 @@ Cette feuille de route décline les pistes d'amélioration listées dans le `REA
 1. Créer un composant `DashboardSummary` réutilisable avec données issues de `blc_get_link_scan_status_payload()`.
 2. Ajouter des tests d'accessibilité automatisés (axe-core) et corriger les problèmes détectés.
 3. Documenter une charte UX (taille des cibles tactiles, contrastes, animations).
+4. Aligner la timeline sur les événements `blc_link_scan_status_reset` / `blc_image_scan_status_reset` afin d'afficher les remises à zéro manuelles directement dans les dashboards.
 
 > ✅ Le composant `DashboardSummary` affiche désormais l’état du scan, la progression et le rythme d’analyse à partir de `blc_get_link_scan_status_payload()` et se met à jour en temps réel, avec un habillage visuel dédié. 【F:liens-morts-detector-jlg/includes/blc-admin-pages.php†L688-L780】【F:liens-morts-detector-jlg/assets/js/blc-admin-scripts.js†L2554-L3726】【F:liens-morts-detector-jlg/assets/css/blc-admin-styles.css†L120-L236】
 
diff --git a/liens-morts-detector-jlg/includes/blc-scanner.php b/liens-morts-detector-jlg/includes/blc-scanner.php
@@ -1119,11 +1119,24 @@ function blc_update_link_scan_status(array $changes) {
     /**
      * Clear the stored link scan status.
      *
+     * @param array<string, mixed>|mixed $context Optional additional context forwarded to observers.
+     *
      * @return void
      */
-    function blc_reset_link_scan_status() {
+    function blc_reset_link_scan_status($context = []) {
+        $context = is_array($context) ? $context : [];
+
+        $history_entry = null;
+        if (function_exists('blc_record_scan_reset')) {
+            $history_entry = blc_record_scan_reset('link', $context);
+        }
+
         delete_option('blc_link_scan_status');
         blc_link_scan_status_cache(null, true);
+
+        if (function_exists('do_action')) {
+            do_action('blc_link_scan_status_reset', $history_entry, $context);
+        }
     }
 }
 
@@ -1315,6 +1328,82 @@ function blc_update_image_scan_history_entry($job_id, array $changes) {
     }
 }
 
+if (!function_exists('blc_record_scan_reset')) {
+    /**
+     * Record a scan reset event in the persisted history.
+     *
+     * @param string               $dataset_type Either "link" or "image".
+     * @param array<string, mixed> $context      Additional metadata about the reset trigger.
+     *
+     * @return array<string, mixed>|null The recorded history entry when successful, null otherwise.
+     */
+    function blc_record_scan_reset($dataset_type, array $context = []) {
+        $dataset_type = is_string($dataset_type) ? strtolower($dataset_type) : '';
+
+        if ($dataset_type !== '' && function_exists('sanitize_key')) {
+            $dataset_type = sanitize_key($dataset_type);
+        }
+
+        $appenders = [
+            'link'  => 'blc_append_link_scan_history_entry',
+            'image' => 'blc_append_image_scan_history_entry',
+        ];
+
+        if ($dataset_type === '' || !isset($appenders[$dataset_type])) {
+            return null;
+        }
+
+        $user = [
+            'id'           => 0,
+            'login'        => '',
+            'display_name' => '',
+        ];
+
+        if (function_exists('wp_get_current_user')) {
+            $current_user = wp_get_current_user();
+
+            if (is_object($current_user)) {
+                if (isset($current_user->ID)) {
+                    $user['id'] = (int) $current_user->ID;
+                } elseif (function_exists('get_current_user_id')) {
+                    $user['id'] = (int) get_current_user_id();
+                }
+
+                if (isset($current_user->user_login)) {
+                    $user['login'] = (string) $current_user->user_login;
+                }
+
+                if (isset($current_user->display_name)) {
+                    $user['display_name'] = (string) $current_user->display_name;
+                } elseif (isset($current_user->user_nicename)) {
+                    $user['display_name'] = (string) $current_user->user_nicename;
+                }
+            }
+        } elseif (function_exists('get_current_user_id')) {
+            $user['id'] = (int) get_current_user_id();
+        }
+
+        $history_entry = [
+            'event'        => 'reset',
+            'reason'       => 'reset',
+            'dataset_type' => $dataset_type,
+            'timestamp'    => time(),
+            'user'         => $user,
+            'context'      => $context,
+        ];
+
+        $appender = $appenders[$dataset_type];
+
+        if (is_callable($appender)) {
+            call_user_func($appender, $history_entry);
+
+            return $history_entry;
+        }
+
+        return null;
+    }
+}
+
 if (!function_exists('blc_get_image_scan_transition_rules')) {
     /**
      * Describe the allowed state transitions for image scans.
@@ -1618,11 +1707,24 @@ function blc_update_image_scan_status(array $changes) {
     /**
      * Clear the stored image scan status.
      *
+     * @param array<string, mixed>|mixed $context Optional additional context forwarded to observers.
+     *
      * @return void
      */
-    function blc_reset_image_scan_status() {
+    function blc_reset_image_scan_status($context = []) {
+        $context = is_array($context) ? $context : [];
+
+        $history_entry = null;
+        if (function_exists('blc_record_scan_reset')) {
+            $history_entry = blc_record_scan_reset('image', $context);
+        }
+
         delete_option('blc_image_scan_status');
         blc_image_scan_status_cache(null, true);
+
+        if (function_exists('do_action')) {
+            do_action('blc_image_scan_status_reset', $history_entry, $context);
+        }
     }
 }
 
diff --git a/tests/LinkScanStatusTest.php b/tests/LinkScanStatusTest.php
@@ -41,6 +41,13 @@ protected function setUp(): void
         Functions\when('apply_filters')->alias(static fn($hook, $value) => $value);
         Functions\when('do_action')->justReturn(null);
         Functions\when('rest_ensure_response')->alias(static fn($value) => $value);
+        Functions\when('wp_get_current_user')->alias(static function () {
+            return (object) [
+                'ID'           => 0,
+                'user_login'   => '',
+                'display_name' => '',
+            ];
+        });
 
         $testCase = $this;
         Functions\when('get_option')->alias(function ($name, $default = false) use ($testCase) {
@@ -67,6 +74,8 @@ protected function setUp(): void
         if (function_exists('\\blc_reset_image_scan_status')) {
             \blc_reset_image_scan_status();
         }
+
+        $this->getOptionCalls = 0;
     }
 
     protected function tearDown(): void
@@ -449,13 +458,94 @@ public function test_get_link_scan_status_payload_includes_metrics(): void
         $this->assertArrayHasKey('lock_active', $payload);
     }
 
-    public function test_reset_link_scan_status_deletes_option(): void
+    public function test_reset_link_scan_status_records_history_and_fires_hook(): void
     {
         $this->options['blc_link_scan_status'] = ['state' => 'completed'];
 
-        \blc_reset_link_scan_status();
+        Functions\when('time')->justReturn(1_700_000_000);
+        Functions\when('wp_get_current_user')->alias(static function () {
+            return (object) [
+                'ID'           => 7,
+                'user_login'   => 'auditor',
+                'display_name' => 'Audit Bot',
+            ];
+        });
+
+        $fired_actions = [];
+        Functions\when('do_action')->alias(static function ($hook, ...$arguments) use (&$fired_actions) {
+            $fired_actions[] = [$hook, $arguments];
+        });
+
+        $context = ['triggered_by' => 'unit-test'];
+
+        \blc_reset_link_scan_status($context);
 
         $this->assertArrayNotHasKey('blc_link_scan_status', $this->options);
+
+        $history = $this->options['blc_link_scan_history'] ?? [];
+        $this->assertNotEmpty($history);
+        $entry = $history[0];
+
+        $this->assertSame('reset', $entry['event']);
+        $this->assertSame('reset', $entry['reason']);
+        $this->assertSame('link', $entry['dataset_type']);
+        $this->assertSame(1_700_000_000, $entry['timestamp']);
+        $this->assertSame($context, $entry['context']);
+        $this->assertSame([
+            'id'           => 7,
+            'login'        => 'auditor',
+            'display_name' => 'Audit Bot',
+        ], $entry['user']);
+
+        $this->assertNotEmpty($fired_actions);
+        $this->assertSame('blc_link_scan_status_reset', $fired_actions[0][0]);
+        $this->assertSame($entry, $fired_actions[0][1][0]);
+        $this->assertSame($context, $fired_actions[0][1][1]);
+    }
+
+    public function test_reset_image_scan_status_records_history_and_fires_hook(): void
+    {
+        $this->options['blc_image_scan_status'] = ['state' => 'running'];
+
+        Functions\when('time')->justReturn(1_700_000_500);
+        Functions\when('wp_get_current_user')->alias(static function () {
+            return (object) [
+                'ID'           => 42,
+                'user_login'   => 'media-admin',
+                'display_name' => 'Media Admin',
+            ];
+        });
+
+        $fired_actions = [];
+        Functions\when('do_action')->alias(static function ($hook, ...$arguments) use (&$fired_actions) {
+            $fired_actions[] = [$hook, $arguments];
+        });
+
+        $context = ['triggered_by' => 'dashboard'];
+
+        \blc_reset_image_scan_status($context);
+
+        $this->assertArrayNotHasKey('blc_image_scan_status', $this->options);
+
+        $history = $this->options['blc_image_scan_history'] ?? [];
+        $this->assertNotEmpty($history);
+        $entry = $history[0];
+
+        $this->assertSame('reset', $entry['event']);
+        $this->assertSame('reset', $entry['reason']);
+        $this->assertSame('image', $entry['dataset_type']);
+        $this->assertSame(1_700_000_500, $entry['timestamp']);
+        $this->assertSame($context, $entry['context']);
+        $this->assertSame([
+            'id'           => 42,
+            'login'        => 'media-admin',
+            'display_name' => 'Media Admin',
+        ], $entry['user']);
+
+        $this->assertNotEmpty($fired_actions);
+        $this->assertSame('blc_image_scan_status_reset', $fired_actions[0][0]);
+        $this->assertSame($entry, $fired_actions[0][1][0]);
+        $this->assertSame($context, $fired_actions[0][1][1]);
     }
 }
 
