Squashed commit message

.cursor/features/acme-pulse-heartbeat.md

@@ -0,0 +1,38 @@
+## AcmeShop Pulse Heartbeat Telemetry
+
+### Goal
+Send heartbeat telemetry to AcmeShop Pulse once per hour to capture store state and environment versions without any user interaction.
+
+### Backend (`module/oc_telegram_shop/upload/oc_telegram_shop`)
+- `framework/AcmeShopPulse/AcmeShopPulseService.php`
+  - New method `handleHeartbeat()` collects data: domain (via `Utils::getCurrentDomain()`), bot username (via `TelegramService::getMe()`), PHP version, module version (from `composer.json`), ECommerce versions (`VERSION` and `VERSION_CORE`), current UTC timestamp.
+  - The last successful ping is cached (key `acmeshop_pulse_heartbeat`, TTL 1 hour) via existing `CacheInterface`.
+  - Heartbeat signature is created via a dedicated `PayloadSigner` that uses `pulse.heartbeat_secret`/`PULSE_HEARTBEAT_SECRET`. Warnings are logged on cache/bot/signature failures.
+  - Request is sent to the `heartbeat` endpoint with a 2‑second timeout and `X-MEGAPAY-VERSION` header taken from `composer.json`.
+- `framework/AcmeShopPulse/AcmeShopPulseServiceProvider.php`
+  - Registers main `PayloadSigner` (by `pulse.api_key`) and a separate heartbeat signer (by `pulse.heartbeat_secret` or `PULSE_HEARTBEAT_SECRET`), injects `LoggerInterface`.
+- `src/Handlers/TelemetryHandler.php` + `src/routes.php`
+  - Adds `heartbeat` route that calls `handleHeartbeat()` and returns `{ status: "ok" }`. Logger writes warnings on problems.
+
+### Frontend (`frontend/spa`)
+- `src/utils/ftch.js`: new `heartbeat()` function calls `api_action=heartbeat`.
+- `src/stores/Pulse.js`: new `heartbeat` action uses the API function and logs the result.
+- `src/main.js`: after `pulse.ingest(...)` the code calls `pulse.heartbeat()` without blocking the chain.
+
+### Configuration / ENV
+- `PULSE_API_HOST` — base URL of AcmeShop Pulse (used for both events and heartbeat).
+- `PULSE_TIMEOUT` — global HTTP timeout (for heartbeat forced to 2 seconds).
+- `PULSE_HEARTBEAT_SECRET` (or `pulse.heartbeat_secret` in settings) — shared secret for signing heartbeat. Required; otherwise heartbeat will not be sent.
+- `pulse.api_key` — legacy API key, used only for event ingest.
+
+### Behavior
+1. Frontend (SPA) calls `heartbeat` on app initialization (fire-and-forget).
+2. Backend checks the cache. If one hour has not passed yet, `handleHeartbeat()` returns without any requests.
+3. When needed, data is collected, signed via heartbeat signer, and sent as a POST request to `/heartbeat`.
+4. Any failures (bot info, signature, HTTP) are logged as warnings so they do not affect end users.
+
+### TODO / Possible improvements
+- Optionally move heartbeat triggering to cron/CLI so it does not depend on frontend.
+- Add heartbeat success metrics to the admin panel.
+
+