270 lines
15 KiB
Markdown
270 lines
15 KiB
Markdown
# 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
|