Перейти к содержанию
16 минут чтения
Тема: Практика Telegram Bot API · Согласование · Права доступа

Как сделать согласование заявок через Telegram-бота

Для примера сотрудник запрашивает покупку двух мониторов. Руководитель получает карточку в личном чате с ботом и выбирает «Одобрить» или «Отклонить». При отказе бот просит указать причину. Итог остаётся в базе вместе с версией заявки и ID согласующего.

Храним заявку, версию и согласующего

Для заявки храните ID, версию, автора, назначенного согласующего, сумму и статус pending, approved или rejected. Сохраняйте данные каждой отправленной на согласование версии. Назначение руководителя вычисляйте на сервере по подразделению и правилам компании.

Свяжите аккаунт руководителя с Telegram ID через подтверждённую привязку. Сохраните ID личного чата после начала диалога с ботом. Имя пользователя и доступ к сообщению сами по себе не дают права принимать решение. Для привязки можно использовать сценарий привязки Telegram к аккаунту сайта.

После изменения цены, состава закупки или согласующего увеличьте версию, сбросьте открытый черновик решения и отправьте новую карточку. Старый комментарий относится к прежней версии.

Определяем правила до отправки карточки

Согласуйте с владельцем процесса, кто принимает решение, в каких пределах и что происходит при отсутствии руководителя. Для примера с мониторами установим одного согласующего на версию заявки. Если стоимость превышает его полномочия, назначаем сотрудника с нужным лимитом до отправки карточки.

Правила должны учитывать автора заявки. Если самосогласование запрещено, проверьте это на сервере при назначении и повторно при решении. Скрытая кнопка в интерфейсе сотрудника не защищает обработчик от прямого запроса.

Замещение руководителя оформляйте явным назначением с периодом действия. После переназначения увеличьте версию заявки, закройте черновики комментариев и выпустите новую карточку. Тогда ответ отсутствующего руководителя на старое сообщение не сможет завершить текущий процесс.

Определите и правила повторной подачи. После отказа сотрудник может исправить состав покупки и создать следующую версию. Прошлый отказ и его причина остаются в истории. Если согласование многоступенчатое, храните решения по этапам и переходите к следующему после фиксации предыдущего. Далее в примере используется один этап.

Отправляем карточку и принимаем нажатие

Покажите номер заявки, версию, автора, сумму и краткое описание. Ниже часть reply_markup для sendMessage. Токен K7zP4m2Q условный. Сгенерируйте для карточки случайный токен, сохраните его с ID заявки, версией, согласующим, чатом и сроком действия.

JSON · reply_markup карточки
{
  "inline_keyboard": [
    [
      { "text": "Одобрить", "callback_data": "approve:K7zP4m2Q" },
      { "text": "Отклонить", "callback_data": "reject:K7zP4m2Q" }
    ]
  ]
}

В обработчике проверенного обновления разберите действие и токен. У callback_data есть ограничение 1–64 байта. Возьмите Telegram ID из callback_query.from.id и проверьте его связь с назначенным сотрудником, личный чат, срок действия и версию карточки. Если данных сообщения для проверки чата нет, попросите открыть актуальную карточку в личном чате.

Ответьте на каждое нажатие через answerCallbackQuery, чтобы Telegram убрал индикатор ожидания. При долгой обработке подтвердите получение нажатия и покажите итог после сохранения.

Запрашиваем комментарий к решению

В примере «Одобрить» фиксирует решение сразу. «Отклонить» создаёт черновик отказа и запрашивает комментарий. Для подсказки можно использовать ForceReply. После отправки сохраните ID сообщения с запросом причины, ID черновика, версию заявки, чат, согласующего и срок.

Карточка закупки №142 с кнопками Одобрить и Отклонить; после Reply с причиной появляется окончательный отказ без кнопок.
Карточка закупки №142 с кнопками Одобрить и Отклонить; после Reply с причиной появляется окончательный отказ без кнопок.
Схема по статье: кнопки и запрос причины — из JSON. Сумма, автор и текст ответа вымышлены. Это не снимок Telegram.

Принимайте текст как ответ на конкретный запрос комментария. Сверяйте reply_to_message.message_id, чат и отправителя. Проверьте длину и убедитесь, что после удаления пробелов причина осталась непустой. Пока комментарий не принят, заявка остаётся в ожидании.

При поступлении причины заново проверьте права и версию. Если заявку изменили, решение уже принято или срок вышел, сообщите об этом и предложите открыть актуальную карточку. Если правила требуют комментарий и для одобрения, используйте тот же сценарий с отдельным действием.

Ниже пример тела sendMessage для запроса причины. ID чата и номер заявки условные. После успешной отправки сохраните result.message_id вместе с черновиком отказа. Параметр force_reply открывает интерфейс ответа, а сервер связывает пришедший комментарий с конкретным запросом.

JSON · запрос причины отказа
{
  "chat_id": 123456789,
  "text": "Укажите причину отказа по заявке №142 ответом на это сообщение.",
  "reply_markup": {
    "force_reply": true,
    "input_field_placeholder": "Например, уточните комплектацию"
  }
}

Дайте руководителю возможность отменить ввод причины. В таком случае закрывайте только черновик решения, а заявку оставляйте в pending. Если срок комментария истёк, новый ответ на старое сообщение предложит повторно открыть карточку. Для одного сотрудника могут существовать несколько черновиков по разным заявкам, поэтому связывать ответ только с последним действием пользователя недостаточно.

Сохраняем решение и историю одной транзакцией

Одинаковый обработчик завершает одобрение и отказ. Начните транзакцию, подтвердите актуальное право сотрудника согласовывать покупки и проверьте данные черновика, если он нужен. Если права могут измениться параллельно, используйте блокировку записи назначения или полномочий по общему правилу вашей БД. Связь с Telegram и ограничение по сумме проверяйте по серверным данным.

Ниже фрагмент для PostgreSQL. :actor_id — внутренний ID сотрудника, полученный после проверки привязки. :decision принимает одно из двух итоговых состояний. В approval_events храните неизменяемую запись с предыдущим и новым состоянием, автором, версией, временем и комментарием.

SQL · условное решение и запись в историю
WITH decided AS (
    UPDATE purchase_requests
    SET status = :decision
    WHERE id = :request_id
      AND version = :card_version
      AND status = 'pending'
      AND approver_id = :actor_id
    RETURNING id, version, status, approver_id
)
INSERT INTO approval_events
    (request_id, request_version, previous_status, decision, actor_id, comment, decided_at)
SELECT id, version, 'pending', status, approver_id, :comment, CURRENT_TIMESTAMP
FROM decided
RETURNING id;

Передавайте параметры через подготовленный запрос. Если вернулся ID события, сохраните задания на уведомление автора и обновление карточки в той же транзакции. Если строка не вернулась, перечитайте состояние и сообщите, что карточка устарела или решение уже принято. Второе одновременное нажатие не должно записать второе решение для той же версии.

Ограничение UNIQUE(request_id, request_version) у таблицы итоговых решений закрепляет один итог на версию. Если храните в той же истории и прочие действия, примените уникальность только к итоговым записям либо вынесите их в отдельную таблицу.

Разбираем решение на одной заявке

Сотрудник отправил заявку №142 на два монитора общей стоимостью 48 000 рублей. В базе сохранена версия 3, назначен руководитель отдела, а в Telegram отправлена карточка именно этой версии. Руководитель нажимает «Отклонить» и получает запрос причины.

Пока он пишет комментарий, сотрудник изменяет комплектацию. Сервер сохраняет версию 4 и отправляет новую карточку. Комментарий руководителя приходит ответом на запрос для версии 3. Обработчик видит несовпадение версии и предлагает рассмотреть обновлённую заявку. Состояние версии 4 остаётся pending.

Если изменения не было, сервер проверяет полномочия руководителя и сохраняет отказ с комментарием. В журнале остаются версия 3, прежнее состояние pending, итог rejected, ID руководителя и время решения. После фиксации бот уведомляет автора и обновляет карточку.

Повтор того же обновления или второе нажатие уже не меняют решение. При двух разных решениях, поступивших почти одновременно, условный UPDATE допускает только первый переход из pending. Второй обработчик читает итог и сообщает его пользователю.

Обновляем карточку и уведомляем автора

После фиксации уберите кнопки через editMessageReplyMarkup и покажите статус. Если карточку удалили или редактирование не удалось, сохранённое решение остаётся в силе. На повторное нажатие ответьте текущим статусом. Проверка состояния в БД применяется и к кнопкам, которые остались видны.

Отдельное уведомление автору связывайте с ID события решения, чтобы повторы задачи не создавали новых исходящих операций. В сообщении укажите номер, итог и комментарий, если он предназначен автору. Для проверки запросов кнопок пригодится разбор callback_query.

Отделяем историю решения от доставки уведомлений

История должна позволять восстановить содержание заявки на момент решения. Вместе с номером версии храните снимок позиций и суммы либо ссылку на неизменяемую версию. Текущая карточка сотрудника может измениться позже, поэтому одного итогового статуса недостаточно.

В событии решения сохраняйте внутренний ID сотрудника и подтверждённый Telegram ID. Имя в сообщении удобно для чтения, но оно может измениться. Комментарий храните как текст и экранируйте при отображении на сайте. Если используете HTML-разметку Telegram, экранируйте комментарий и перед отправкой.

У уведомления о решении должен быть свой статус доставки. Например, заявка уже approved, а сообщение автору не отправилось из-за блокировки бота. Покажите это оператору и оставьте возможность повторить уведомление. Решение при этом остаётся зафиксированным.

Если требуется отменить принятое решение, оформите отдельное действие с правами, причиной и новой записью истории. Это позволит увидеть, кто и почему изменил итог. Редактирование старой строки истории лишает процесс такой возможности.

Реализуем проверку полномочий и фиксацию решения

Для примера ниже нужны PHP с pdo_pgsql и mbstring, а также PostgreSQL. Создадим минимальные таблицы для сотрудников, заявок, решений и исходящих задач. Суммы храним в копейках. Telegram ID сотрудника попадает в approval_members только после подтверждённой привязки; из callback нельзя принимать внутренний actor_id.

SQL · минимальная схема согласования
CREATE TABLE approval_members (
  id bigserial PRIMARY KEY, telegram_user_id bigint UNIQUE NOT NULL,
  active boolean NOT NULL DEFAULT true, limit_minor bigint NOT NULL CHECK (limit_minor >= 0)
);
CREATE TABLE purchase_requests (
  id bigserial PRIMARY KEY, version integer NOT NULL DEFAULT 1,
  author_id bigint NOT NULL, approver_id bigint NOT NULL REFERENCES approval_members(id),
  total_minor bigint NOT NULL CHECK (total_minor >= 0), snapshot jsonb NOT NULL,
  status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected'))
);
CREATE TABLE approval_events (
  id bigserial PRIMARY KEY, request_id bigint NOT NULL REFERENCES purchase_requests(id),
  request_version integer NOT NULL, previous_status text NOT NULL, decision text NOT NULL,
  actor_id bigint NOT NULL, telegram_user_id bigint NOT NULL,
  comment text NOT NULL, decided_at timestamptz NOT NULL,
  UNIQUE (request_id, request_version)
);
CREATE TABLE approval_outbox (
  event_id bigint NOT NULL REFERENCES approval_events(id), kind text NOT NULL,
  state text NOT NULL DEFAULT 'pending', PRIMARY KEY (event_id, kind)
);

snapshot содержит состав покупки на согласование. Если разрешаете изменять заявку, сохраняйте снимки всех версий в отдельной таблице до изменения текущей строки. В простом варианте ниже после итогового решения заявка неизменяема. Для повторной подачи создаётся новая заявка со ссылкой на предыдущую.

PHP · decision.php
<?php
declare(strict_types=1);

function decidePurchase(PDO $db, int $telegramId, int $requestId, int $version,
    string $decision, string $comment = ''): ?int
{
    if (!in_array($decision, ['approved', 'rejected'], true)) {
        throw new InvalidArgumentException('Неизвестное решение');
    }
    $comment = trim($comment);
    if (mb_strlen($comment) > 2000 || ($decision === 'rejected' && $comment === '')) {
        throw new InvalidArgumentException('Укажите причину отказа длиной до 2000 символов');
    }
    $db->beginTransaction();
    try {
        $q = $db->prepare('SELECT id, limit_minor FROM approval_members
            WHERE telegram_user_id = ? AND active = true FOR UPDATE');
        $q->execute([$telegramId]);
        $actor = $q->fetch(PDO::FETCH_ASSOC);
        if (!$actor) {
            $db->commit();
            return null;
        }
        $q = $db->prepare("WITH decided AS (
            UPDATE purchase_requests SET status = :decision
            WHERE id = :request_id AND version = :version AND status = 'pending'
              AND approver_id = :actor_id AND author_id <> :not_author
              AND total_minor <= :limit_minor
            RETURNING id, version, status, approver_id
        )
        INSERT INTO approval_events
            (request_id, request_version, previous_status, decision, actor_id, telegram_user_id, comment, decided_at)
        SELECT id, version, 'pending', status, approver_id, :telegram_id, :comment, CURRENT_TIMESTAMP
        FROM decided RETURNING id");
        $q->execute([
            'decision' => $decision, 'request_id' => $requestId, 'version' => $version,
            'actor_id' => $actor['id'], 'not_author' => $actor['id'],
            'limit_minor' => $actor['limit_minor'], 'telegram_id' => $telegramId, 'comment' => $comment,
        ]);
        $eventId = $q->fetchColumn();
        if ($eventId !== false) {
            $q = $db->prepare("INSERT INTO approval_outbox (event_id, kind)
                VALUES (?, 'notify_author'), (?, 'refresh_card')");
            $q->execute([$eventId, $eventId]);
        }
        $db->commit();
        return $eventId === false ? null : (int) $eventId;
    } catch (Throwable $error) {
        if ($db->inTransaction()) $db->rollBack();
        throw $error;
    }
}

Вызывайте функцию после проверки токена карточки либо черновика комментария. requestId и version берите из найденной серверной записи, telegramId — из отправителя проверенного обновления. Для отказа дополнительно сопоставьте reply_to_message.message_id с сохранённым запросом причины. Функция повторно проверяет текущее назначение, активность, лимит суммы и запрет самосогласования.

Пример вызова для одобрения: decidePurchase($db, $callback['from']['id'], $card['request_id'], $card['version'], 'approved'). Для отказа последний аргумент содержит проверенный текст ответа, а requestId и version берутся из черновика. PDO настройте с ERRMODE_EXCEPTION и отключённой эмуляцией подготовленных запросов. Общая схема приёма callback_query и отправки ответа остаётся описанной выше.

Вернувшийся ID означает, что решение, история и две задачи зафиксированы вместе. null означает, что переход не выполнен: обработчик перечитывает доступную руководителю заявку и показывает текущий статус или предложение открыть новую карточку. При повторе одобрения после уже сохранённого отказа нельзя сообщать «Одобрено» только на основании нажатой кнопки.

Проверьте функцию сначала без отправки сообщений: создайте тестового согласующего с лимитом 5 000 000 копеек и заявку другого автора на 4 800 000. Первое одобрение создаст одно событие и две исходящие задачи, повтор вернёт null. Для другой заявки уменьшите лимит, отключите сотрудника или измените версию — решение не должно сохраниться. Воркер отправки читает событие и получателя из серверных данных; ошибка доставки не откатывает решение.

Проверяем права, старые кнопки и повторы

  • В личном чате руководителя отклоните заявку. До ввода причины статус должен оставаться pending. После ответа проверьте итог и текст в истории.

  • Обработайте действие от другого тестового аккаунта. Состояние заявки не должно измениться.

  • Поменяйте сумму или назначение и нажмите кнопку прежней версии. Бот должен предложить открыть актуальную карточку.

  • Отправьте два решения для одной версии почти одновременно. Проверьте одну итоговую запись, один набор исходящих задач и статус, соответствующий первому сохранённому решению.

CallbackQuery · ForceReply · editMessageReplyMarkup · Изменяющие CTE в PostgreSQL