Monorepo skeleton, Prisma schema, core domain and services with tests

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/PRD.md

@@ -0,0 +1,328 @@
+# 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.