# ТЗ: Telegram-бот с записью и оплатой

Версия 1, 6 ноября 2026. Дополнение к статье:
https://alexeymuzyka.com/articles/telegram-bot-zapis-i-oplata/

Это шаблон для своего проекта. Незаданные условия выяснить у владельца.
Не копировать цены, налоговые параметры и правила другого продавца.

## 1. Интервью владельца

До кода заполнить:
- Услуга, получатель результата, продолжительность: [ответ].
- Цена и валюта, предоплата или полная оплата: [ответ].
- Продавец, подтверждённый провайдер и допустимый сценарий оплаты: [ответ].
- Категория услуги и применимые правила Telegram: [подтверждение].
- Кто согласует время, часовой пояс, рабочие часы: [ответ].
- Когда начинается обязательство перед клиентом: [ответ].
- Срок оплаты, отмена, перенос, возврат: [ответ].
- Кто разбирает спорные платежи и куда пишет клиент: [ответ].
- Где работает сервер, кто обслуживает и восстанавливает базу: [ответ].
- Какие данные клиента нужны, кто видит их и когда они удаляются: [ответ].
- Способ выдачи чеков и параметры, согласованные бухгалтером: [ответ].

Секреты в этот файл не вставлять.

## 2. Первая версия

Один владелец, одна услуга, одна валюта, один платёжный провайдер.
Клиент оставляет заявку. Владелец назначает время. Бот отправляет ссылку
оплаты. Подтверждение провайдера отмечает платёж. Встреча синхронизируется
с отдельным календарём. Уведомления об ошибках получает владелец.

До реализации выбрать порядок назначения и оплаты; не считать его
универсальным. Автопродление, массовые рассылки и самостоятельный выбор
слотов в первую версию не входят.

## 3. Данные и состояния

Заявка: внутренний id, Telegram id, услуга, согласованная цена и валюта,
время с часовым поясом, состояние согласования и отдельная отметка оплаты.
Платёж: внутренний id попытки, заявка, провайдер, внешний id, сумма,
валюта, test, ключ идемпотентности, статус, даты проверок.

Показать таблицу переходов до кода. Отмена встречи не означает возврат
денег. Возврат денег не должен молча удалять историю заявки.
Сбой доставки сообщения не отменяет сохранённую оплату.

## 4. Платёж

Схема redirect по API ЮKassa: сумму вычисляет сервер; платёжные данные
вводятся на стороне провайдера. Не хранить номер карты и защитный код.
Создать запись попытки до внешнего вызова. Повтор запроса после потери
ответа использует тот же ключ идемпотентности.

Webhook принимает уведомление, перечитывает объект по API своего магазина,
сверяет id, принадлежность заявке, сумму, валюту и тестовый режим.
Статус return_url и слова клиента не подтверждают деньги.
Повтор и параллельная доставка не меняют оплаченное состояние дважды.
Нужна сверка зависших попыток после сбоя и перезапуска.

## 5. Календарь

Источник времени — заявка. Постоянный id события связан с ней.
Перенос меняет событие; правила удаления согласовать с владельцем.
Ошибка Google не теряет заявку, сохраняется для повтора и видна владельцу.
Meet подключать отдельно, с нужным согласием; предусмотреть ручную ссылку.
Указать, кто и каким каналом отправляет ссылку клиенту.

## 6. Приёмка

Приложить протокол проверок из test-payment.md: действие, ожидаемый
результат, фактический результат, команда воспроизведения.
Сначала заявка без денег, затем тестовый магазин, затем календарь.
Проверить восстановление тестовой базы из резервной копии.
Боевые платежи, смена ключей и публикация требуют отдельного решения
владельца после демонстрации результата.

## 7. Расширение: самостоятельные слоты

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

## 8. Что агент передаёт владельцу

Команды запуска и остановки, автоматические проверки, протокол ручной
приёмки, имена настроек без значений, адрес состояния, журнал ошибок,
порядок резервного копирования, восстановления и временного закрытия оплат.

Источники для проверки актуальных требований:
- https://yookassa.ru/developers/payment-acceptance/getting-started/quick-start
- https://yookassa.ru/developers/using-api/webhooks
- https://yookassa.ru/developers/payment-acceptance/testing-and-going-live/testing
- https://yookassa.ru/developers/payment-acceptance/receipts/54fz/yoomoney/basics
- https://core.telegram.org/bots/payments