supersam/docs/superpowers/plans/2026-03-30-delivery-platform-contract-plan.md

Delivery Platform Contract 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: Реализовать договорной объем проекта: self-hosted кабинет с ролями, клиентскую страницу согласования доставки, автоматизации на n8n/Edge Functions, ручную обработку логистом, платное хранение, интеграцию с 1С, обучение и приемку по 3 этапам.

Architecture: Основа остается в существующем React + Supabase приложении. Внутренние рабочие места продолжают жить в текущем dashboard, а клиентский сценарий выносится в отдельный публичный route с серверной валидацией состояния заказа. Критичные бизнес-переходы и интеграционные контракты фиксируются в Supabase schema/Edge Functions, а n8n используется как orchestration-слой для SMS, напоминаний и обмена с 1С.

Tech Stack: React 18, Vite, existing UI kit, Vitest, Supabase self-hosted, Supabase SQL/RLS, Supabase Edge Functions, n8n, self-hosted VPS deployment docs.

---

File Structure

• Modify: src/router.jsx — добавить публичный клиентский route и сохранить текущую dashboard-навигацию.
• Create: src/pages/ClientDeliveryPage.jsx — страница выбора доставки по ссылке.
• Create: src/components/client/DeliveryChoiceFlow.jsx — основной клиентский flow выбора/подтверждения/информационных состояний.
• Create: src/components/client/DeliveryStateNotice.jsx — read-only состояния: уже согласовано, передано логисту, платное хранение, доставлено.
• Create: src/components/client/DeliveryChoiceFlow.test.jsx — UI/flow тесты клиентской страницы.
• Modify: src/constants/deliveryWorkflow.js — новые статусы и метаданные (Ожидает ответа клиента, Передан логисту, Платное хранение).
• Modify: src/services/orderService.js — чистые переходы статусов, напоминания, ручная передача логисту, исключения доставки.
• Modify: src/services/orderService.test.js — тесты на новые переходы и guard rules.
• Modify: src/data/mockAppData.js — договорные demo-сценарии ролей, логиста, клиента и неуспешной доставки.
• Modify: src/pages/DashboardPage.jsx — вывести логисту ручную обработку, платное хранение и delivery exceptions.
• Modify: src/components/logistics/BotControlPanel.jsx or split — логистические действия для ручного согласования и повторной доставки.
• Modify: src/components/driver/DriverDeliveryPlanner.jsx
• Modify: src/components/driver/DriverDeliveryDetail.jsx — фиксация успешной/неуспешной доставки и причины.
• Modify: supabase/schema.sql — invitation/session tables, integration event tables, дополнительные статусы/поля.
• Modify: supabase/functions/_shared/workflow.ts — серверная карта переходов для delivery agreement flow.
• Create: supabase/functions/_shared/delivery-invitations.ts — общая логика поиска/валидации активной клиентской ссылки.
• Create: supabase/functions/create-delivery-invitation/index.ts — создание активной клиентской ссылки для n8n.
• Create: supabase/functions/get-delivery-invitation/index.ts — отдача публичного состояния клиентской страницы.
• Create: supabase/functions/confirm-delivery-choice/index.ts — подтверждение half-day выбора клиента.
• Create: supabase/functions/transfer-to-logistics/index.ts — ручная передача заказа логисту/платное хранение по automation signals.
• Create: supabase/functions/report-delivery-result/index.ts — фиксация delivery result + payload для 1С.
• Modify: supabase/functions/README.md — обновить serverless contracts.
• Create: docs/operations/self-hosted-deploy.md — требования к VPS, доменам, балансам, старту работ.
• Create: docs/integrations/n8n-delivery-flow.md — webhook contracts, reminder schedule, SMS/1С responsibilities.
• Create: docs/training/logistics-playbook.md
• Create: docs/training/driver-playbook.md
• Modify: docs/scenarios.md
• Modify: docs/architecture.md

Chunk 1: Contract Stage 1 Foundation And Demo Approval

Task 1: Зафиксировать self-hosted стартовые условия и договорные ограничения

Files:

• Create: docs/operations/self-hosted-deploy.md

• Modify: README.md

• Описать старт работ: VPS/Beget or agreed provider, домен/поддомен для app и Supabase, баланс минимум на 2 месяца.

• Зафиксировать, что 1С, SMS и домены предоставляет/обеспечивает Заказчик.

• Прогнать sanity-check документации вручную.

Task 2: Подготовить demo-модель статусов и ролей под договор

Files:

• Modify: src/constants/deliveryWorkflow.js

• Modify: src/data/mockAppData.js

• Modify: src/services/orderService.js

• Modify: src/services/orderService.test.js

• Написать падающие тесты на новые статусы:

  • Ожидает ответа клиента
  • Передан логисту
  • Платное хранение
  • повторная доставка после Проблема доставки

• Прогнать таргетированные тесты.

  • Run: npm test -- src/services/orderService.test.js
  • Expected: FAIL

• Реализовать минимальные переходы в orderService.

• Обновить workflow metadata и demo data под новые сценарии.

• Прогнать таргетированные тесты повторно.

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

Task 3: Добавить публичный demo-route клиентского выбора доставки

Files:

• Modify: src/router.jsx

• Create: src/pages/ClientDeliveryPage.jsx

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

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

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

• Написать падающие UI-тесты на:

  • активный выбор half-day
  • уже согласованную доставку
  • передан логисту
  • платное хранение

• Прогнать только новый клиентский набор тестов.

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

• Реализовать публичную страницу и базовые read/write состояния на demo data.

• Прогнать тесты повторно.

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

Task 4: Показать логисту ручную ветку в dashboard

Files:

• Modify: src/pages/DashboardPage.jsx

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

• Modify: related test files if coverage already exists

• Вывести для логиста заказы в Ожидает ответа клиента, Передан логисту, Платное хранение, Проблема доставки.

• Добавить действия ручного согласования и передачи на следующий статус в demo mode.

• Ручная проверка stage 1 demo:

  • login by role
  • internal dashboard
  • client page
  • manual logistics branch

Chunk 2: Contract Stage 2 Core Delivery Workflow

Task 5: Спроектировать и внедрить schema changes для delivery invitation flow

Files:

• Modify: supabase/schema.sql

• Modify: supabase/functions/_shared/workflow.ts

• Написать SQL-план таблиц/полей для:

  • client invitation/session
  • event/audit integration state
  • optional manual handling reason fields

• Обновить server-side workflow map под новые статусы.

• Проверить schema diff вручную на совместимость с текущими orders, delivery_slots, order_history.

Task 6: Реализовать Edge Functions для клиентской ссылки и логистической передачи

Files:

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

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

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

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

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

• Modify: supabase/functions/README.md

• Написать падающие tests for shared workflow/helpers where feasible.

• Реализовать создание активной ссылки без TTL-expiry logic, только по status guard.

• Реализовать confirm half-day choice и перевод в Доставка согласована.

• Реализовать transfer to logistics для reminder escalation.

• Обновить function README с request/response contract.

Task 7: Перевести клиентский route с demo на реальный Supabase contract

Files:

• Modify: src/pages/ClientDeliveryPage.jsx

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

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

• Modify or Create: supporting client-side service file if needed

• Подключить загрузку invitation state из Edge Function.

• Подключить подтверждение выбора half-day.

• Показать серверные состояния:

  • active choice
  • already agreed
  • transferred to logistics
  • paid storage
  • delivered

• Прогнать client flow tests и обновить их под реальный contract.

Task 8: Описать n8n orchestration и внешние зависимости

Files:

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

• Modify: docs/scenarios.md

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

  • SMS #1
  • SMS #2 after no click
  • reminder after opened-but-not-confirmed
  • transfer to logistics
  • paid storage notification
  • 1С inbound/outbound responsibilities of customer

• Добавить webhook payload examples for n8n.

Chunk 3: Contract Stage 3 End-To-End Integrations And Operations

Task 9: Реализовать delivery result flow и integration payloads for 1С

Files:

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

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

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

• Modify: related driver tests if present

• Написать падающие tests на:

  • Доставлен
  • Проблема доставки
  • возврат логисту после failed delivery

• Прогнать таргетированные driver/order service tests.

• Реализовать driver result payload preparation for n8n/1С.

• Обновить UI водителя для обязательной фиксации причины неуспешной доставки.

Task 10: Завершить ручную ветку логиста и платное хранение

Files:

• Modify: src/pages/DashboardPage.jsx

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

• Modify: src/services/orderService.js

• Modify: src/services/orderService.test.js

• Добавить логистические действия:

  • ручное согласование
  • перевод в платное хранение
  • снятие с платного хранения после новой договоренности

• Закрепить audit entries/history comments for these transitions.

• Прогнать order/logistics tests.

Task 11: Подготовить обучение и эксплуатационные документы

Files:

• Create: docs/training/logistics-playbook.md

• Create: docs/training/driver-playbook.md

• Modify: docs/architecture.md

• Описать сценарии логиста:

  • auto agreement monitoring
  • manual follow-up
  • paid storage
  • repeat delivery

• Описать сценарии водителя:

  • confirmed route
  • delivered
  • failed delivery

• Обновить architecture doc под публичный client route и integrations layer.

Chunk 4: Final Verification And Handoff

Task 12: Полная техническая проверка

Files:

• Reference: docs/superpowers/plans/2026-03-30-delivery-platform-contract-plan.md

• Прогнать unit/integration tests.

  • Run: npm test
  • Expected: PASS

• Прогнать линтер.

  • Run: npm run lint
  • Expected: PASS

• Прогнать production build.

  • Run: npm run build
  • Expected: PASS

• Ручная проверка:

  • role login
  • demo/dashboard
  • public client route
  • logistics manual flow
  • driver result flow
  • integration payload visibility

Task 13: Договорная приемка по этапам

Files:

• Reference: contract stage description

• Reference: docs/training/logistics-playbook.md

• Reference: docs/training/driver-playbook.md

• Подготовить demo checklist для Этапа 1.

• Подготовить production checklist для Этапа 2.

• Подготовить launch + training checklist для Этапа 3.

• Зафиксировать, какие входы со стороны Заказчика обязательны до каждой приемки:

  • VPS and balance
  • domain/subdomain
  • SMS provider
  • 1С responsible person
  • 1С data contract