BarevClub/docs/PRD.md

Barev Club — бизнес-требования для разработки (промпт для Claude Code)

Как использовать. Положи этот файл в корень пустого репозитория как docs/PRD.md и напиши Claude Code: «Прочитай docs/PRD.md. Сначала предложи архитектуру, структуру репозитория и план по этапам, задай уточняющие вопросы из раздела 13. Код не пиши, пока я не подтвержу план. Потом реализуй Этап 1».

---

0. Роль и правила работы для Claude Code

Ты — ведущий full-stack разработчик. Строишь платформу Barev Club по этому документу.

• Работай по этапам (раздел 11). Не начинай следующий этап, пока текущий не принят по критериям из раздела 12.
• Перед кодом каждого этапа покажи план: какие модули, таблицы, эндпоинты, экраны.
• Если требование неоднозначно — спроси, не додумывай бизнес-логику. Технические решения принимай сам и коротко объясняй.
• Секреты только через .env (+ .env.example в репо). Никаких токенов в коде.
• Покрывай тестами бизнес-логику: статусы заказов, расчёт цены со скидкой, назначение исполнителя, промокоды.
• Добавь seed-данные (услуги, исполнители, партнёры, тестовые заказы), чтобы всё можно было показать без реальных пользователей.
• Все тексты интерфейса — через i18n, ни одной строки хардкодом.

---

1. Продукт и цель

Barev Club — клуб-сервис для эмигрантов в Ереване. Клиенты приходят через агентства недвижимости (QR/промокод в договоре аренды). Внутри одного Telegram-приложения клиент заказывает услуги по четырём направлениям и пользуется скидками партнёров.

Слоган: «Ереван — как дома. С первого дня.»

Цель MVP: клиент из агентства за 2 минуты открывает бота, выбирает язык, заказывает услугу и видит статус; админ назначает исполнителя; исполнитель проводит заказ по шагам.

Ключевые метрики:

• % лидов от агентства, активировавших бота;
• % активировавших, сделавших первый заказ;
• повторные заказы за 30 дней;
• конверсия в Barev+;
• лиды и выручка в разрезе агентств.

---

2. Направления и услуги (только эти, ничего не добавлять)

Направление	Услуги	Формат
Быт	Клининг (обычная / генеральная / после ремонта), Ремонт (сантехника, электрика, мелкий ремонт), Трансфер (аэропорт ↔ адрес)	на адресе клиента / по городу
Документы	Соцкарта, Нотариальный перевод паспорта, ВНЖ	офлайн, с загрузкой документов
Обучение и карьера	Языки (армянский, английский; пакет уроков), Карьерный консультант (разбор резюме, план поиска работы)	онлайн / офлайн
Скидки и подарки	Скидки и подарки партнёров: кофейни, рестораны, другие	по клубной карте

Цены — справочник в админке, на фронте показываются как «от N ֏». Конкретные цены и проценты скидок задаёт админ.

---

3. Роли

Роль	Где работает	Что делает
Клиент	Telegram-бот + Mini App	Заказывает услуги, видит статусы, чат с исполнителем, оценивает, пользуется клубной картой, оформляет Barev+
Исполнитель	Отдельный Telegram-бот для исполнителей + его Mini App	Подтипы: клинер, мастер, водитель, преподаватель, карьерный консультант. Видит заказы на день, ведёт по шагам, чек-лист, фотоотчёт, заработок. Исполнитель — либо частное лицо (фрилансер), либо сотрудник компании-партнёра
Компания-партнёр (исполнитель)	Тот же бот исполнителей, роль «диспетчер компании»	Клининговая компания, автопарк, языковая школа и т.п. Получает заказы, назначенные на компанию, и распределяет их между своими сотрудниками
Админ / оператор	Веб-админка	Канбан заказов, назначение исполнителей, справочники, клиенты, финансы, отчёты по агентствам
Агентство	Источник лидов (в MVP без кабинета)	Получает уникальный промокод/deep-link. Получает % от оплаченных заказов привлечённых клиентов; в отчётах видно его лиды, выручку и начисленное вознаграждение
Партнёр	В MVP без кабинета	Принимает клубную карту; проверяет её по коду на веб-странице проверки

---

4. Каналы и поверхности

1. Лендинг (веб, адаптив) — за основу дизайн «Лендинг v2 · плотный».
2. Клиентский Telegram-бот — точка входа, онбординг, уведомления, ретрансляция чата.
3. Клиентский Mini App — основной интерфейс клиента.
4. Бот исполнителей + его Mini App — отдельный бот: назначения, принятие заказов, пошаговые статусы, чек-листы, фотоотчёты, заработок; роль «диспетчер компании» для компаний-партнёров.
5. Веб-админка — для операторов, desktop-first.

Домен лендинга у владельца уже есть (значение — в .env, LANDING_DOMAIN). Оба бота создаём в BotFather; токены — в .env (CLIENT_BOT_TOKEN, PRO_BOT_TOKEN).

Языки везде: RU, EN, 中文 (ZH), Հայերեն (HY), ES.

---

5. Функциональные требования

5.1 Лендинг (LND)

• LND-1. Секции, как в макете v2:
  • шапка с языками и кнопкой «Открыть в Telegram»;
  • hero: заголовок, подзаголовок, CTA и 3 шага;
  • превью «Мои заявки»;
  • плашки «5 языков» и «Без установки»;
  • 4 блока направлений со списком услуг и ценами «от»;
  • «Как это работает» в 4 шага;
  • баннер агентства;
  • тарифы Barev / Barev+;
  • FAQ-аккордеон;
  • подвал.
• LND-2. Переключатель 5 языков меняет все тексты; язык запоминается и передаётся в бота.
• LND-3. Все CTA — deep-link в бота t.me/<bot>?start=<payload>. Payload несёт язык, UTM и код агентства, если он есть в URL лендинга (?a=<agency_code>).
• LND-4. SEO-мета на каждом языке, OG-картинка, быстрая загрузка (Lighthouse ≥ 90 на мобильном).
• LND-5. Цены и тексты услуг подтягиваются из справочника, а не хардкодятся.

5.2 Онбординг в боте (ONB)

• ONB-1. /start с payload: определить язык и агентство, создать клиента и сохранить источник (агентство, UTM).
• ONB-2. Если язык не пришёл — выбор из 5 языков.
• ONB-3. Согласие на обработку персональных данных (ссылка на политику), без согласия дальше не пускать.
• ONB-4. Если клиент пришёл с кодом агентства — автоматически активировать подарочный месяц Barev+ и показать сообщение.
• ONB-5. Кнопка «Открыть приложение» запускает Mini App.
• ONB-6. Ручной ввод промокода агентства, если клиент пришёл без deep-link.

5.3 Каталог и заказ (ORD)

• ORD-1. Главная Mini App:
  • приветствие;
  • блок «Мои заявки» с активными заказами;
  • быстрые кнопки;
  • плитки 4 направлений;
  • нижняя навигация: Главная / Услуги / + / Скидки / Профиль.
• ORD-2. Карточка услуги с параметрами, зависящими от услуги:
  • клининг: тип уборки, примерная длительность;
  • ремонт: категория и описание проблемы с фото;
  • трансфер: рейс, количество пассажиров и багажа, адрес;
  • языки: язык, уровень, онлайн/офлайн, пакет уроков;
  • консультант: тема, загрузка резюме;
  • документы: тип документа, загрузка сканов, для кого (сам / члены семьи).
• ORD-3. Выбор даты и времени из доступных слотов (для трансфера — время рейса).
• ORD-4. Расчёт цены: базовая цена по параметрам минус скидка Barev+ по направлению. Показывать строки «Стоимость», «Скидка Barev+», «Итого».
• ORD-5. Подтверждение заказа → статус «Новый» → уведомление клиенту и в админку.
• ORD-6. Бесплатная отмена и перенос — не позднее чем за 24 часа до начала услуги. Позже — отмена с удержанием (процент настраивается в админке по услугам) или только через оператора. Порог 24 ч тоже хранится в настройках, не в коде.
• ORD-7. Заказ «Повторить» из истории с теми же параметрами.

5.4 Статусы заказов (STS)

Своя последовательность статусов для каждой категории (state machine с проверкой допустимых переходов):

Категория	Статусы
Клининг	Новый → Назначен → В пути → Уборка → Готово
Ремонт	Новый → Назначен → На месте → Смета согласована клиентом → Ремонт → Готово
Трансфер	Новый → Назначен → Водитель ждёт → В пути → Завершён
Языки	Записан → Урок N запланирован → Идёт урок → Урок завершён (прогресс «урок N из M»)
Карьера	Новый → Консультант назначен → Резюме получено → Встреча → План отправлен
Документы	Новый → Документы проверяются → Подача → Готово (+ «Нужны доп. документы»)

Плюс «Отменён» из допустимых состояний. Каждый переход пишется в историю: кто, когда, комментарий. Клиент получает уведомление о каждом переходе.

• STS-1. В ремонте исполнитель вносит смету, клиент принимает или отклоняет её в Mini App. Без согласия переход в «Ремонт» невозможен.

5.5 Кабинет исполнителя (PRO)

• PRO-1. Шапка: имя, роль, статус смены (на смене / не на смене), заработок за день, рейтинг.
• PRO-2. Список заказов на сегодня; «Сейчас» — текущий заказ:
  • адрес или «Онлайн»;
  • язык клиента;
  • заметка клиента.
• PRO-3. Пошаговые кнопки по роли:
  • клинер: «Я на месте» → «Начать уборку» → чек-лист зон → «Завершить и отправить фото»;
  • мастер: «Я на месте» → «Начать работу» → чек-лист «Диагностика / Смета / Ремонт / Фото» → «Закрыть»;
  • водитель: «Я в аэропорту» → «Пассажир в машине» → «Багаж, адрес» → «Завершить поездку»;
  • преподаватель: «Открыть урок» → «Начать» → «Повторение / Новая тема / ДЗ» → «Завершить урок»;
  • консультант: «Открыть встречу» → «Начать» → «Резюме / План / Материалы» → «Завершить».
• PRO-4. Закрыть заказ нельзя, пока не отмечены все пункты чек-листа. Фото обязательно там, где требует чек-лист.
• PRO-5. Исполнитель принимает или отклоняет назначенный заказ (таймаут настраивается). Отказ возвращает заказ в «Новые».
• PRO-7. Заказ можно назначить на частного исполнителя или на компанию-партнёра. Во втором случае диспетчер компании в боте исполнителей назначает конкретного сотрудника; до этого заказ в админке помечен «Назначен на компанию».
• PRO-8. Выплаты: для фрилансеров ставка задаётся на исполнителе (фикс за услугу или % от заказа — выбирается в профиле исполнителя); для компаний — договорная ставка на уровне компании. Расчёт выплат — в разделе финансов админки.
• PRO-6. История заказов и заработок за период.

5.6 Веб-админка (ADM)

• ADM-1. Канбан заказов: Новые / Назначены / В работе / Готово, фильтр по направлению и услуге, по дате, поиск.
• ADM-2. Сводка: всего заказов, без исполнителя, выручка за день, свободные исполнители.
• ADM-3. Назначение исполнителя:
  • система подсказывает свободного исполнителя нужной категории с учётом языка клиента, района и текущей загрузки;
  • назначение в один клик или выбор вручную.
• ADM-4. Карточка заказа: параметры, история статусов, переписка, файлы, цена, оплата.
• ADM-5. Справочники:
  • направления и услуги с параметрами и ценами;
  • исполнители: роль, языки, районы, график, ставка;
  • партнёры: категория, скидка, адрес, условия;
  • агентства: код, условия вознаграждения;
  • промокоды;
  • тарифы Barev+ и скидки по направлениям.
• ADM-6. Клиенты: список, профиль, заказы, источник (агентство), статус Barev+.
• ADM-7. Финансы:
  • выручка по услугам;
  • выплаты исполнителям за период;
  • вознаграждение агентствам;
  • экспорт в CSV.
• ADM-8. Отчёт по агентствам: лиды → активировали → заказали → оплаченная выручка → начисленное вознаграждение (% агентства от оплаченных заказов его клиентов). Процент задаётся на агентстве; срок, в течение которого клиент «принадлежит» агентству, — настройка (см. раздел 13). Выгрузка акта за месяц в CSV.
• ADM-9. Роли в админке: владелец (всё) и оператор (без финансов и настроек).

5.7 Чат и уведомления (MSG)

• MSG-1. Чат клиент ↔ исполнитель внутри заказа через бота-посредника; номера телефонов не раскрываются. Чат закрывается после завершения заказа + N часов.
• MSG-2. Push в Telegram:
  • смена статуса;
  • назначение;
  • напоминание за 24 часа и за 1 час;
  • просьба оценить.
• MSG-3. Все сообщения бота — на языке пользователя.

5.8 Скидки и клубная карта (CRD)

• CRD-1. Клубная карта в Mini App: имя, уровень (Barev / Barev+), QR и короткий код.
• CRD-2. Каталог партнёров: категория, скидка или подарок, адрес, условия.
• CRD-3. Публичная страница проверки карты для партнёра (/check/<code>): действительна ли карта, уровень. Персональных данных кроме имени не показывать.
• CRD-4. Логирование использований карты у партнёров для отчёта.

5.9 Членство Barev / Barev+ (SUB)

• SUB-1. Barev — бесплатно: каталог, клубная карта, скидки партнёров.
• SUB-2. Barev+ — ежемесячная подписка: скидка N% на Документы, Быт, Обучение и карьеру (проценты настраиваются по направлениям).
• SUB-3. Подарочный месяц по коду агентства, один раз на клиента. Напоминание за 3 дня до окончания.
• SUB-4. Экран выбора членства с переключением тарифов, как в макете.

5.10 Оценки (RTG)

• RTG-1. После завершения — оценка 1–5 и комментарий. Рейтинг исполнителя считается автоматически.
• RTG-2. Оценка ≤ 3 создаёт задачу для оператора.

5.11 Оплата (PAY)

• PAY-1. Способ оплаты на старте ещё не выбран. В MVP: заказ имеет поле «способ оплаты» (справочник, настраивается в админке) и статус оплаты; админ или исполнитель отмечает «оплачено» вручную. Никакой реальной интеграции с платёжкой в Этапах 1–2.
• PAY-2. Этап 3: онлайн-оплата и рекуррентная подписка через платёжного провайдера, работающего в Армении (выбор провайдера — открытый вопрос). Архитектуру сразу заложить через абстракцию PaymentProvider с заглушкой ManualPaymentProvider.
• PAY-3. Вознаграждение агентств и выплаты исполнителям считаются только по заказам со статусом оплаты «оплачено».

---

6. Нефункциональные требования

• Безопасность:
  • проверка подписи Telegram initData на бэкенде для каждого запроса Mini App;
  • RBAC по ролям;
  • админка за логином с 2FA.
• Персональные данные:
  • сканы паспортов и документов хранятся в приватном объектном хранилище с шифрованием;
  • доступ по временным ссылкам только у оператора и назначенного исполнителя «Документы»;
  • автоудаление через 90 дней после завершения заказа (значение в настройках);
  • логирование доступа к файлам.
• i18n: 5 языков. RU — исходный язык. EN, ZH, HY, ES — машинный черновой перевод, который делаешь ты; каждый ключ помечается статусом needs_review, пока носитель языка его не проверит. Сделай простой экран или экспорт (CSV/JSON) для проверки переводов носителями. Направление письма везде LTR. Шрифты с поддержкой кириллицы, армянского и китайского: фолбэк для армянского и китайского, если основной шрифт их не поддерживает.
• Время: часовой пояс Asia/Yerevan. Валюта — драм (֏).
• Надёжность:
  • ежедневные бэкапы БД;
  • логирование ошибок (Sentry или аналог);
  • аудит-лог действий админов.
• Производительность: Mini App открывается быстрее 2 секунд на 4G.
• Масштаб MVP: до нескольких тысяч клиентов и сотен заказов в день, без микросервисов.

---

7. Модель данных (основные сущности)

User (telegram_id, роль, язык, имя, телефон?) · Client (источник/агентство, UTM, статус подписки) · Provider (роль-подтип, частный или сотрудник компании, языки, районы, график, тип ставки и ставка, рейтинг, на смене) · ProviderCompany (название, категории услуг, диспетчеры, договорная ставка) · AgencyCommission (агентство, заказ, % и сумма, период) · Category · Service (параметры как JSON-схема, базовая цена) · Order (клиент, услуга, параметры, слот, адрес/онлайн, цена, скидка, итог, статус, исполнитель, оплата) · OrderStatusHistory · ChecklistItem / OrderChecklist · Estimate (смета ремонта) · OrderFile · Message · Rating · LessonPackage (уроков всего / пройдено) · Partner · CardUsage · Subscription · Agency · PromoCode · Payout · AdminUser · AuditLog.

---

8. Рекомендуемый стек (можно предложить лучше и обосновать)

• Монорепо (pnpm/turborepo): apps/landing, apps/miniapp-client, apps/miniapp-pro, apps/admin, apps/bot-client, apps/bot-pro, packages/db, packages/ui, packages/i18n, packages/core (бизнес-логика, state machines).
• Фронт: Next.js + TypeScript (лендинг, админка), React + Vite (оба Mini App) с Telegram WebApp SDK.
• Боты: Node.js + grammY, два отдельных бота с общей бизнес-логикой из packages/core.
• БД: PostgreSQL + Prisma.
• Хранилище файлов: S3-совместимое, приватные бакеты.
• Очереди и напоминания: BullMQ + Redis или cron.
• Деплой: Docker. Один сервер на MVP, staging и prod окружения.

---

9. Дизайн-система (из макетов Barev Club)

• Цвета:
  • фон #FBF6EE, текст #1E1B1A, вторичный текст #5C5550, акцент #B8235A, заголовки на розовом #4A1028;
  • направления: Быт #A8C38A, Документы #F9CDB0, Обучение и карьера #CFC8F5, Скидки и подарки #F7DA6E;
  • дополнительные: розовый #F6C3D3, голубой #BCD0F2.
• Шрифты: заголовки Rubik (700–800, приём «жирное + курсив»), текст Onest.
• Форма: крупные скругления (карточки 24–40px, кнопки-таблетки 999px), тёмная нижняя навигация-таблетка с белой «+» по центру, декоративные «цветы» (scalloped shapes).
• Доступность: контраст текста ≥ 4.5:1, зоны нажатия ≥ 44px.
• Сделать packages/ui с токенами и компонентами, чтобы лендинг, Mini App и админка выглядели единообразно.

---

10. Ключевые пользовательские сценарии

1. Клиент из агентства: QR в договоре → лендинг или сразу бот с кодом агентства → язык → согласие → подарочный Barev+ → заказ клининга со скидкой → статус «Назначен» → чат с клинером → «Готово» с фотоотчётом → оценка.
2. Трансфер: заказ с номером рейса → водитель назначен → «Водитель ждёт» → «В пути» → «Завершён».
3. Ремонт со сметой: мастер на месте → вносит смету → клиент согласует → ремонт → фото → закрытие.
4. Документы: клиент выбирает «Соцкарта» → загружает сканы → оператор проверяет → «Нужны доп. документы» или «Подача» → «Готово».
5. Языки: покупка пакета из M уроков → расписание → каждый урок закрывается преподавателем → прогресс «урок N из M».
6. Скидка у партнёра: клиент показывает карту → партнёр открывает страницу проверки → использование логируется.
7. Админ: новый заказ появляется в канбане → «Назначить: <подсказанный исполнитель>» → исполнитель принимает.

---

11. Этапы

• Этап 1 (MVP-ядро):
  • монорепо, БД, i18n, packages/ui;
  • лендинг v2;
  • бот с онбордингом и кодами агентств;
  • Mini App клиента: каталог, заказ, «Мои заявки», статусы;
  • услуги Клининг и Трансфер;
  • админка: канбан, назначение, справочники услуг и исполнителей;
  • бот исполнителей и его Mini App для клинера и водителя (частные исполнители и диспетчер компании);
  • уведомления; оплата отмечается вручную;
  • машинный перевод на 5 языков со статусом needs_review.
• Этап 2:
  • Ремонт со сметой, Документы с загрузкой файлов, Языки (пакеты уроков), Карьерный консультант;
  • чат через бота;
  • оценки;
  • отчёт по агентствам;
  • финансы и выплаты.
• Этап 3:
  • клубная карта и партнёры со страницей проверки;
  • Barev+ с подарочным месяцем, затем онлайн-оплата и рекуррентная подписка;
  • аудит и автоудаление файлов.

---

12. Критерии приёмки (по этапу 1)

• Лендинг на 5 языках, все CTA ведут в бота с правильным payload (язык, агентство, UTM).
• /start с кодом агентства создаёт клиента с источником и активирует подарочный Barev+.
• Клиент оформляет клининг и трансфер, видит итог со скидкой, получает уведомление о каждом статусе.
• Недопустимый переход статуса отклоняется бэкендом (тесты на state machine для каждой категории).
• В админке новый заказ появляется в «Новых». Кнопка назначения предлагает свободного исполнителя нужной категории с учётом языка, назначение уходит исполнителю.
• Исполнитель не может закрыть заказ без всех пунктов чек-листа.
• Все строки интерфейса переведены (проверка: нет ключей без перевода).
• Запросы Mini App без валидного initData отклоняются.
• Seed-данные позволяют пройти все сценарии этапа на staging.

---

13. Принятые решения и открытые вопросы

Уже решено владельцем:

• Оплата на старте не выбрана → ручная отметка «оплачено», абстракция PaymentProvider (PAY-1, PAY-2).
• Исполнители смешанные: фрилансеры и компании-партнёры (PRO-7, PRO-8).
• Агентства получают % от оплаченных заказов привлечённых клиентов (ADM-8, PAY-3).
• Для исполнителей — отдельный Telegram-бот (раздел 4).
• Бесплатная отмена и перенос — за 24 часа до услуги (ORD-6).
• Сканы документов хранятся 90 дней после завершения заказа (раздел 6).
• Переводы: машинный черновик + проверка носителем (раздел 6).
• Домен есть, ботов ещё нет — создаём в BotFather (раздел 4).

Ещё открыто (спроси перед стартом, а пока используй дефолты из скобок):

1. Цены по услугам, % скидки Barev+ по направлениям и цена подписки (пока seed-значения-заглушки в админке).
2. Какой % получают агентства и как долго клиент «закреплён» за агентством (пока 10% и 12 месяцев, обе настройки — в админке).
3. Размер удержания при поздней отмене (пока 0%, настройка по услугам).
4. Платёжный провайдер для Этапа 3.