74 lines
5.5 KiB
Markdown
74 lines
5.5 KiB
Markdown
# 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).
|
||
|
||
```bash
|
||
cd /dev/MAX
|
||
./git-push.sh
|
||
```
|
||
|
||
**В чате с ассистентом:** можно сказать **«запуш»** — будут сделаны `git add`, `git commit` (если есть изменения) и выполнен `./git-push.sh`. Пароль вводить не нужно, используются креды из .env.
|
||
|
||
## Лицензия / конфиденциальность
|
||
|
||
Скрипты и доки — для внутреннего использования. Не коммитить .env и токены.
|