supersam/docs/n8n-order-group-delivery-flow.md

n8n Flow For order_groups

Goal

Supabase stores the delivery state, generates the client link, and saves all timestamps. n8n is responsible for sending SMS, retrying, and moving stalled groups into manual handling.

The short link is not needed on our side. We store the full delivery_link, and the SMS provider shortens it during delivery.

Source Of Truth

The main record is public.order_groups.

Important fields:

• status - business readiness of the group
• delivery_status - delivery coordination state for the client and logistics
• delivery_link - full public link to /delivery/:token
• delivery_invitation_id - related invitation record
• notification_status - SMS orchestration state for n8n
• sms_attempts - how many SMS attempts were made
• first_sms_sent_at - timestamp of the first SMS
• second_sms_sent_at - timestamp of the second SMS
• last_sms_error - last provider error text
• next_notification_check_at - when n8n should revisit the record
• delivery_date and delivery_time - selected slot after client confirmation

Recommended Status Model

delivery_status

• pending_confirmation - client has not selected a slot yet
• agreed - client selected a delivery slot
• manual_confirmation_required - automatic flow failed, manager/logistics must continue manually
• assigned_to_driver - delivery is approved and handed over to driver planning
• out_for_delivery - driver is already working on it
• delivered - delivery completed
• cancelled - group should no longer be processed

notification_status

• not_started - link has not been prepared yet
• link_ready - Supabase created delivery_link, n8n can send the first SMS
• first_sms_sent - first SMS was accepted by provider
• second_sms_sent - reminder SMS was accepted by provider
• confirmed - client selected a slot
• manual_required - no confirmation after retries
• send_failed - provider/API error, retry allowed

Supabase Responsibilities

1. Prepare the link

When an order_group is moved into the client-delivery flow:

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

Supabase trigger order_groups_ensure_delivery_link should:

• create delivery_invitations row with order_group_id
• generate token and full public URL
• write delivery_link into order_groups
• set delivery_invitation_id
• set notification_status = 'link_ready'
• set next_notification_check_at = now()

The SQL for this trigger lives in:

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

n8n no longer has to call create-delivery-invitation for order_groups. It should wait until the row already has notification_status = 'link_ready' and delivery_link is not null.

2. Accept client choice

The public client page uses the token. When the client confirms a slot, confirm-delivery-choice should:

• store delivery_date and delivery_time
• set delivery_status = 'agreed'
• set notification_status = 'confirmed'

That change becomes the stop signal for all reminder workflows in n8n.

n8n Workflows

Workflow 1. First SMS sender

Trigger:

• Cron every 5-10 minutes
• Optional backup webhook trigger if you later want push-based start

Query:

• status = 'ready_for_notification'
• delivery_status = 'pending_confirmation'
• notification_status = 'link_ready'
• delivery_link is not null

Action:

• send SMS with delivery_link

On success update 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 = now() + interval '1 hour'

On failure update order_groups:

• notification_status = 'send_failed'
• last_sms_error = <provider error>
• next_notification_check_at = now() + interval '10 minutes'

Workflow 2. Delivery watchdog

Trigger:

• Cron every 10 minutes

Purpose:

• find records where first workflow did not finish cleanly
• retry failed first sends

Query candidates:

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

Behavior:

• retry first SMS
• if success, move to first_sms_sent
• if repeated failures exceed your chosen threshold, move to manual_required

Workflow 3. Reminder SMS

Trigger:

• Cron every 10 minutes

Query:

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

Action:

• send second SMS reminder with the same delivery_link

On success update:

• notification_status = 'second_sms_sent'
• sms_attempts = 2
• second_sms_sent_at = now()
• last_sms_error = null
• next_notification_check_at = now() + interval '3 hours'

On failure update:

• notification_status = 'send_failed'
• last_sms_error = <provider error>
• next_notification_check_at = now() + interval '30 minutes'

Workflow 4. Manual handoff

Trigger:

• Cron every 10 minutes

Query:

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

Action:

• stop automatic reminders
• move the group into manual handling

Update:

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

Workflow 5. Stop conditions

Every workflow must ignore rows where:

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

This prevents duplicate SMS after the client already responded or the case was handed to a person.

Suggested SMS Text

Example:

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

Reminder:

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

What Frontend Needs

The frontend public page only needs:

• token from URL
• get-delivery-invitation
• confirm-delivery-choice

No SMS logic should live in the frontend. No link generation should live in the frontend.

Minimal Rollout Order

1. Deploy updated Supabase schema and docs/sql/order-groups-auto-delivery-link.sql.
2. Verify that insert/update in order_groups writes delivery_link and notification_status = 'link_ready'.
3. Build n8n workflow for first SMS.
4. Build n8n reminder workflow.
5. Build n8n manual-handoff workflow.
6. Test full cycle on one real order_group.

Test Scenario

1. Mark one order_group as ready for client delivery.
2. Confirm that delivery_link appeared in order_groups automatically.
3. Let n8n send the first SMS.
4. Open the link and confirm a slot on the client page.
5. Confirm that delivery_status = 'agreed' and notification_status = 'confirmed'.
6. Confirm that reminder workflows no longer touch this group.