Mk
/
supersam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
supersam/docs/n8n-order-group-delivery-fl...

12 KiB
Raw Blame History

Поток n8n для order_groups

Цель

Supabase хранит состояние доставки, генерирует ссылку для клиента и сохраняет все временные отметки. n8n отвечает за отправку SMS, повторные попытки и перевод зависших групп в ручную обработку.

Короткая ссылка с нашей стороны не нужна. Мы храним полную delivery_link, а сервис SMS сам сокращает ссылку при отправке.

Источник истины

Основная запись находится в public.order_groups.

Важные поля:

  • status - бизнес-готовность группы
  • delivery_status - состояние согласования доставки для клиента и логиста
  • delivery_link - полная публичная ссылка на /delivery/:token
  • delivery_invitation_id - связанная запись приглашения
  • notification_status - состояние SMS-оркестрации для n8n
  • sms_attempts - сколько было попыток отправки SMS
  • first_sms_sent_at - время первой SMS
  • second_sms_sent_at - время второй SMS
  • last_sms_error - текст последней ошибки провайдера
  • next_notification_check_at - когда n8n должен вернуться к записи
  • delivery_date и delivery_time - выбранный слот после подтверждения клиентом

Окно отправки SMS

Чтобы не тревожить клиентов ночью, SMS отправляются только в местное окно:

09:00-20:00 Europe/Simferopol

Если запись стала готова к отправке вне этого окна, SMS не отправляется сразу. Supabase должен поставить ближайшее разрешенное время в next_notification_check_at:

  • до 09:00 - сегодня в 09:00
  • с 09:00 до 20:00 - сразу
  • после 20:00 - завтра в 09:00

Для этого в SQL есть helper:

public.next_order_group_sms_check_at(start_from timestamptz, delay interval)

n8n не должен сам решать, можно ли сейчас тревожить клиента. Он просто выбирает записи, где next_notification_check_at <= now().

Рекомендуемая модель статусов

delivery_status

  • pending_confirmation - клиент еще не выбрал слот
  • agreed - клиент выбрал слот доставки
  • manual_confirmation_required - автоматический поток не сработал, менеджер/логист должен продолжить вручную
  • no_contact - менеджер/логист пытался связаться вручную, но связи с клиентом нет
  • assigned_to_driver - доставка согласована и передана в планирование водителю
  • out_for_delivery - водитель уже в работе
  • delivered - доставка завершена
  • cancelled - группу больше не нужно обрабатывать

notification_status

  • not_started - ссылка еще не подготовлена
  • link_ready - Supabase создал delivery_link, n8n может отправлять первую SMS
  • first_sms_sent - первая SMS принята провайдером
  • second_sms_sent - отправлено напоминание
  • confirmed - клиент выбрал слот
  • manual_required - после повторов подтверждения нет
  • send_failed - ошибка провайдера/API, можно повторить

Ответственность Supabase

1. Подготовка ссылки

Когда order_group попадает в поток согласования доставки:

  • status = 'ready_for_notification'
  • delivery_status = 'pending_confirmation'

Триггер Supabase order_groups_ensure_delivery_link должен:

  • создать запись delivery_invitations с order_group_id
  • сгенерировать token и полную публичную ссылку
  • подготовить слоты только на завтра и послезавтра
  • записать delivery_link в order_groups
  • установить delivery_invitation_id
  • установить notification_status = 'link_ready'
  • установить next_notification_check_at через public.next_order_group_sms_check_at()

SQL для этого триггера лежит здесь:

docs/sql/order-groups-auto-delivery-link.sql

n8n больше не должен вызывать create-delivery-invitation для order_groups. Ему нужно ждать, пока в строке уже будут notification_status = 'link_ready' и delivery_link is not null.

2. Прием выбора клиента

Публичная страница использует token. Когда клиент подтверждает слот, confirm-delivery-choice должен:

  • сохранить delivery_date и delivery_time
  • установить delivery_status = 'agreed'
  • установить notification_status = 'confirmed'

Это становится стоп-сигналом для всех напоминаний в n8n.

Потоки n8n

Поток 1. Отправка первой SMS

Триггер:

  • Cron каждые 5-10 минут
  • Опционально запасной webhook-триггер, если потом захочешь push-старт

Запрос:

  • status = 'ready_for_notification'
  • delivery_status = 'pending_confirmation'
  • notification_status = 'link_ready'
  • delivery_link is not null
  • next_notification_check_at <= now()

Действие:

  • отправить SMS с delivery_link

При успехе обновить order_groups:

  • notification_status = 'first_sms_sent'
  • sms_attempts = 1
  • first_sms_sent_at = now()
  • sms_sent_at = now()
  • last_sms_error = null
  • next_notification_check_at = public.next_order_group_sms_check_at(now(), interval '3 hours')

Важно: если первая SMS ушла, например, в 18:30, проверка через 3 часа попала бы на 21:30. Helper перенесет следующую проверку на завтра 09:00.

При ошибке обновить order_groups:

  • notification_status = 'send_failed'
  • last_sms_error = <ошибка провайдера>
  • next_notification_check_at = public.next_order_group_sms_check_at(now(), interval '10 minutes')

Поток 2. Наблюдатель доставки

Триггер:

  • Cron каждые 10 минут

Назначение:

  • найти записи, где первый поток не завершился корректно
  • повторить неудачные первые отправки

Кандидаты для выбора:

  • notification_status = 'send_failed'
  • delivery_status = 'pending_confirmation'
  • next_notification_check_at <= now()

Поведение:

  • повторить первую SMS
  • если успех, перевести в first_sms_sent
  • если повторные ошибки превысили выбранный порог, перевести в manual_required
  • все новые значения next_notification_check_at считать через public.next_order_group_sms_check_at(...)

Поток 3. Напоминание по SMS

Триггер:

  • Cron каждые 10 минут

Запрос:

  • delivery_status = 'pending_confirmation'
  • notification_status = 'first_sms_sent'
  • next_notification_check_at <= now()

Действие:

  • отправить вторую SMS-напоминалку с той же delivery_link

При успехе обновить:

  • notification_status = 'second_sms_sent'
  • sms_attempts = 2
  • second_sms_sent_at = now()
  • last_sms_error = null
  • next_notification_check_at = public.next_order_group_sms_check_at(now(), interval '3 hours')

При ошибке обновить:

  • notification_status = 'send_failed'
  • last_sms_error = <ошибка провайдера>
  • next_notification_check_at = public.next_order_group_sms_check_at(now(), interval '30 minutes')

Поток 4. Передача в ручную обработку

Триггер:

  • Cron каждые 10 минут

Запрос:

  • delivery_status = 'pending_confirmation'
  • notification_status = 'second_sms_sent'
  • next_notification_check_at <= now()

Действие:

  • остановить автоматические напоминания
  • перевести группу в ручную обработку

Обновление:

  • delivery_status = 'manual_confirmation_required'
  • notification_status = 'manual_required'

После этого автоматические SMS больше не отправляются. В ЛК менеджер/логист должен вручную выбрать дату доставки или поставить результат no_contact, если связаться с клиентом не удалось.

Поток 5. Условия остановки

Каждый поток должен игнорировать строки, где:

  • delivery_status in ('agreed', 'no_contact', 'assigned_to_driver', 'out_for_delivery', 'delivered', 'cancelled')
  • notification_status in ('confirmed', 'manual_required')

Это не дает слать дублирующие SMS после ответа клиента или передачи кейса человеку.

Рекомендуемый текст SMS

Пример:

Ваш заказ готов к согласованию доставки.
Выберите удобные дату и время по ссылке:
{{delivery_link}}

Напоминание:

Напоминаем: нужно выбрать дату и время доставки вашего заказа.
Ссылка:
{{delivery_link}}

Что нужно фронтенду

Публичной странице нужны только:

  • token из URL
  • get-delivery-invitation
  • confirm-delivery-choice

Никакой логики SMS на фронтенде быть не должно. Никакой генерации ссылок на фронтенде быть не должно.

Минимальный порядок внедрения

  1. Развернуть обновленную схему Supabase и docs/sql/order-groups-auto-delivery-link.sql.
  2. Проверить, что insert/update в order_groups пишет delivery_link и notification_status = 'link_ready'.
  3. Собрать поток n8n для первой SMS.
  4. Собрать поток n8n для напоминаний.
  5. Собрать поток n8n для ручной передачи.
  6. Проверить полный цикл на одной реальной записи order_group.

Сценарий проверки

  1. Пометить одну order_group как готовую к клиентскому согласованию доставки.
  2. Убедиться, что delivery_link появился в order_groups автоматически.
  3. Дать n8n отправить первую SMS.
  4. Открыть ссылку и подтвердить слот на клиентской странице.
  5. Убедиться, что delivery_status = 'agreed' и notification_status = 'confirmed'.
  6. Убедиться, что потоки напоминаний больше не трогают эту группу.