interview-demo-code/.cursor/features/telecart-pulse-heartbeat.md

TeleCart Pulse Heartbeat Telemetry

Цель

Раз в час отправлять телеметрию (heartbeat) на TeleCart Pulse, чтобы фиксировать состояние магазина и версии окружения без участия пользователя.

Backend (module/oc_telegram_shop/upload/oc_telegram_shop)

• framework/TeleCartPulse/TeleCartPulseService.php
  • Новый метод handleHeartbeat() собирает данные: домен (через Utils::getCurrentDomain()), username бота (через TelegramService::getMe()), версии PHP, модуля (из composer.json), OpenCart (VERSION и VERSION_CORE), текущий UTC timestamp.
  • Последний успешный пинг кешируется (ключ telecart_pulse_heartbeat, TTL 1 час) через существующий CacheInterface.
  • Подпись heartbeat выполняется через отдельный PayloadSigner, который использует секрет pulse.heartbeat_secret/PULSE_HEARTBEAT_SECRET. Логируются предупреждения при ошибках кеша/бота/подписи.
  • Отправка идет на эндпоинт heartbeat с таймаутом 2 секунды и заголовком X-TELECART-VERSION, взятым из composer.json.
• framework/TeleCartPulse/TeleCartPulseServiceProvider.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 TeleCart 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 в админку.