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