🎯 Local Lead Studio

Поиск клиентов для техспеца: карточки бизнесов из Яндекс.Карт → чистая база лидов → готовность к сделке.

---

Приоритет — бизнесы без сайта (кандидаты на новый сайт). Те, у кого сайт есть, можно собирать отдельно как редизайн. Работает локально, на одной машине. Не публичный сервис.

✨ Возможности

• 🔎 Поиск по городам и нишам — Яндекс.Карты.
• 🧹 Фильтры: сетевики, мин. отзывы, наличие фото, «есть сайт / нет сайта».
• ♻️ Дедупликация: повторный сбор не плодит дубли и не сбивает ручной статус.
• 🗂 Карточка лида: телефоны, сайты, соцсети, фото, история, папка с данными.
• 📊 Скоринг и статусы: NEW → POTENTIAL → IN_PROGRESS → PROCESSED (+ REJECT / CHAIN).
• 🖥 Портативная десктоп-версия (Electron) — Python на машине не нужен.

🚀 Быстрый старт

Портативная версия (без установки)

Готовый .exe ничего не ставит в систему и не требует Python:

electron/dist/Local Lead Studio 0.1.0.exe   ← двойной клик

Данные хранятся рядом с .exe — в папке lead_studio_data.

Из исходников (Windows)

Всё ставится локально в папку проекта (backend/venv, node_modules). В систему глобально ничего не пишется — удалите папку проекта, и следов не останется.

Шаг 1. Поставить Python и Node.js

Нужны два инструмента (ставятся один раз на машину):

Инструмент	Версия	Скачать
Python	3.10+	https://www.python.org/downloads/
Node.js	18+ (LTS)	https://nodejs.org/en/download/

• При установке Python отметьте галочку «Add python.exe to PATH». Node.js — обычный установщик .msi, ничего отмечать не надо.

Проверьте, что оба в PATH (новый терминал):

python --version
node --version

Шаг 2. Скачать проект

Скачайте ZIP с репозитория и распакуйте, либо через git:

git clone <repo-url>
cd LocalLeadStudio

Шаг 3. Запустить

Один скрипт сам создаёт venv, ставит зависимости, собирает UI (один раз) и открывает окно Electron. Запускайте из папки LocalLeadStudio.

🖥️ Windows (двойной клик по файлу или в cmd):

run.bat

Первый запуск дольше (ставятся зависимости и собирается фронт). Дальше — сразу окно.

Данные хранятся рядом — lead_studio_data/.

Сервис	Адрес
🖼 UI	http://localhost:5173
🔌 API	http://127.0.0.1:8765
📖 Docs	http://127.0.0.1:8765/docs

📖 Как пользоваться

1. Слева задайте регион, город и ниши (или ручной список запросов).
2. Проверьте лимиты: число карточек, паузу, мин. отзывов, фото.
3. Запустите сбор, следите за статусом.
4. Разберите таблицу лидов; в карточке — контакты, фото, история, папка.
5. Помечайте статусы вручную — повторный сбор их не откатит.

🗃 Структура проекта

backend/
  yamap_landing_web.py     точка входа FastAPI (app, роуты, main)
  core.py                  пути, конфиг, репозиторий, общие хелперы
  guards.py                локальная защита + лимиты Яндекса
  folders.py               папки лидов
  cities.py                справочник городов/регионов
  leads.py                 извлечение и сохранение лида
  lead_filters.py          фильтры отбора (keep_lead, is_chain, гео)
  lead_pipeline.py         оркестрация сбора, провайдеры, job
  yamap_landing_parser.py  парсер Яндекс.Карт
  lead_studio/             SQLite-репозиторий и провайдер Яндекс.Карт
frontend/                  React + Vite + Tailwind + shadcn
electron/                  десктоп-обёртка (окно над локальным сервером)

🌐 Источники и браузеры

Источник	Как работает	Требования
Яндекс.Карты	парсинг публичной страницы (не API), самолимит ~80/день + паузы	—

📦 Как собрать portable .exe (Windows)

1. В корне проекта запустите:

   build-portable.bat

2. Скрипт проверит Python 3.10+ и Node.js 18+ в PATH. Если одного из них нет или версия устарела, откроется официальная страница установки. После установки перезапустите build-portable.bat.

3. Готовый файл будет здесь: electron/dist/Local Lead Studio 0.1.0.exe.

Все зависимости проекта остаются рядом с исходниками: Python-пакеты и PyInstaller — в backend/venv, npm-пакеты — в frontend/node_modules и electron/node_modules, кэши сборки — в .cache/. В глобальные Python/npm-пакеты скрипт ничего не ставит. На ПК получателя этого portable .exe Python и Node.js не нужны.

🛠 Разработка

:: frontend
cd frontend && npx tsc -p tsconfig.app.json --noEmit && npm run lint && npm run build
:: backend
cd backend && python -m py_compile yamap_landing_web.py core.py lead_pipeline.py

🔒 Данные и приватность

• БД, выгрузки, фото и папки карточек runs/ → lead_studio_data рядом с парсером (в dev — в корне проекта, в portable — рядом с .exe). В git не коммитятся.
• Только публичные данные карточек. Чужие фото/отзывы не публикуйте без согласия.

⚠️ Ограничения

• Локальный инструмент; backend слушает только localhost.
• Портативный .exe — Windows x64; первый запуск медленнее (распаковка во временную папку).
• Подписи кода нет — SmartScreen может предупредить при первом запуске.