MAX/README.md

MAX Bot + n8n (СПРФ / Клиент)

Интеграция бота в мессенджере MAX с n8n: webhook, нормализация входящих, отправка сообщений и кнопок, работа с БД (PostgreSQL, схемы sprf_ / clpr_).

Содержимое репозитория

Скрипты

Файл	Назначение
register_max_webhook.py	Регистрация webhook бота MAX на URL n8n (читает .env: MAX_BOT_TOKEN, N8N_MAX_WORKFLOW, MAX_WEBHOOK_SECRET).
fetch_schema.py	Выгрузка структуры таблиц sprf_* из PostgreSQL в sprf_tables_schema.md.
git-push.sh	Пуш в Gitea без ввода пароля: читает GITEA_USER, GITEA_PASSWORD, GITEA_URL из .env, пушит в origin main, затем убирает пароль из remote. Можно просто сказать «запуш» — тогда выполнится этот скрипт (после add/commit при необходимости).

Ноды для n8n (Code node)

Файл	Назначение
n8n-code-node-max-normalize.js	Нормализация входящего Webhook MAX: один объект с max_id, max_chat_id, answer_text, answer_type (text, command, callback, contact, voice, photo, file и т.д.), callback_id, callback_message_text, contact_payload и др. Личные чаты (dialog); при callback пользователь берётся из callback.user.
n8n-code-add-menu-buttons.js	Формирование тела сообщения с меню: текст + inline_keyboard (callback-кнопки, request_contact, кнопка «Главное меню» type message). Выход: message_body для POST /messages.

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

Путь	Описание
docs/max-webhook.md	Настройка Webhook в n8n, регистрация в MAX, отправка ответа (POST /messages), ответ на callback (POST /answers), удаление кнопок.
docs/max-curl-http-request.md	Примеры curl и настройка HTTP Request в n8n: отправка сообщения, кнопки, ответ на callback, удаление кнопок.
docs/max-api/	Локальная копия/выжимка MAX Bot API: обзор, методы (messages, updates, subscriptions, answers), объекты (Update, Message, MessageBody, NewMessageBody), форматы текста (markdown/html), кнопки (inline_keyboard: callback, message, link, request_contact и др.), контакт (vcf_info, max_info).
docs/clpr-vs-sprf-schema-diff.md	Сравнение структуры таблиц БД с префиксами clpr_ и sprf_.
SITUATION.md	Текущая ситуация: что настроено, команды, файлы.

Схемы БД

Файл	Описание
sprf_tables_schema.md	Структура таблиц с префиксом sprf_ (public).
clpr_tables_schema.md	Структура таблиц с префиксом clpr_ (public).

Требования

• Python 3, зависимости: psycopg2-binary (для fetch_schema).
• В корне файл .env (не коммитить): MAX_BOT_TOKEN, N8N_MAX_WORKFLOW, MAX_WEBHOOK_SECRET, при необходимости MAX_API_BASE; для выгрузки схемы: PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD.

Быстрый старт

1. Настроить Webhook в n8n (path = sprf_max, POST), включить воркфлоу.
2. Выполнить: python3 register_max_webhook.py.
3. В воркфлоу после Webhook вставить Code node с содержимым n8n-code-node-max-normalize.js.
4. Ответ пользователю: HTTP Request — POST https://platform-api.max.ru/messages?user_id={{ $json.max_id }}, body из message_body или свой JSON (текст, кнопки — см. docs).

Подробнее: docs/max-webhook.md, docs/max-curl-http-request.md, docs/max-api/04-formats-and-buttons.md.

Ограничения MAX API

• Редактирование (PUT /messages) и удаление (DELETE /messages) — только для сообщений моложе 24 часов.
• POST /answers (обновление сообщения с кнопками) — по факту тоже редактирование; при старше 24 ч может не сработать.

Git

Репозиторий на ветке main, remote origin → Gitea.

Пуш без ввода пароля: скрипт ./git-push.sh читает GITEA_USER, GITEA_PASSWORD, GITEA_URL из .env и пушит в origin main. Пароль в URL после push убирается. Креды в репозиторий не попадают (.env в .gitignore).

cd /dev/MAX
./git-push.sh

В чате с ассистентом: можно сказать «запуш» — будут сделаны git add, git commit (если есть изменения) и выполнен ./git-push.sh. Пароль вводить не нужно, используются креды из .env.

Лицензия / конфиденциальность

Скрипты и доки — для внутреннего использования. Не коммитить .env и токены.