# 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