# 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/?start=`. Payload несёт язык, UTM и код агентства, если он есть в URL лендинга (`?a=`). - **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/`): действительна ли карта, уровень. Персональных данных кроме имени не показывать. - **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.