# Product Docs And Real Client Flow Design

**Goal:** Подготовить один общий документ по приложению с описанием задач, ролей и пользовательских сценариев, а также довести публичную клиентскую страницу до рабочего Supabase flow на реальном invitation token и seed-данных.

## What We Are Building

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

Параллельно нужно довести клиентскую страницу `/delivery/:token` до реально работающего сценария на базе `delivery_invitations`, `orders` и `delivery_slots`, чтобы можно было показать не showcase-заглушку, а настоящий flow.

## Product Documentation Shape

Главный документ должен быть продуктовым, а не набором технических заметок. Рекомендованная структура:

1. Назначение системы
2. Основные задачи приложения
3. Роли и зоны ответственности
4. Ключевые рабочие сценарии
5. Сценарий клиента по публичной ссылке
6. Какие данные живут в Supabase
7. Как подготовить систему к показу
8. Полезные ссылки на более глубокие технические документы

Этот документ должен стать основной точкой входа из `README`.

## Real Client Flow

Клиентская страница должна работать на реальном token из `delivery_invitations`, без локального fallback как основного сценария.

Для этого:
- `get-delivery-invitation` должен корректно работать с тем способом вызова, который использует фронтенд;
- ответ invitation должен возвращать все данные, нужные клиентскому экрану: заказ, клиент, state, доступные слоты, выбранные `delivery_date` и `delivery_time`;
- `confirm-delivery-choice` должен фиксировать выбор клиента и обновлять заказ/историю;
- seed должен создавать один рабочий invitation token, который можно открыть в браузере и пройти до подтверждения.

## Seed Strategy

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

Вместо текстовых слотов вида `14 апреля, первая половина дня` лучше хранить технически стабильный формат, который фронтенд однозначно разбирает, например `YYYY-MM-DD, До обеда`.

## UX Decisions

- В клиентском экране главное действие — выбор даты и половины дня без лишнего текста.
- Тексты должны звучать как рабочий сервис доставки.
- В документе роли описываются через задачи и результат, а не через внутреннюю реализацию интерфейса.

## Validation

- Тесты API/клиента фиксируют рабочий invitation flow.
- После seed известный токен должен открываться на `/delivery/:token`.
- Общий документ должен быть связан с `README` как основной обзор проекта.