Y&P Lead Radar

Сервис находит новые объявления на List.am по фильтрам клиента, доставляет их агентам в Telegram и ведёт каждый объект как лид в CRM до сделки. Домен: listcrm.yandpconsulting.com.

Написан с нуля по ТЗ. Из прежней CRM (../crmyerevan-…) взят только модуль парсера — см. docs/PARSER.md.

Структура

Путь	Назначение
apps/api	Бэкенд: Fastify, Postgres (Drizzle). Один API для веб-кабинета и Mini App
apps/web	Веб-кабинет и Mini App: React, Tailwind, тема сайта yandpconsulting.com
packages/shared	Тарифы и лимиты, роли, воронки по умолчанию, сопоставление с фильтрами

Запуск на своём компьютере

Нужны Node 22+, pnpm 10, Docker.

cp .env.example .env
pnpm install
pnpm db:up            # Postgres в Docker, порт 5433
pnpm db:migrate
pnpm --filter @lr/api superadmin <email> "Имя"   # печатает пароль суперадмина
pnpm dev:api          # http://localhost:3100
pnpm dev:web          # http://localhost:5174

Проверки: pnpm typecheck && pnpm test (тестам API нужен запущенный Postgres и база leadradar_test).

После изменения apps/api/src/db/schema.ts: pnpm db:generate && pnpm db:migrate — появится новый файл миграции в apps/api/drizzle/; старые файлы миграций не правятся и не удаляются.

Что готово

• Схема данных всех сущностей ТЗ (раздел 9).
• Вход по email и паролю, через Telegram Login и Telegram Mini App; подтверждение email и сброс пароля (письма пока пишутся в лог API — почтовый сервис не выбран).
• Компании, тарифы и лимит участников, роли, приглашения, удаление агента.
• Состояние подписки: активна → просрочена (15 дней) → только чтение.
• Суперадмин: компании, тариф, дата окончания, отсрочка, вход в кабинет, состояние парсера.
• Парсер → общая база → фильтры → лиды: все категории недвижимости list.am, в базу идут объявления не старше 3 дней, оттуда — клиентам по общим и личным фильтрам.
• Бот: уведомление о лиде с кнопкой «Беру», атомарный захват, «Взял(а) Имя» у остальных, привязка Telegram, /pause и /resume, тихие часы. Очередь сообщений с повторами и лимитом темпа.
• Пул: возврат через 24 часа без смены статуса, предупреждение за 2 часа, повторное «Беру».
• Воронка объекта: статусы, отказ с причиной, сделка с комиссией, назначение и переназначение, комментарии, напоминания, история, «Это агент», лиды вручную.
• Воронка клиента: покупатели и арендаторы, запрос клиента, подбор подходящих объектов из CRM, отметки «предложен» и «показан», переназначение руководителем, напоминания в боте.
• Общая сделка: объект и клиент из CRM закрываются один раз, комиссия записывается одной строкой из двух частей: с собственника — агенту объекта, с покупателя или арендатора — агенту клиента; если стороны в CRM нет, обе части получает агент второй стороны. Суммы и дату исправляет руководитель.
• Оплата агентов: оклад, процент с части комиссии агента (отдельно для продажи и аренды) или оклад + процент; план на месяц (сделки, комиссия) и бонус за него — суммой или надбавкой к проценту. Ведомость «Кому сколько платить» за месяц; строка сотрудника раскрывает его сделки, начисления, ручные записи (премия, штраф, аванс) и отметку «выплачено». Выплата закрывает месяц: он считается по условиям и курсам на день выплаты, а изменения его сделок и недоплата переходят перерасчётом в ближайший месяц без выплаты. Агент видит свои условия, сделки, начисления и историю выплат в «Настройках».
• Динамика и рейтинг: сделки и комиссия по месяцам — по компании и по каждому сотруднику (агент видит только свою); рейтинг месяца виден всем: место, число сделок, выполнение плана, без сумм. Ведомость со сделками выгружается файлом для Excel.
• Суперадмину в Telegram приходит уведомление о каждой новой регистрации и о компании, созданной самостоятельно: имя, email, Telegram. Приветствие бота (ответ на /start тому, кто ещё не привязал Telegram): текст на трёх языках и до 10 файлов — в разделе «Сообщения». Следом бот спрашивает язык кнопками; выбор запоминается, на нём бот отвечает и создаётся аккаунт.
• Отчёты в Telegram (включает руководитель в настройках компании): итоги недели по понедельникам и итоги месяца с ведомостью первого числа, в 9 утра по Еревану.
• Настройка воронок: руководитель переименовывает, добавляет, удаляет и переставляет промежуточные статусы и причины отказа в обеих воронках.
• База (Team, Agency): объекты и клиенты (покупатели, арендаторы), закрытые сделкой или отказом; у клиента — связанные объекты. Раз в сутки объекты из CRM проверяются на list.am: снятое объявление получает отметку и дату. Повторно опубликованный объект приходит новым лидом с блоком «Уже был в работе».
• Аналитика (Team, Agency, руководителю): сводка, воронка, таблица по агентам (взято, скорость реакции, возвраты в пул, конверсия по этапам, сделки, комиссии), причины отказа, выгрузка в CSV; отдельно по объектам и по клиентам.
• Суперадмин — «Объявления»: вся общая база объявлений с поиском, фильтрами и карточкой «кому ушло лидом». Настройки парсера в админке: включение, свежесть в днях, пауза, число страниц, категории, ключ ридера Jina, проверка снятых объявлений — без перезапуска сервиса. Ночная пауза (в тех же настройках, по умолчанию 22:00–8:00 по Еревану): парсер и проверка снятых не работают (экономия токенов Jina), сторож парсера ночью молчит. Догрузка фото (кнопка на странице парсера): объявления за последние 24 часа, ставшие лидами, у которых в базе только обложка или фото не открываются, — заново читается галерея со страницы List.am (без переписывания текста моделью); идёт в фоне пачками, прогресс виден в админке.
• Биллинг: счета за установку, фикс и «%» с расшифровкой по сделкам; смена тарифа со следующего месяца; напоминания за 7, 3 и 1 день и при просрочке; ручная отметка оплаты суперадмином; контракт платёжного провайдера для онлайн-оплаты — см. docs/BILLING.md.
• Суперадмин — «Счета» и «Сообщения»: сводка (активные компании, выручка за месяц, просрочки), счета всех компаний, курсы валют; сообщения в Telegram всем, компании, руководителям или одному пользователю с журналом отправок.
• Поддержка: всё, что человек пишет боту (текст, фото, файл), попадает в обращение. Суперадмин отвечает в разделе «Поддержка» — ответ уходит в тот же чат — и закрывает кнопкой «Проблема решена». В кабинете у пользователей есть раздел «Поддержка» с подсказкой, как написать.
• Характеристики объявления: со страницы List.am берутся удобства по разделам, «можно с детьми», «можно с животными», мебель, ремонт, предоплата и остальные поля. Видны в карточке объекта; правила про детей и животных — ещё и в уведомлении бота. Телефон автора не собирается.
• Кто будет жить (карточка клиента): один, с другом, пара; дети и животные с количеством и возрастом; до 10 фото. Подбор не предлагает объекты, где с детьми или животными прямо нельзя.
• Анкета соискателя: у каждого агента своя ссылка на клиентский бот (команда /anketa в основном боте или кнопка в разделе «Клиенты»). Соискатель отвечает на вопросы — в CRM появляется клиент, закреплённый за агентом, а агент получает в бот вопрос «Показать подходящие объекты?». Телефон обязателен: пропустить нельзя, номер отправляется кнопкой «Отправить мой номер» или пишется вручную.
• Чат с клиентом (карточка клиента): переписка с клиентом, заполнившим анкету, через клиентский бот. Пишут ответственный агент и руководитель — текст, фото и файлы; клиент видит ответ с именем агента. Сообщения клиента попадают в чат (фото — ещё и в фото карточки), агенту приходит уведомление в основной бот с кнопкой «Открыть»; в списке клиентов — счётчик непрочитанных. Вложения хранятся у Telegram.
• Страница подборки для клиента: <кабинет>/<компания>/<код> — объекты, прикреплённые к клиенту, и запись на показ по дням. Адрес и ссылка на List.am на странице скрыты. Запись на показ приходит создателю ссылки в бот и появляется в карточке клиента.
• Фото и текст на странице клиента (логика из бота list-am-bot): для объектов, которые показывают клиенту, догружается полный набор фото объявления; фото отдаёт сам сервис, срезая сверху 8 % высоты (CROP_TOP_PERCENT); текст собирается по шаблону-карточке, а с ключом OPENROUTER_API_KEY дополняется абзацем из описания. Адреса в тексте нет.
• Карточка объекта: все фото объявления (обрезанные, догружаются в фоне после первого открытия), «Описание для клиента» с кнопкой копирования и поле «Телефон собственника» — номер агент берёт из объявления сам; он сохраняется в карточке и, если в общей базе его не было, в базе объявлений.
• Комиссия агентства: руководитель задаёт в настройках процент или фикс — отдельно для объектов и клиентов, продажи и аренды. В карточке видно условие и ожидаемую сумму; агент может поменять условие для своей карточки. При закрытии сделки сумма комиссии подставляется по условию.
• Оплата агентов: руководитель задаёт каждому сотруднику оклад, процент с комиссии по его сделкам или оклад + процент («Команда»). Там же таблица «Кому сколько платить» за выбранный месяц; агент видит свои условия и начисления в настройках.
• Отделы (раздел «Команда»): руководитель создаёт отделы, назначает и снимает сотрудников, задаёт фильтры отдела. У отдела свои объекты и клиенты: сотрудник видит только данные своего отдела, руководитель и суперадмин — все отделы (с выбором отдела в списках). Одно объявление под фильтрами двух отделов приходит каждому своей карточкой; общий фильтр компании — в каждый отдел с сотрудниками (и в «без отдела», если там есть агенты). Уведомления — сотрудникам отдела; руководителю — по общим фильтрам и фильтрам отделов, одно на объект. При смене отдела объекты и клиенты сотрудника переходят с ним. Удалить можно отдел без сотрудников, клиентов и объектов в работе.
• Рабочий список объектов показывает только актуальное: снятые с List.am и закрытые сделкой или отказом объекты не попадают в список, поиск, подбор, страницу клиента и витрину — они остаются в базе и в «Базе» (фильтр «Сняты с List.am»).
• Избранное и «Не просмотренные»: звёздочка в списке и карточке, у каждого своя; фильтры сочетаются со всеми остальными. Цена в АМД или ДОЛ: границы задаются в выбранной валюте, цены объектов в другой валюте пересчитываются по курсу из админки («Счета»); при смене валюты введённые границы пересчитываются.
• «Отправить в бот» в карточке объекта: фото, описание и комиссия приходят основным ботом в личный чат того, кто нажал. Без привязанного Telegram — инструкция и кнопка привязки.
• Демо-компании: scripts/seed-demo.mjs создаёт «Демо: Аренда» и «Демо: Продажа» на настоящих объявлениях из базы, scripts/seed-demo-backdate.sql раскладывает их историю по трём неделям.
• Мастер первой настройки: первый фильтр, привязка бота, приглашение агентов.
• Mini App: тот же кабинет в Telegram с входом без пароля и нижней панелью разделов. Тариф Solo в браузере видит только подписку и профиль — рабочие разделы открываются в Telegram.
• Веб-кабинет: объекты (таблица и канбан), карточка, клиенты, база, аналитика, фильтры, команда, настройки, подписка, админка; три языка, тёмная и светлая тема.
• Боевая сборка: Docker-образы, ежедневная резервная копия, скрипт выкладки — см. docs/DEPLOY.md.

Что дальше

1. Выкладка на VPS по docs/DEPLOY.md: домен, боевой бот, первая выкладка.
2. Ручная приёмка на боевом стенде — что осталось, перечислено в docs/ACCEPTANCE.md.
3. Платёжный провайдер, почтовый сервис, вычитка армянских текстов.