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

`SuperSam` — это система управления доставкой заказов, которая объединяет внутренние рабочие кабинеты сотрудников и публичную страницу для клиента. Приложение помогает пройти путь от готовности заказа к отгрузке до согласования доставки, назначения исполнителей, фиксации результата и контроля исключений.

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

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

## Роли

### Менеджер

Менеджер работает с заказами на ранних этапах:
- видит список заказов и карточки клиентов;
- следит за составом заказа и комментариями;
- передаёт заказ дальше по процессу после подтверждения.

### Логист

Логист отвечает за доставку:
- видит готовые к запуску и проблемные заказы;
- контролирует статусы согласования доставки;
- назначает и корректирует слоты;
- переводит заказ в ручную обработку, если клиент не ответил;
- отслеживает историю и связанные сообщения.

### Водитель

Водитель работает только со своими доставками:
- видит назначенные маршруты;
- открывает карточку точки доставки;
- фиксирует ход доставки и итоговый статус.

### Администратор

Администратор видит всю систему:
- пользователей и роли;
- общие списки заказов и событий;
- состояние интеграций и служебные данные.

### Клиент

Клиент не входит во внутренний кабинет. Он получает публичную ссылку вида `/delivery/:token` и по ней:
- видит номер заказа;
- выбирает удобную дату;
- выбирает половину дня: `До обеда` или `После обеда`;
- подтверждает выбор.

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

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

1. Заказ попадает в систему.
2. Менеджер и внутренние сотрудники ведут заказ по этапам.
3. Когда заказ готов к доставке, логист запускает приглашение клиенту.
4. Клиент выбирает слот по публичной ссылке.
5. Система переводит заказ в `Доставка согласована`.
6. Логист и водитель доводят доставку до результата.

### Сценарий клиента

Клиентская страница работает по token из таблицы `public.delivery_invitations`. Для рабочего показа используется заранее загруженный seed-набор данных.

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

`/delivery/client-flow-1001`

Эта ссылка должна показывать:
- заказ `CD-240031`;
- четыре варианта слота;
- две даты;
- две половины дня: `До обеда` и `После обеда`.

После подтверждения выбора:
- invitation переводится в состояние `agreed`;
- заказ переводится в `Доставка согласована`;
- в `order_history` появляется запись о подтверждении;
- в `delivery_slots` фиксируется подтверждённый слот.

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

### Основные таблицы

- `public.users` — пользователи и роли;
- `public.orders` — заказы и текущие статусы;
- `public.order_history` — история изменений;
- `public.delivery_slots` — возможные и подтверждённые слоты доставки;
- `public.delivery_invitations` — публичные invitation token и состояние клиентского flow;
- `public.integration_events` — технические и интеграционные события.

### Важные поля для клиентского flow

- `delivery_invitations.token_hash` — хеш публичного токена;
- `delivery_invitations.state` — состояние приглашения;
- `delivery_invitations.available_slots` — список доступных вариантов для клиента;
- `delivery_invitations.delivery_date` и `delivery_invitations.delivery_time` — выбранный или основной слот;
- `orders.status` — текущий рабочий статус заказа;
- `orders.delivery_agreement_status` — статус согласования доставки.

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

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

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

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

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

- [README](/Users/mihailkucer/Documents/super-sam/README.md)
- [Архитектура](/Users/mihailkucer/Documents/super-sam/docs/architecture.md)
- [Сценарии](/Users/mihailkucer/Documents/super-sam/docs/scenarios.md)
- [Edge Functions](/Users/mihailkucer/Documents/super-sam/supabase/functions/README.md)