# SuperSam: Обзор системы

`SuperSam` — это система управления доставкой заказов. В текущем scope она состоит из трёх внутренних ролей и одной публичной страницы для клиента: менеджер, логист, водитель и клиент.

## Задачи приложения

- показать менеджеру единый реестр доставочных заказов с поиском и карточкой заказа;
- показать логисту список доставок на сегодня и ближайшие дни с половинами дня;
- показать водителю свои доставки, адрес, состав заказа и базовые статусы;
- дать клиенту публичную ссылку, по которой он выбирает дату и половину дня доставки **или самовывоза**;
- хранить состояние заказов, приглашений и истории изменений в Supabase.

## Роли

### Менеджер

- видит список заказов доставки;
- ищет по номеру заказа, клиенту и телефону;
- открывает карточку заказа и смотрит состав, комментарии и историю;
- может назначить тип доставки (доставка/самовывоз), дату самовывоза и половину дня;
- не работает с созданием заказов и внутренними служебными экранами.

### Логист

- видит заказы, готовые к доставке;
- смотрит ближайшие даты: сегодня, завтра и послезавтра;
- смотрит половину дня и текущий статус доставки;
- открывает карточку заказа, чтобы свериться с деталями;
- может перевести статус заказа в «Самовывоз» и указать дату.

### Водитель

- видит только свои доставки;
- открывает адрес, клиента, состав заказа и комментарии;
- меняет базовый статус доставки по маршруту.

### Клиент

- получает публичную ссылку вида `/delivery/:token`;
- видит номер заказа и состав заказа;
- **выбирает тип получения: Доставка или Самовывоз**;
- при выборе доставки — выбирает дату и половину дня: `До обеда` или `После обеда`;
- при выборе самовывоза — выбирает дату (сегодня/завтра/послезавтра с учётом выходных) и половину дня;
- видит информацию о бесплатном хранении (2 рабочих дня) и платном (300₽/день начиная с 3-го рабочего дня);
- подтверждает выбор без входа во внутренний кабинет.

## Самовывоз

### Клиентский флоу

1. Клиент открывает ссылку `/delivery/:token`.
2. Видит две вкладки: **🚚 Доставка** и **🏪 Самовывоз**.
3. На вкладке «Самовывоз» видит:
   - Доступные даты: сегодня (если до 12:00 текущего дня готовности), завтра, послезавтра (выходные пропускаются).
   - Две половины дня: «До обеда» и «После обеда».
   - Информационный блок: «Бесплатное хранение — 2 рабочих дня. С 3-го рабочего дня — 300₽/день.»
4. Выбирает дату и половину дня, подтверждает.
5. Статус заказа переходит в `pickup`, в БД сохраняются `pickup_date` и `pickup_time_slot`.

### Управление в карточке заказа

- Менеджер, логист и администратор могут переключить тип доставки (Доставка ↔ Самовывоз).
- При самовывозе доступны поля: дата самовывоза и половина дня.
- Статус «Самовывоз» доступен в кнопках смены статуса.

### База данных

В таблице `order_groups` добавлены колонки:
- `delivery_type text DEFAULT 'delivery'` — тип получения: `delivery` или `pickup`
- `pickup_date date` — дата самовывоза
- `pickup_time_slot text` — половина дня самовывоза (`До обеда` / `После обеда`)

Статус `delivery_status` пополнился значением `pickup` — «Самовывоз».

## Основные сценарии

### Внутренний сценарий

1. Заказ появляется в Supabase.
2. Менеджер видит его в реестре и сверяет состав.
3. Логист отслеживает готовность и ближайшее окно доставки.
4. Водитель получает свою доставку и доводит её до результата.

### Сценарий клиента (доставка)

Клиентская страница работает по token из таблицы `public.delivery_invitations`.

После загрузки seed можно открыть ссылку:

`/delivery/client-flow-1001`

Эта ссылка показывает:
- заказ `CD-240031`;
- состав заказа;
- вкладки «Доставка» и «Самовывоз»;
- на вкладке «Доставка» — четыре варианта слота, две даты, две половины дня.

### Сценарий клиента (самовывоз)

При выборе вкладки «Самовывоз»:
- доступны даты начиная с дня готовности (если до 12:00) или завтра;
- две половины дня: «До обеда» и «После обеда»;
- информационный блок о стоимости хранения;
- подтверждение устанавливает `delivery_type = 'pickup'`, `delivery_status = 'pickup'`.

## Что хранится в Supabase

- `public.users` — пользователи и роли;
- `public.orders` — заказы и текущие статусы;
- `public.order_history` — история изменений;
- `public.order_groups` — группы заказов с полями доставки и самовывоза:
  - `delivery_type` — `delivery` или `pickup`;
  - `delivery_date`, `delivery_time` — слот доставки;
  - `pickup_date`, `pickup_time_slot` — слот самовывоза;
  - `delivery_status` — статус согласования (включая `pickup`);
- `public.delivery_slots` — возможные и подтверждённые слоты доставки;
- `public.delivery_invitations` — публичные invitation token и состояние клиентского flow;
- `public.integration_events` — технические и интеграционные события.

## Как подготовить систему к показу

1. Загрузить схему `supabase/schema.sql`.
2. Выполнить `supabase/seed/stage-1-demo.sql`.
3. Убедиться, что развернуты Edge Functions:
   - `get-delivery-invitation`
   - `confirm-delivery-choice`
   - `create-delivery-invitation`
4. Открыть внутренний кабинет и пройти вход под ролью.
5. Открыть клиентскую ссылку `/delivery/client-flow-1001`.

## Что показывать на встрече

- вход менеджера, логиста и водителя;
- реестр заказов и карточку заказа;
- список доставок по датам для логиста;
- карточку доставки водителя;
- клиентскую ссылку с выбором типа получения (доставка/самовывоз) и датой;
- информационный блок о стоимости хранения при самовывозе.

## Полезные документы

- [README](../README.md)
- [Архитектура](architecture.md)
- [Сценарии](scenarios.md)
- [Поток n8n](n8n-order-group-delivery-flow.md)
- [Edge Functions](../supabase/functions/README.md)