# 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
- логист переводит в согласовано или в платное хранение
- водитель фиксирует доставку или проблему
- итоговый статус уходит во внешнюю систему