supersam/docs/superpowers/specs/2026-04-14-product-docs-and-real-client-flow-design.md

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 как основной обзор проекта.