Mk
/
supersam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
supersam/docs/superpowers/plans/2026-04-12-delivery-orchest...

11 KiB
Raw Blame History

Delivery Orchestration Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Реализовать рабочую orchestration-схему согласования доставки на базе Supabase + Edge Functions + n8n + FTP XML, включая SMS-тайминги, ручную работу логиста, платное хранение и передачу результата доставки во внешнюю систему.

Architecture: Supabase остается источником истины по заказам, приглашениям, статусам и истории. n8n становится orchestration-слоем: читает XML с FTP, вычисляет SLA по времени, вызывает Edge Functions, отправляет SMS и передает статусы во внешние системы. Приложение показывает оператору и клиенту только актуальное состояние из Supabase.

Tech Stack: React 18, Vite, Supabase SQL, Supabase Edge Functions, n8n, FTP XML polling, SMS provider, external accounting integration.

File Structure

  • Create: docs/integrations/delivery-orchestration.md — итоговая архитектура процесса и распределение ответственности.
  • Create: docs/integrations/n8n-delivery-flow.md — рабочие contracts для n8n workflow и payload examples.
  • Modify: docs/architecture.md — короткая ссылка на orchestration-слой.
  • Modify: docs/scenarios.md — привести текстовые сценарии к фактической схеме.
  • Modify: supabase/schema.sql — добавить недостающие orchestration fields, если они еще не добавлены.
  • Modify: supabase/functions/_shared/delivery-invitations.ts — выровнять helper map под финальную схему.
  • Modify: supabase/functions/create-delivery-invitation/index.ts
  • Modify: supabase/functions/get-delivery-invitation/index.ts
  • Modify: supabase/functions/confirm-delivery-choice/index.ts
  • Modify: supabase/functions/transfer-to-logistics/index.ts
  • Modify: supabase/functions/report-delivery-result/index.ts
  • Modify: supabase/functions/README.md
  • Modify: src/pages/ClientDeliveryPage.jsx — показать итоговые статусы и ошибки по production flow.
  • Modify: src/components/logistics/BotControlPanel.jsx — ручные действия логиста.
  • Modify: src/components/driver/DriverDeliveryPlanner.jsx
  • Modify: src/components/driver/DriverDeliveryDetail.jsx
  • Modify: src/services/deliveryInvitationApi.js
  • Modify: related tests for functions, client flow, logistics and driver behavior.

Chunk 1: Orchestration Contracts

Task 1: Зафиксировать архитектурное решение “n8n orchestrates, Supabase stores truth”

Files:

  • Create: docs/integrations/delivery-orchestration.md

  • Modify: docs/architecture.md

  • Step 1: Write the architecture document

Зафиксировать:

  • XML на FTP читает n8n

  • n8n запускает сценарии по времени

  • Supabase хранит статусы и историю

  • Edge Functions валидируют переходы

  • клиентское приложение только читает/подтверждает состояние

  • Step 2: Add a short summary into docs/architecture.md

Добавить отдельный блок про orchestration layer и связь с n8n.

  • Step 3: Manual doc review

Проверить, что документ явно отвечает на вопрос:

  • где живет расписание;
  • кто читает XML;
  • где отправляются SMS;
  • кто возвращает статус в учетную систему.

Task 2: Подготовить n8n-контракт для XML и SLA

Files:

  • Create: docs/integrations/n8n-delivery-flow.md

  • Modify: docs/scenarios.md

  • Step 1: Describe FTP XML Poller

Описать:

  • как читается XML;

  • какие поля заказа считаются сигналом “полностью готов”;

  • как n8n понимает, что заказ новый для delivery flow.

  • Step 2: Describe timeout workflows

Зафиксировать:

  • первая SMS

  • повторная SMS через 3 часа

  • передача логисту еще через 3 часа

  • reminder через 1 час после opened/no-confirm

  • передача логисту через 2 часа после reminder

  • SMS о платном хранении

  • Step 3: Add payload examples

Добавить примеры payload между:

  • n8n -> create-delivery-invitation
  • n8n -> transfer-to-logistics
  • n8n -> report-delivery-result
  • n8n -> SMS provider

Chunk 2: Supabase State Model

Task 3: Проверить, что в Supabase хватает данных для SLA-логики

Files:

  • Modify: supabase/schema.sql

  • Modify: supabase/functions/README.md

  • Step 1: Audit current schema against the flow

Проверить наличие/нехватку полей:

  • sent_at

  • opened_at

  • confirmed_at

  • logistics_transferred_at

  • paid_storage_at

  • delivered_at

  • reminder markers

  • export markers for external system

  • Step 2: Add missing fields if required

Если чего-то не хватает, добавить минимальные поля без дублирования уже существующих timestamps.

  • Step 3: Update function README

Описать, какие функции вызываются n8n и какие timestamps/statuses они меняют.

Task 4: Выровнять Edge Functions под финальную схему

Files:

  • Modify: supabase/functions/_shared/delivery-invitations.ts

  • Modify: supabase/functions/create-delivery-invitation/index.ts

  • Modify: supabase/functions/get-delivery-invitation/index.ts

  • Modify: supabase/functions/confirm-delivery-choice/index.ts

  • Modify: supabase/functions/transfer-to-logistics/index.ts

  • Modify: supabase/functions/report-delivery-result/index.ts

  • Test: supabase/functions/_shared/delivery-invitations.test.ts

  • Test: supabase/functions/_shared/workflow.test.ts

  • Step 1: Write failing tests for missing state transitions

Покрыть:

  • awaiting response

  • reminder state

  • transfer to logistics

  • paid storage

  • delivered

  • failed delivery returning to logistics

  • Step 2: Run targeted function tests

Run: npm test -- supabase/functions/_shared/delivery-invitations.test.ts supabase/functions/_shared/workflow.test.ts Expected: FAIL if contracts are incomplete.

  • Step 3: Implement minimal changes

Довести helpers и functions до полного соответствия схеме.

  • Step 4: Re-run targeted tests

Run: npm test -- supabase/functions/_shared/delivery-invitations.test.ts supabase/functions/_shared/workflow.test.ts Expected: PASS

Chunk 3: App Operator Flows

Task 5: Довести клиентскую страницу до финального production behavior

Files:

  • Modify: src/pages/ClientDeliveryPage.jsx

  • Modify: src/components/client/DeliveryChoiceFlow.jsx

  • Modify: src/components/client/DeliveryStateNotice.jsx

  • Modify: src/services/deliveryInvitationApi.js

  • Test: src/components/client/DeliveryChoiceFlow.test.jsx

  • Step 1: Write or extend failing tests for all terminal states

Покрыть:

  • awaiting choice

  • agreed

  • transferred to logistics

  • paid storage

  • delivered

  • invalid/expired token

  • Step 2: Run targeted client tests

Run: npm test -- src/components/client/DeliveryChoiceFlow.test.jsx Expected: FAIL if state rendering is incomplete.

  • Step 3: Implement minimal UI changes

Сделать экраны и сообщения строго соответствующими схеме.

  • Step 4: Re-run client tests

Run: npm test -- src/components/client/DeliveryChoiceFlow.test.jsx Expected: PASS

Task 6: Довести ручную ветку логиста и ветку водителя

Files:

  • Modify: src/components/logistics/BotControlPanel.jsx

  • Modify: src/pages/DashboardPage.jsx

  • Modify: src/components/driver/DriverDeliveryPlanner.jsx

  • Modify: src/components/driver/DriverDeliveryDetail.jsx

  • Modify: related logistics/driver tests if needed

  • Step 1: Add logistics actions

Нужны действия:

  • согласовать вручную

  • перевести в платное хранение

  • повторно согласовать после проблемной доставки

  • Step 2: Add driver result actions

Нужны действия:

  • отметить Доставлен

  • отметить Проблема доставки

  • передать причину обратно в логистику

  • Step 3: Run targeted UI/service tests

Run: npm test -- src/services/orderService.test.js src/services/orderViews.test.js Expected: PASS

Chunk 4: n8n Implementation And Launch Checklist

Task 7: Реализовать сами n8n workflows

Files:

  • Reference: docs/integrations/n8n-delivery-flow.md

  • Step 1: Build FTP XML Poller workflow

Настроить:

  • cron trigger

  • чтение XML с FTP

  • парсинг готовых заказов

  • сверку с Supabase

  • Step 2: Build Delivery Offer Dispatcher

Настроить:

  • вызов create-delivery-invitation

  • отправку первой SMS

  • Step 3: Build Delivery Reminder Scheduler

Настроить:

  • повторную SMS

  • reminder после opened/no-confirm

  • передачу логисту по timeout

  • Step 4: Build Paid Storage Notifier

Настроить SMS при статусе Платное хранение.

  • Step 5: Build Delivery Result Exporter

Настроить передачу результата доставки во внешнюю систему.

Task 8: Финальная проверка

Files:

  • Reference: docs/integrations/delivery-orchestration.md

  • Reference: docs/integrations/n8n-delivery-flow.md

  • Reference: docs/superpowers/plans/2026-04-12-delivery-orchestration-implementation.md

  • Step 1: Run full test suite

Run: npm test Expected: PASS

  • Step 2: Run linter

Run: npm run lint Expected: PASS

  • Step 3: Run production build

Run: npm run build Expected: PASS

  • Step 4: Execute manual end-to-end checklist

Проверить руками:

  • XML отметил заказ как готовый
  • ушла первая SMS
  • открытие ссылки фиксируется
  • reminder отправляется по времени
  • заказ уходит логисту при timeout
  • логист переводит в согласовано или в платное хранение
  • водитель фиксирует доставку или проблему
  • итоговый статус уходит во внешнюю систему