Squashed commit message

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

@@ -0,0 +1,38 @@
+## MegaPay Pulse Heartbeat Telemetry
+
+### Цель
+Раз в час отправлять телеметрию (heartbeat) на MegaPay Pulse, чтобы фиксировать состояние магазина и версии окружения без участия пользователя.
+
+### Backend (`module/oc_telegram_shop/upload/oc_telegram_shop`)
+- `framework/MegaPayPulse/MegaPayPulseService.php`
+  - Новый метод `handleHeartbeat()` собирает данные: домен (через `Utils::getCurrentDomain()`), username бота (через `TelegramService::getMe()`), версии PHP, модуля (из `composer.json`), OpenCart (`VERSION` и `VERSION_CORE`), текущий UTC timestamp.
+  - Последний успешный пинг кешируется (ключ `megapay_pulse_heartbeat`, TTL 1 час) через существующий `CacheInterface`.
+  - Подпись heartbeat выполняется через отдельный `PayloadSigner`, который использует секрет `pulse.heartbeat_secret`/`PULSE_HEARTBEAT_SECRET`. Логируются предупреждения при ошибках кеша/бота/подписи.
+  - Отправка идет на эндпоинт `heartbeat` с таймаутом 2 секунды и заголовком `X-MEGAPAY-VERSION`, взятым из `composer.json`.
+- `framework/MegaPayPulse/MegaPayPulseServiceProvider.php`
+  - Регистрирует основной `PayloadSigner` (по `pulse.api_key`) и отдельный heartbeat signer (по `pulse.heartbeat_secret` или `PULSE_HEARTBEAT_SECRET`), инжектит `LoggerInterface`.
+- `src/Handlers/TelemetryHandler.php` + `src/routes.php`
+  - Добавлен маршрут `heartbeat`, который вызывает `handleHeartbeat()` и возвращает `{ status: "ok" }`. Логгер пишет warning при проблемах.
+
+### Frontend (`frontend/spa`)
+- `src/utils/ftch.js`: новая функция `heartbeat()` вызывает `api_action=heartbeat`.
+- `src/stores/Pulse.js`: добавлен action `heartbeat`, использующий новую API-функцию и логирующий результат.
+- `src/main.js`: после `pulse.ingest(...)` вызывается `pulse.heartbeat()` без блокировки цепочки.
+
+### Конфигурация / ENV
+- `PULSE_API_HOST` — базовый URL MegaPay Pulse (используется и для events, и для heartbeat).
+- `PULSE_TIMEOUT` — общий таймаут HTTP (для heartbeat принудительно 2 секунды).
+- `PULSE_HEARTBEAT_SECRET` (или `pulse.heartbeat_secret` в настройках) — общий секрет для подписания heartbeat. Обязателен, иначе heartbeat не будет отправляться.
+- `pulse.api_key` — прежний API ключ, используется только для event-инджеста.
+
+### Поведение
+1. Frontend (SPA) вызывает `heartbeat` при инициализации приложения (fire-and-forget).
+2. Backend проверяет кеш. Если часа еще не прошло, `handleHeartbeat()` возвращает без запросов.
+3. При необходимости собираются данные, подписываются через heartbeat signer и отправляются POST-запросом на `/heartbeat`.
+4. Любые сбои (bot info, подпись, HTTP) логируются как warning, чтобы не тревожить пользователей.
+
+### TODO / Возможные улучшения
+- При необходимости вынести heartbeat запуск в крон/CLI, чтобы не зависеть от фронтенда.
+- Добавить метрики успешности heartbeat в админку.
+
+