# 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`. |

### Ноды для 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 убирается.

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

Можно сказать «запуш» — тогда будет выполнен этот скрипт (с текущими изменениями нужно сначала сделать `git add` и `git commit`).

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

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