# TG-Max Sniffer

> Self-hosted сервис для автоматического анализа сообщений из чатов
> Telegram и Max с помощью ChatGPT (или любой OpenAI-совместимой модели)
> по гибкому CRON-расписанию.

Платформа принимает сообщения через вебхуки Telegram Bot API и Max Bot API,
сохраняет их в MySQL и в назначенное расписанием время выполняет анализ
через OpenAI Chat Completions API. Результат отправляется в указанный
чат-получатель — Telegram, Max или личный диалог.

## Ключевые компоненты

- `webhook` (PHP 8.2 + Apache) — приём вебхуков Telegram и Max
- `cron` (PHP CLI) — планировщик задач на основе CRON-выражений
- `mysql` — хранение сообщений, задач, результатов, ботов и чатов
- `logviewer` — веб-просмотр логов планировщика (localhost-only)
- Админ-панель (отдельный проект) — управление задачами, ботами и результатами

## Основные возможности

- Поддержка Telegram и Max в единой модели данных
- CRON-выражения из 5 полей (Linux-стиль): `*`, диапазоны `1-5`,
  перечисления `1,3,5`, шаги `*/5`
- Шаблоны промптов с плейсхолдером `{messages:status=unprocessed;since=2h;accounts=111,222}`
- Совместимость с OpenAI API, Azure OpenAI, LM Studio, Ollama
- Самостоятельный выбор GPT-модели для каждой задачи
- Учёт `prompt_tokens` / `completion_tokens` / стоимости
- Несколько задач могут читать один батч сообщений (флаг `mark=0`)
- Подавление пустых ответов (фраза «Нет сигнала» не отправляется)
- Защита от двойного запуска в одну минуту
- Docker Compose и Kubernetes-манифесты

## Типичные сценарии применения

1. Утренние дайджесты рабочих чатов (CRON `0 9 * * 1-5`)
2. Мониторинг чатов поддержки клиентов (CRON `*/15 9-18 * * 1-5`)
3. Аналитика комьюнити и аудитории (CRON `0 18 * * 5`)
4. Контроль активности удалённых команд (CRON `0 19 * * 1-5`)
5. Алерты по ключевым словам и упоминаниям (CRON `*/5 * * * *`)
6. Сводки вопросов учеников в образовательных чатах (CRON `0 21 * * *`)

## Структура БД

- `messengers(id, code, name)` — telegram, max
- `bots(id, messenger_id, name, token, webhook_secret, is_active)`
- `chats(id, bot_id, external_id, title, type, is_active)`
- `messages(id, chat_id, external_message_id, sender_external_id,
   sender_name, text, sent_at, is_processed, processed_at, run_id)`
- `scheduled_tasks(id, chat_id, name, cron_expression, prompt_template,
   system_prompt, gpt_model, target_bot_id, target_chat_external_id,
   is_active, last_run_at)`
- `analysis_runs(id, chat_id, task_id, started_at, completed_at,
   period_from, period_to, messages_count, status, error_message)`
- `analysis_results(id, run_id, gpt_model, system_prompt, request_text,
   response_text, prompt_tokens, completion_tokens, total_tokens)`

## URL вебхуков

- Telegram: `https://<host>/telegram.php?bot_id=<ID>`
- Max:      `https://<host>/max.php?bot_id=<ID>`

## Переменные окружения

`DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS, OPENAI_API_KEY, OPENAI_API_URL,
OPENAI_DEFAULT_MODEL, CHECK_INTERVAL_SECONDS, TELEGRAM_API_BASE_URL,
WEBHOOK_PORT, LOGVIEWER_PORT`

## Документация

- README.md — общее описание, быстрый старт, примеры задач
- cron/PLACEHOLDER_SYNTAX.md — синтаксис `{messages:...}` и CRON-выражений
- DASHBOARD_QUERIES.md — 13 готовых SQL-запросов для дашборда

## Лицензия и приватность

Self-hosted: все данные хранятся в собственной MySQL пользователя.
В третьи руки уходит только то, что отправляется в выбранный LLM-провайдер
(OpenAI, Azure OpenAI или локальная модель).