init: Parser v1 — Lead Generation Engine

Парсер лидов МБ РФ: Яндекс.Карты + HH.ru + обогащение DaData/ЕГРЮЛ/Rusprofile + Streamlit CRM. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-09 12:56:06 +03:00
commit f78f35fb3f
33 changed files with 9198 additions and 0 deletions
@@ -0,0 +1,773 @@
+# Parser v1 — Lead Generation Engine
+
+Парсер лидов малого бизнеса РФ с многоуровневым обогащением, скорингом и **CRM-приложением** для ручной работы с лидами.
+
+**Источники:**
+- 🗺 **Яндекс.Карты** — компании по нишам (кафе, автосервис, стоматология...). Сканирует карточку на email и доп.телефоны (в описаниях / «О компании»).
+- 💼 **HH.ru** — компании, ищущие «руки» по signal-запросам (оператор, администратор записи) = нет автоматизации.
+- 🔍 **HH employer-pages** — для лидов от HH парсит страницу работодателя → website + доп.контакты.
+- 🔎 **DDG-find-sites** — для лидов без website ищет сайт через DuckDuckGo (бесплатно, без капчи) + верифицирует по содержимому (`name fuzzy-match` + blocklist 80+ агрегаторов).
+- 🌐 **Tier 2 enrichment** — анализ сайта: CMS, чат, онлайн-запись, аналитика + email/телефоны из `<a href="mailto:...">` / `<a href="tel:...">` + **ИНН/ОГРН/КПП из footer** (152-ФЗ disclosure, пробует 7 типичных contact-страниц).
+- 🏛 **Tier 3 ЕГРЮЛ** — **DaData** (primary, 10К запросов/день бесплатно, индексирует бренды) → **Rusprofile** (fallback). Возвращает ИНН/ОГРН/КПП/директор/адрес/дата регистрации/ОКВЭД.
+- 🚫 **Blacklist крупных компаний** — автоматически отсекает банки (Газпром/Альфа/Сбер), ритейл-сети (ВкусВилл/X5/Магнит), госструктуры (Правительство Москвы/ФГАОУ) и пр. публичные компании ПАО которым outreach бесполезен.
+
+**Два режима работы:**
+- 🤖 **Парсер** — собирает лидов в `leads.db` через `launch.bat` (TUI-меню) или `python main.py …`
+- 🎯 **CRM-приложение** (Streamlit) — открывается через `launch_crm.bat`, читает/пишет ту же `leads.db`: фильтры по статусу/региону/score, форма касания (звонок/email/VK/TG → реакция), история всех касаний, заметки о лиде.
+
+**Стек:** Python 3.12 + Botasaurus + SQLite + requests + colorlog + Streamlit (для CRM) + DaData Suggestions API
+**Текущая БД:** 2874 лида (2676 HH + 198 Я.Карты), из них **143 excluded** (blacklist крупных компаний), **2731 доступных для outreach**, **1587 hot** (score≥5). У ~520 лидов есть директор/ИНН.
+
+---
+
+## ⚡ Быстрый старт
+
+**Два двойных клика:**
+- **`launch.bat`** — запускает парсер через TUI-меню (`questionary`): источники, категории, локация, опции pipeline.
+- **`launch_crm.bat`** — открывает CRM-приложение в браузере (`localhost:8501`): таблица лидов, фильтры, форма касания.
+
+```bash
+# 1. Один раз: установка
+python -m venv .venv
+.venv\Scripts\activate                 # Windows
+pip install -r requirements.txt
+playwright install chromium
+
+# 2a. Парсер через TUI-меню (рекомендуется)
+launch.bat
+# или: python launcher.py
+
+# 2b. Или напрямую через CLI
+python main.py --full --category "автосервис,салон красоты,стоматология" --limit 20
+
+# 3. Работать с собранными лидами в CRM
+launch_crm.bat
+# или: streamlit run app/app.py
+
+# 4. CSV-отчёты прогонов
+explorer exports
+```
+
+---
+
+## 📋 Содержание
+
+1. [Установка](#установка)
+2. [Smoke-тесты](#smoke-тесты)
+3. [Команды](#команды)
+   - [📖 Справочник по всем флагам](#-справочник-по-всем-флагам)
+4. [География: город / район / регион](#география)
+5. [Pipeline и его шаги](#pipeline)
+6. [Скоринг лидов](#скоринг)
+7. [Что в БД](#что-в-бд)
+8. [CRM-приложение (Streamlit)](#crm-приложение)
+9. [Структура проекта](#структура)
+10. [PyCharm флоу](#pycharm)
+11. [Troubleshooting](#troubleshooting)
+12. [Прогресс по фазам](#прогресс-по-фазам)
+
+---
+
+## Установка
+
+```bash
+# Создать venv и активировать
+python -m venv .venv
+.venv\Scripts\activate                 # Windows
+# source .venv/bin/activate            # Linux/Mac
+
+# Зависимости
+pip install -r requirements.txt
+playwright install chromium             # обязательно — это браузер для Botasaurus
+```
+
+**Python:** 3.12 (3.13 тоже работает; 3.14 — рискованно, не все wheel'ы есть).
+
+---
+
+## Smoke-тесты
+
+Перед первым запуском проверь что модули работают:
+
+```bash
+python normalization.py    # тесты телефона / домена / рейтинга
+python database.py         # тест дедупликации
+python scoring.py          # тест скоринга
+```
+
+Все 3 должны напечатать `✅ ... — пройдены`. Если упало — баг.
+
+---
+
+## Команды
+
+> 💡 Можно вообще не помнить флаги — двойной клик по **`launch.bat`** откроет TUI-меню (`launcher.py`) с навигацией стрелками + чекбоксами + 50+ категорий и 40+ локаций. Описание ниже — для запуска через PowerShell/Terminal или PyCharm Run Configuration.
+
+
+### Полный pipeline (всё одной командой)
+
+`--full` эквивалент `--source X --find-sites --enrich --enrich-egrul --rescore --export` (+ `--hh-enrich-websites` если source=hh). Делает:
+1. **Парсинг** одного источника (HH или Я.Карты)
+2. **HH employer-pages** (если HH) — заходит на страницу работодателя, тащит website + контакты
+3. **DDG find-sites** — для лидов без website ищет сайт через DuckDuckGo + верифицирует
+4. **Tier 2** — анализ сайтов (CMS, чат, запись, аналитика) + извлечение ИНН/ОГРН/КПП из footer (152-ФЗ)
+5. **Tier 3** — ЕГРЮЛ через DaData (primary) → Rusprofile (fallback). Если на сайте нашли ИНН — обогащение по ИНН (точно).
+6. **Blacklist filter** — автоматически отсекает крупные публичные компании (банки, ритейл-сети, госструктуры)
+7. **Rescore** всех лидов в БД (включая старых)
+8. **Export** CSV
+
+```bash
+# Я.Карты — нужно явно указать --source yandex (default)
+python main.py --full --category "автосервис" --limit 30
+
+# HH — компании которые ищут "руки" (нет CRM)
+python main.py --full --source hh --category "оператор колл-центра" --limit 5
+
+# По всем signal-запросам HH (~30-40 минут)
+python main.py --full --source hh
+```
+
+**Источники запускаются раздельно** — БД одна, но каждый источник имеет свои параметры,
+скорость, риски блокировок. Так удобнее контролировать прогоны.
+
+**БД общая (`leads.db`)** — после двух раздельных прогонов компании из Я.Карт и HH
+автоматически смерджатся через дедуп по ИНН/телефону/домену (после ЕГРЮЛ-обогащения).
+
+### По шагам
+
+| Команда | Что делает |
+|---|---|
+| `--source yandex --category "кафе" --limit 30` | Парсинг 1 категории на Я.Картах |
+| `--source yandex` (без `--category`) | Все 10 категорий из `config.CATEGORIES` |
+| `--source hh` | HH.ru — все signal-запросы (`оператор`, `администратор записи`, ...) |
+| `--source hh --category "оператор колл-центра"` | HH.ru — только один запрос |
+| `--hh-enrich-websites` | Для HH-лидов без сайта зайти на employer-страницу, взять website + контакты |
+| `--find-sites` | Для лидов без website искать сайт через DuckDuckGo (бесплатно) + верифицировать по INN/name |
+| `--enrich` | Tier 2 — обогатить непроверенные сайты (CMS / контакты / footer ИНН) |
+| `--enrich-egrul` | Tier 3 — обогатить через DaData (primary) → Rusprofile (fallback) |
+| `--rescore` | Пересчитать score у всех лидов |
+| `--export --min-score 5` | Только экспорт горячих лидов |
+| `--stats` | Показать статистику БД |
+| `--cleanup-directors` | Очистить лиды где director_name = "Генеральный директор" / "Председатель" / etc. (запустится повторное обогащение) |
+
+### 📖 Справочник по всем флагам
+
+Каждый флаг можно использовать отдельно или **комбинировать в любом порядке**.
+Pipeline запускается последовательно: parse → enrich → enrich-egrul → rescore → export.
+
+#### 🎯 Pipeline-флаги (запускают шаги обработки)
+
+| Флаг | Default | Что делает | Зависит от |
+|---|---|---|---|
+| `--source {yandex,hh}` | — | Какой источник парсить. Без него парсинг не идёт. *(2GIS/VK/WB — отключены, см. DECISIONS D13/D17)* | — |
+| `--hh-enrich-websites` | false | Для HH-лидов без сайта: зайти на employer-страницу, забрать `website` + доп.контакты | Лиды source=hh без website |
+| `--find-sites` | false | Для лидов без website: искать сайт через DuckDuckGo HTML search + верифицировать (INN на странице ИЛИ fuzzy-match названия + blocklist 80+ доменов агрегаторов) | Лиды без website |
+| `--find-sites-source {yandex,hh,all}` | `all` | Ограничить `--find-sites` лидами из конкретного источника | используется с `--find-sites` |
+| `--find-sites-limit N` | — | Ограничить `--find-sites` первыми N лидами (для теста) | используется с `--find-sites` |
+| `--enrich` | false | Tier 2: анализ сайта (CMS, чат, запись, аналитика) **+ сбор email/доп.телефонов + ИНН/ОГРН/КПП из footer (152-ФЗ)** для лидов где `website` есть, но `site_checked_at` ещё пуст. Если на сайте нашли ИНН — авто-запуск ЕГРЮЛ по ИНН. | Лиды с `website` в БД |
+| `--enrich-egrul` | false | Tier 3: ЕГРЮЛ через **DaData** (primary, 10K/день бесплатно) → **Rusprofile** (fallback). Для лидов где `egrul_checked_at` пуст | Лиды с `name` в БД |
+| `--rescore` | false | Пересчитать score у **всех** лидов в БД (нужно после изменения `config.SCORE_WEIGHTS`) | — |
+| `--export` | false | CSV каждого прогона сессии в `exports/YYYY-MM/leads_<src>_<query>_<city>_<ts>.csv` с шапкой-метаданными. Если парсинга в сессии не было — плоский CSV по `min_score`. | — |
+| `--export-master` | false | Snapshot всей БД в `exports/_master/all_leads.csv` (перезапись). Можно вызвать в любой момент. | — |
+| `--export-run N` | — | Пересоздать CSV конкретного прогона по его ID из `sources_log` (если файл удалили). | — |
+| `--full` | false | **Shortcut** — раскрывается в `--source X --find-sites --enrich --enrich-egrul --rescore --export` (+ `--hh-enrich-websites` если `--source hh`). Default source = `yandex`. | — |
+| `--stats` | false | Показать сводку БД и **выйти** (другие флаги игнорируются) | — |
+| `--cleanup-directors` | false | Утилита: очистить кривые ФИО директоров ("Генеральный директор" и т.п.) и сбросить `egrul_checked_at` чтобы `--enrich-egrul` повторно их прогонял | — |
+| `--rescan-sites` | false | Одноразовая утилита: сбросить `site_checked_at` у всех лидов → следующий `--enrich` пройдёт по сайтам заново. Нужно после расширения сбора контактов / обновления `analyze_website`. | — |
+
+#### 🔍 Параметры парсинга (модификаторы для `--source`)
+
+| Флаг | Default | Что делает | Где работает |
+|---|---|---|---|
+| `--category "X"` | — | Конкретный поисковый запрос. Можно несколько через запятую: `"автосервис,салон красоты,стоматология"`. Если не указано — берётся профильный список (`CATEGORIES` для Я.Карт, `HH_SIGNAL_QUERIES` для HH) | yandex, hh |
+| `--city "X"` | `"Москва"` | Город из `config.CITIES` (Москва / Москва и МО / СПб). Если указан незнакомый — fallback на "Москва и МО" + город как район | yandex, hh |
+| `--district "X"` | — | Район Москвы или другой топоним для уточнения. Свободная строка (Митино, Бутово, Зеленоград). Добавляется к поисковому запросу + сохраняется в БД отдельной колонкой | yandex |
+| `--limit N` | 100 | Для Я.Карт — **максимум карточек на категорию**. Для HH — **максимум страниц** (1 страница ≈ 50 вакансий). Не действует на enrichment (он всегда обрабатывает всех непроверенных) | yandex, hh |
+
+#### 📤 Параметры экспорта
+
+| Флаг | Default | Что делает |
+|---|---|---|
+| `--min-score N` | 0 | В CSV попадут только лиды с `score >= N`. Например `--min-score 5` оставит только hot leads |
+
+---
+
+### 💡 Какие флаги можно комбинировать
+
+#### ✅ Типичные комбинации
+
+```bash
+# Только парсинг, без обогащения
+python main.py --source yandex --category "кафе" --limit 20
+
+# Полная цепочка по Я.Картам — парсинг + find-sites + Tier2 + DaData + score + CSV
+python main.py --full --source yandex --category "кафе" --limit 20
+
+# Полная цепочка по HH (включая employer-pages)
+python main.py --full --source hh --category "оператор колл-центра" --limit 5
+
+# Обогатить и пересчитать без нового парсинга (например после правки скоринга)
+python main.py --find-sites --enrich --enrich-egrul --rescore --export
+
+# Только найти сайты для HH-лидов (лимит 50 для теста)
+python main.py --find-sites --find-sites-source hh --find-sites-limit 50
+
+# Только пересчитать score (быстро — секунды)
+python main.py --rescore --export
+
+# Утилита очистки + повторный enrichment + rescore + CSV
+python main.py --cleanup-directors --enrich-egrul --rescore --export
+
+# Только посмотреть текущее состояние
+python main.py --stats
+
+# Перепрогон enricher на ВСЕХ лидах с website (после расширения сбора контактов)
+python main.py --rescan-sites --enrich --rescore --export-master
+
+# Master-файл всех лидов в один CSV
+python main.py --export-master
+
+# Восстановить удалённый CSV прогона #5
+python main.py --export-run 5
+```
+
+#### ❌ Бессмысленные комбинации
+
+- `--stats` + что угодно — `--stats` всегда выходит сразу
+- `--full` без `--source` (точнее, без явного source — возьмёт default `yandex`)
+- `--enrich` без лидов с `website` в БД — нечего обогащать
+- `--enrich-egrul` без лидов в БД — то же самое
+- `--district "X"` для `--source hh` — игнорируется (HH парсит по area_id)
+
+---
+
+### HH.ru — отдельный workflow
+
+```bash
+# Полный цикл одной командой (Парсинг → Tier 2 → ЕГРЮЛ → Rescore → CSV)
+python main.py --full --source hh
+
+# Только парсинг по одному signal-запросу (для теста)
+python main.py --source hh --category "оператор колл-центра" --limit 2
+
+# Без --category — пройдёт по всем 13 signal-запросам из config.HH_SIGNAL_QUERIES
+python main.py --source hh
+```
+
+**Принцип:** если компания ищет "оператора ПК" / "администратора записи" / "менеджера без CRM" — у них нет автоматизации. Это **прямой сигнал боли** = `+3 hh_signal` в скоринг. Дедупликация по ИНН автоматически свяжет их с лидами из Я.Карт если совпадут (обычно не пересекаются — разные срезы рынка).
+
+**Важно:** HH парсер работает через **Botasaurus браузер** (не api.hh.ru — он 403'ит даже с Chrome TLS-fingerprint). Открывает страницы поиска `hh.ru/search/vacancy` как реальный пользователь. Региональный модал "Вы из Москвы?" закрывается автоматически.
+
+**Что HH даёт vs что нет:**
+| Поле | HH | Что компенсирует |
+|---|---|---|
+| name | ✅ | — |
+| employer_id, source_url | ✅ | — |
+| phone | ❌ | HH публично не показывает |
+| website | ❌ | — |
+| ИНН + директор + дата регистрации | через `--enrich-egrul` | Rusprofile по name (~65% покрытие) |
+
+### Геолокация — `--city` и `--district`
+
+См. подробно в [разделе ниже](#география). Кратко:
+
+```bash
+# Известный город (есть в config.CITIES)
+python main.py --full --city "Москва" --category "стоматология" --limit 15
+
+# Любой город / район — через district + общая зона
+python main.py --full --city "Москва и МО" --district "Жуковский" --category "автосервис"
+python main.py --full --city "Москва" --district "Митино" --category "салон красоты"
+```
+
+### Категории — несколько через запятую
+
+```bash
+python main.py --full --category "автосервис,салон красоты,стоматология" --limit 20
+```
+
+Парсятся последовательно. Между категориями — пауза `random(30, 60)` сек (anti-bot).
+
+---
+
+## География
+
+### 3 уровня геолокации
+
+| Уровень | CLI | Поле в БД | Пример |
+|---|---|---|---|
+| **Регион** (агрегатор) | автоматом из конфига | `region` | "Москва", "Московская область" |
+| **Город** | `--city "Москва"` | `city` | "Москва", "Мытищи" |
+| **Район** | `--district "Митино"` | `district` | "Митино", "Жуковский" |
+
+### Что в `config.CITIES`
+
+```python
+CITIES = {
+    "Москва":          {"yandex_id": 213, ...},   # ✓ проверено
+    "Москва и МО":     {"yandex_id": 1,   ...},   # ✓ проверено
+    "Санкт-Петербург": {"yandex_id": 2,   ...},   # ✓ проверено
+}
+```
+
+### Fallback для незнакомого города
+
+Если указать `--city` которого **нет** в `config.CITIES` (и при этом `--district` пуст), парсер автоматически:
+1. Использует `Москва и МО` (geo_id 1) как базу
+2. Город уходит в `--district`
+3. В лог пишет ⚠️ предупреждение
+
+```bash
+# Указано "Жуковский" — нет в config → fallback на "Москва и МО" + район "Жуковский"
+python main.py --full --city "Жуковский" --category "автосервис"
+```
+
+⚠️ Если указать **и** неизвестный city, **и** district одновременно — будет ошибка с подсказкой.
+
+### Как добавить точный город (5 минут)
+
+1. Открыть https://yandex.ru/maps/ → найти город в поиске
+2. **Кликнуть** на первый результат ("Мытищи, городской округ")
+3. URL станет `https://yandex.ru/maps/10743/mytishchi/?...`
+4. Вставить в `config.CITIES`:
+   ```python
+   "Мытищи": {"yandex_id": 10743, "yandex_slug": "mytishchi",
+              "vk_id": 1, "region": "Московская область"},
+   ```
+5. Готово: `python main.py --full --city "Мытищи" --category "автосервис"`
+
+---
+
+## Pipeline
+
+```
+┌─────────┐  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  ┌──────┐
+│1. Parse │→ │2. HH-emp│→ │3. Find-  │→ │4. Tier2 │→ │5. Tier 3 │→ │6. Black- │→ │7. Re-  │→ │8.CSV │
+│ Я.Карты │  │   pages │  │  Sites   │  │ website │  │ DaData → │  │ list     │  │ score  │  │      │
+│ + HH    │  │ employer│  │ DuckDuck │  │ analyzer│  │ Rusprof  │  │  filter  │  │ all    │  │      │
+│ + body  │  │website+ │  │ + verify │  │ + footer│  │ fallback │  │ 143 leads│  │ leads  │  │      │
+│ emails  │  │contacts │  │ by INN/  │  │ INN/OGRN│  │ + INN-by-│  │ excluded │  │        │  │      │
+│         │  │         │  │ name     │  │   /KPP  │  │ site     │  │          │  │        │  │      │
+└─────────┘  └─────────┘  └──────────┘  └─────────┘  └──────────┘  └──────────┘  └────────┘  └──────┘
+ --source     --hh-enrich  --find-     --enrich      --enrich-       (auto в     --rescore   --export
+              -websites    sites                     egrul           upsert)
+```
+
+Каждый шаг можно запустить **независимо** или **в комбинации**. Флаг `--full` запускает всю цепочку.
+
+**Сбор контактов в pipeline (важно):**
+- **Шаг 1** парсит карточки Я.Карт + HH-вакансии. Я.Карты помимо `.orgpage-phones-view__phone-number` сканирует **весь видимый текст карточки** через `document.body.innerText` → email/доп.телефоны из описания / «О компании». Технические домены Яндекса фильтруются.
+- **Шаг 2 (HH employer-pages)** для HH-лидов без сайта — заходит на страницу работодателя на hh.ru, тащит website + социальные сети + телефоны.
+- **Шаг 3 (Find-Sites)** для всех лидов без `website` — ищет сайт через DuckDuckGo HTML search. Верифицирует двумя способами: (а) ИНН лида должен встречаться на странице, или (б) название компании fuzzy-match (с очисткой от ОПФ-префиксов). Blocklist 80+ доменов агрегаторов (`hh.ru`, `2gis.ru`, `yell.ru`, `rusprofile.ru` и т.п.).
+- **Шаг 4 (Tier 2)** `analyze_website` запрашивает сайт компании: CMS-сигнатуры (Tilda/Wix/1С-Bitrix/InSales), online-чат, online-запись, аналитика. Извлекает email/телефоны из `mailto:`/`tel:`. Сканирует footer + пробует 7 типичных contact-страниц (`/contacts/`, `/kontakty/`, `/o-kompanii/`, `/rekvizity/`, ...) на наличие **ИНН/ОГРН/КПП** (152-ФЗ disclosure). Если ИНН найден — авто-запуск `enrich_egrul_by_inn(inn)` (точное обогащение по ИНН без fuzzy-поиска).
+- **Шаг 5 (Tier 3)** ЕГРЮЛ-обогащение: сначала **DaData Suggestions API** (10K запросов/день бесплатно, индексирует бренды → находит «ВкусВилл» / «Кофемания» / «The Бык»), при неудаче — **Rusprofile** fallback. С учётом kladr_id для приоритета по городу (Москва/СПб). Возвращает: ИНН, ОГРН, КПП, директор (ФИО), адрес, дата регистрации, ОКВЭД.
+- **Шаг 6 (Blacklist)** при `upsert_lead` проверяется через `blacklist.is_blacklisted(name)` — три стратегии: точное имя (~140 компаний), keyword-fragments (~30 паттернов), prefix-matching. Лид помечается `outreach_status='excluded'` и пропускается фильтрами CRM.
+- Если расширил `analyze_website` (добавил новые сигнатуры/детекторы) — прогони `--rescan-sites --enrich` чтобы обогатить уже собранных лидов заново.
+
+---
+
+## Скоринг
+
+Формула **v5** — **«решаемая нами боль» × ICP**, шкала **0-10** (логика в `scoring.py`, веса в `config.py`).
+Полное обоснование и история — **D17** в [`../DECISIONS.md`](../DECISIONS.md).
+
+**Семантика:** score отвечает на ОДИН вопрос — есть ли у компании проблемы, которые закрывают НАШИ продукты, и насколько остро. Не «качество лида», не «дозвонибельность».
+
+```
+score = pain(решаемая боль) × icp_fit(наш ли это размер)
+```
+
+### Детекторы боли → продукт (`config.SCORE_WEIGHTS`)
+
+| Тема | Сигнал | Вес | Продукт | Применяется к |
+|---|---|---|---|---|
+| Запись/входящие | нет онлайн-записи | 2.0 | **P4** | только услуги с записью (`APPT_CATEGORIES`) |
+| | нет онлайн-чата | 1.0 | **P4** | всем |
+| Репутация | рейтинг <3.5 / <4.0 / <4.5 | 2.0 / 1.5 / 1.0 | **P3** | всем (4.5+ = не боль) |
+| | мало отзывов <10 / <30 | 1.0 / 0.5 | **P3** | всем |
+| Веб | нет сайта / сайт мёртв | 1.5 / 2.5 | **P10** | всем |
+| | сайт на конструкторе (вкл. авто-визитки Я.Бизнес) | 0.5 | **P10** | всем (премиум топит ICP) |
+| Маркетинг | нет соцсетей (VK/Telegram) | 1.0 | **P12** | только B2C (`SOCIAL_SALES_CATEGORIES`) |
+| | нет веб-аналитики | 0.5 | **P12** | всем |
+| Инфра | почта на бесплатном домене | 0.5 | **P2** | всем |
+
+Внутри темы — насыщение `max + 0.4·остальные` (коррелированные сигналы не стакаются линейно). Сумма тем → `raw_pain`, нормировка `/PAIN_NORM·10`, cap 10. `pain_products` (JSON) = «с чем заходить» для CRM.
+
+### ICP-гейт — прогрессивный штраф за «зрелость» (множитель 0..1)
+
+ЦА = малый/средний бизнес, которому нужна автоматизация. Чем больше отзывов **и** выше рейтинг — тем сильнее снижаем балл (процветающим/раскрученным труднее продать):
+
+```
+icp = 1 − 0.85 · rf · (0.65 + 0.35·gf)
+  rf = min(1, отзывы / 6000)         # линейно по объёму (усилен 2026-06-05)
+  gf = clamp((avg − 4.0)/(5.0 − 4.0))  # по рейтингу
+```
+
+Отзывы штрафуют всегда (база 0.5), высокий рейтинг усиливает до полного. Мало отзывов → ≈1 (новый/борющийся бизнес сохраняет балл). На Я.Картах рейтинги зажаты 4.5-5.0 → главный рычаг это объём отзывов. Параметры — `ICP_*` в `config.py`.
+
+«Уже автоматизирован» отдельно не режем — у такого лида просто нет болевых дыр (severity→0).
+
+### ⚠️ Категорийная релевантность (читай при добавлении категории)
+
+Часть болей применима не ко всем типам бизнеса. Подробная инструкция — в блоке `config.py`:
+- **booking (P4)** — только `APPT_CATEGORIES` (салон, клиника, кафе, автосервис…)
+- **social (P12)** — только `SOCIAL_SALES_CATEGORIES` (бьюти, HoReCa, розница…)
+- Новая/неизвестная категория по умолчанию НЕ получает booking/social, пока не впишешь ключевое слово в нужный список (консервативно — чтобы не завышать ложно).
+- Instagram в РФ забанен → в соцсетях учитываются только VK/Telegram.
+
+### Полнота диагностики
+
+`diagnostic_coverage` (0..1) — доля проверенных тем. «Не проверяли» ≠ «нет боли»: при coverage < `MIN_COVERAGE` (0.5) лид помечается «нужно обогащение», а не ранжируется фальшиво.
+
+### Бэнды и пороги
+
+- 🔥 **hot** — score ≥ `BAND_HOT` (6) · 🟡 **warm** — 4-5 · ⚪ **cold** — ≤3
+- `HOT_LEAD_THRESHOLD = BAND_HOT` (совместимость с CRM / экспортом)
+- `PAIN_NORM = 5.0` — нормировочный делитель · `SCORE_MAX = 10` — hard cap
+
+### Аудит скоринга
+
+`python audit_scores.py` — независимая проверка всей БД (пересчёт каждого лида + санитарные правила: боль vs данные, устаревший score, целостность). Код возврата 1 при HARD-аномалиях — можно вешать на хук/CI.
+
+---
+
+## Что в БД
+
+Таблица `leads` — все поля:
+
+```
+Идентичность:    id, name, inn, ogrn, director_name
+Контакты:        phones (доверенные — Я.Карты), phones_extra (с сайта, к проверке),
+                 emails (JSON), phone_primary, email_primary
+Онлайн:          website, vk_url, telegram_url, instagram_url, youtube_url
+Гео:             address, city, region, district
+Бизнес:          category
+Сигналы:         reviews_count, reviews_avg, has_website, has_vk, has_telegram
+Скоринг:         score, score_breakdown (JSON)
+Email валидация: email_valid, email_checked_at
+Tier 2:          site_alive, site_status_code, cms_type,
+                 has_live_chat, has_online_booking, has_analytics,
+                 email_domain_type, site_checked_at
+Tier 3:          registration_date, egrul_checked_at, egrul_status
+Outreach (auto): outreach_status, outreach_channel, outreach_sent_at, outreach_replied_at
+CRM (ручной):    comments, last_action, last_reaction, last_touched_at
+Системные:       source, source_id, source_url, parsed_at, updated_at,
+                 phone_dedup_key, domain_dedup_key
+```
+
+Дополнительные таблицы:
+- `sources_log` — история прогонов (`source`, `query`, `city`, `started_at`, `finished_at`, счётчики, статус)
+- `outreach_events` — история всех касаний (звонок/email/VK/TG → реакция → комментарий). Пишется из CRM-приложения и в будущем — из Phase 3 auto-pipeline.
+- `lead_in_run` — junction-таблица «прогон ↔ лид» с пометкой `inserted`/`merged`. Нужна для `--export-run N` — пересоздания CSV конкретного прогона.
+
+**Статусы лида (`outreach_status`):**
+- `inbox` / `new` — не разобран (default для свежих лидов)
+- `triaged` — посмотрел, оставил в работе
+- `in_work` — идёт работа (звоним, переписываемся)
+- `done` — закрыт (стал клиентом или отказался окончательно)
+- `skip` — пропустить (не наша ЦА)
+- `queued` / `sent` / `replied` / `converted` — для будущего auto-pipeline (Phase 3)
+
+### Дедупликация
+
+`upsert_lead()` ищет дубль в порядке: **ИНН → телефон (10 цифр) → домен**. Найденный — мержит (объединяет phones/emails, заполняет пустые поля).
+
+UNIQUE constraints на `inn` и `phone_dedup_key`.
+
+---
+
+## CRM-приложение
+
+Streamlit-приложение для работы со звонящего/писавшего человека: фильтр лидов, форма касания, история всех взаимодействий, заметки.
+
+### Запуск
+
+```powershell
+# Двойной клик по launch_crm.bat либо:
+streamlit run app/app.py
+```
+
+При первом запуске `launch_crm.bat` ставит `streamlit>=1.35.0` через pip (~30 сек) и создаёт пустой `~/.streamlit/credentials.toml` чтобы Streamlit не задавал вопрос про email.
+
+Откроется браузер на `http://localhost:8501`. Работает на той же `leads.db` что и парсер — изменения видны сразу с обеих сторон.
+
+### Интерфейс
+
+**Левая панель — фильтры:**
+- Быстрый фильтр: 📥 Inbox / 🔥 Hot (≥6) / ⚙️ В работе / ✅ Готовые / 🚫 Пропущенные / 📋 Все
+- Источник (multiselect)
+- Регион (multiselect)
+- Район содержит (текстовый поиск)
+- Категория (multiselect)
+- Статус (multiselect)
+- Диапазон score (slider 0–10)
+- Поиск по имени
+
+**Сверху — 5 метрик:** Всего в БД, Inbox, В работе, Готовых, Под текущий фильтр.
+
+**Таблица лидов** — клик по строке открывает детальную карточку под таблицей.
+
+**Карточка лида:**
+- 3 колонки: контакты (телефон/email/сайт/VK/TG/Instagram), бизнес (категория/отзывы/директор/ИНН), статус (score / последнее касание).
+- Форма **«➕ Записать касание»**: действие (звонок/email/VK/TG/WhatsApp/SMS) + реакция (не ответили / отказ / согласились / перешли в TG / перезвонить / не наша ЦА / спам) + комментарий + новый статус лида.
+- **«📝 Заметки»** — свободные заметки о лиде (отдельно от истории касаний).
+- **«📜 История касаний»** — все события по этому лиду из таблицы `outreach_events`.
+
+### Автомиграция БД
+
+При запуске `app.py` вызывается `database.init_db(...)` — это автоматически догоняет схему: добавляет 4 CRM-колонки, таблицы `outreach_events` и `lead_in_run` если их ещё нет. То есть приложение работает на старой БД без подготовки.
+
+### Файлы
+
+- `app/app.py` — Streamlit UI (~380 строк)
+- `app/db_layer.py` — слой работы с БД (~270 строк): фильтры, детали, история, запись касаний, метрики
+- `launch_crm.bat` — Windows-launcher с автоустановкой streamlit и автокредами
+
+---
+
+## Структура
+
+```
+parser_v1/
+├── README.md                      ← этот файл
+├── launch.bat                     ← 🚀 запуск парсера через TUI-меню (двойной клик)
+├── launch_crm.bat                 ← 🎯 запуск CRM-приложения в браузере (двойной клик)
+├── launcher.py                    ← TUI-меню на questionary (запуск парсера)
+├── requirements.txt
+├── .gitignore
+│
+├── config.py                      # CITIES, CATEGORIES, веса скоринга, задержки
+├── database.py                    # SQLite: схема, миграции, upsert, start/finish_source_run, update_lead_contacts
+├── normalization.py               # Телефоны (E.164), домены, ratings, extract_emails/phones_from_text
+├── scoring.py                     # Формула скоринга v4 (0-10, hard cap)
+├── logger_setup.py                # Цветной вывод (colorlog)
+├── main.py                        # CLI — точка входа парсера
+├── leads.db                       # ⚠️ создаётся при первом запуске
+│
+├── parsers/
+│   ├── base.py                    # BaseParser: retry, sleep, captcha-counter
+│   ├── yandex_maps.py             # Я.Карты (Botasaurus + JS-скролл + body-text email/phones scan)
+│   └── hh.py                      # HH.ru — signal-запросы через Botasaurus → employers как лиды
+│
+├── enricher/
+│   ├── website_analyzer.py        # Tier 2: CMS, чат, запись, аналитика + email/phones + ИНН/ОГРН/КПП из footer (152-ФЗ, 7 contact-страниц)
+│   ├── contacts_finder.py         # 🔎 Поиск сайта через DuckDuckGo HTML + верификация (INN на странице или fuzzy-match имени + blocklist 80+ агрегаторов)
+│   ├── dadata_enricher.py         # 🏛 ЕГРЮЛ через DaData Suggestions API (primary, 10K/день free, kladr_id для Москва/СПб приоритета)
+│   ├── egrul_enricher.py          # 🏛 ЕГРЮЛ через Rusprofile (fallback) + enrich_egrul_by_inn (точное обогащение)
+│   └── blacklist.py               # 🚫 Чёрный список крупных компаний — 143 лида исключено (банки/ритейл/гос)
+│
+├── export/
+│   └── csv_export.py              # CSV: export_run (per-прогон), export_master (snapshot всей БД), export_to_csv (плоский по min_score)
+│
+├── app/                           ← 🎯 CRM-приложение (Streamlit)
+│   ├── app.py                     #    UI: фильтры + таблица + карточка лида + форма касания
+│   └── db_layer.py                #    Слой работы с БД (фильтры, история, запись касаний)
+│
+├── exports/                       # ⚠️ создаётся при первом экспорте
+│   ├── 2026-05/                   #    Файлы прогонов сгруппированы по месяцу
+│   │   └── leads_<src>_<query>_<city>_<timestamp>.csv
+│   └── _master/
+│       └── all_leads.csv          #    Snapshot всей БД (--export-master, перезапись)
+│
+└── _archive/
+    └── phase0/                    # тесты Phase 0 (Botasaurus discovery)
+        ├── test_yandex.py
+        ├── test_yandex_v2.py
+        └── test_yandex_v3.py
+```
+
+---
+
+## PyCharm
+
+### Run Configuration
+
+1. **Run → Edit Configurations → main**
+2. **Script parameters:** например `--full --category "кафе" --limit 15`
+3. **Working directory:** `parser_v1` (полный путь). **Важно** — иначе `leads.db` создастся не там
+4. **Apply → Run**
+
+### Terminal
+
+`Alt+F12` (или View → Tool Windows → Terminal). venv активируется автоматически. Удобно для произвольных команд:
+
+```bash
+python main.py --full --city "Москва" --district "Митино" --category "автосервис" --limit 10
+```
+
+---
+
+## Troubleshooting
+
+### Скролл подгружает мало карточек
+
+**Симптом:** в логе видно `Скролл #1: карточек 5 (+0)` подряд → стоп через 3 итерации.
+
+**Причина:** Яндекс кеширует страницу при `reuse_driver=True` или замедляется.
+
+**Что делать:**
+- Подожди 30 сек, попробуй заново — обычно помогает
+- Закрой все окна Chrome, перезапусти
+
+### `404` на URL вида `/maps/{geo_id}/{slug}/`
+
+**Причина:** неправильный `yandex_id` или `yandex_slug` в `config.CITIES`.
+
+**Что делать:** удали запись для этого города из `config.CITIES` — fallback автоматически переключит на "Москва и МО" + район. Или добавь точные значения через [инструкцию выше](#как-добавить-точный-город-5-минут).
+
+### Captcha от Яндекса
+
+**Симптом:** `⚠️  CAPTCHA. Останавливаемся.` или `⚠️  Бот-детектор: cloudflare`.
+
+**Что делать:**
+- Подожди 1-2 часа (Яндекс снимает блок сам)
+- Уменьши `--limit` (например 10 вместо 50)
+- Увеличь задержки в `config.MIN_DELAY` / `config.MAX_DELAY`
+- Если повторяется — переключиться на VPS или использовать Tor
+
+### DaData/Rusprofile не находит компанию (`не найдено в ЕГРЮЛ`)
+
+Это **нормально для ~70%** компаний (текущий success rate ~29.6%). Причины:
+- Юр.название отличается от названия в Я.Картах / HH (например, бренд «Кофемания» = ООО «КАФЕ К» — DaData находит, Rusprofile нет)
+- Кавычки или специальные символы (буква "ъ" в "Кафе Пушкинъ" мешает)
+- Это ИП без публичного бренда
+
+**Что помогает:**
+- На сайте может быть ИНН в footer — `analyze_website` его извлечёт автоматически (152-ФЗ), и тогда обогащение идёт по ИНН (точно).
+- Запустить `--find-sites` чтобы сначала найти сайты, потом `--enrich` (поднимет много ИНН с footer'ов).
+
+### DaData 401/403
+
+**Симптом:** `DaData error: 401 Unauthorized`.
+
+**Причина:** не задан `DADATA_API_KEY` / `DADATA_SECRET_KEY` в `.env`.
+
+**Решение:** скопировать `.env.example` → `.env`, вставить ключи с https://dadata.ru/profile/#info. Файл `.env` — в `.gitignore`, в git не попадёт.
+
+### `IntegrityError: UNIQUE constraint failed: leads.inn`
+
+**Симптом:** при ЕГРЮЛ-обогащении одного из лидов.
+
+**Причина:** этот ИНН уже в БД у другого лида (одна сеть с разными филиалами).
+
+**Что делает парсер:** ловит исключение → пишет остальные поля **без** ИНН → помечает в логе `(DUP по ИНН)`. Прогон не падает.
+
+### `Connection to remote host was lost. - goodbye`
+
+**Не ошибка** — это сообщение когда Botasaurus закрывает CDP-соединение с Chrome в конце прогона.
+
+### "Должность" вместо ФИО директора
+
+**Симптом:** в БД `director_name = "Генеральный директор"` или похожее.
+
+**Причина:** старые записи, обогащённые до фикса валидатора ФИО.
+
+**Решение:** запустить
+```bash
+python main.py --cleanup-directors --enrich-egrul --rescore --export
+```
+
+Это очистит мусорные ФИО + повторно прогонит ЕГРЮЛ для очищенных + пересчитает.
+
+### HH `403 Forbidden` для api.hh.ru
+
+**Симптом:** в логе `HH 403 даже с TLS-fingerprint Chrome`.
+
+**Причина:** Cloudflare защищает api.hh.ru от bulk-запросов. Не помогают ни `requests`, ни `botasaurus_requests` с Chrome TLS.
+
+**Решение:** парсер уже использует **Botasaurus браузер** (через сайт `hh.ru/search/vacancy`). См. D10 в `../DECISIONS.md`. Если ошибка осталась после этого — закрой Chrome и перезапусти.
+
+### HH модал "Вы из Москвы?"
+
+**Симптом:** окно Chrome зависло на регионального модале.
+
+**Что делает парсер:** автоматически закрывает через `_dismiss_hh_modals()` (JS клик на "Да, верно"). После первого закрытия cookie сохраняется в `user_data/` — модал больше не появляется.
+
+**Если всё равно показывается:** закрой руками в окне Chrome — парсер продолжит.
+
+### HH парсинг карточек "зависает" на каждой странице
+
+**Симптом:** `Sleeping for 3 seconds...` потом тишина 1-2 минуты, потом результат.
+
+**Причина:** Botasaurus `select_all` без `wait=None` ждёт 5 сек на каждом элементе (50 карточек × 3 поля = 12 минут зависа).
+
+**Что делает парсер:** в `parsers/hh.py` все `select` внутри циклов карточек идут с `wait=None`. На странице 5-10 секунд вместо 12 минут.
+
+---
+
+## Прогресс по фазам
+
+### Phase 1 — MVP ✅ DONE (2026-05-03)
+- [x] Скелет (config, normalization, database, base, scoring)
+- [x] Yandex.Maps парсер (Botasaurus + JS-скролл)
+- [x] CSV экспорт (utf-8-sig для Excel)
+- [x] CLI (main.py)
+- [x] Tier 2 enrichment (website analyzer — CMS / чат / запись / аналитика)
+- [x] Tier 3 enrichment (ЕГРЮЛ / Rusprofile + валидатор ФИО)
+- [x] Pipeline `--full`
+- [x] Геолокация (`--city` + `--district` + fallback на "Москва и МО")
+- [x] Цветные логи (colorlog)
+- [x] **DoD: 100+ уникальных лидов в CSV** ✅ (116 лидов)
+
+### Phase 2 — Scale 🟢 ACTIVE
+- [x] **HH.ru парсер через Botasaurus** ✅ DONE 2026-05-04 — signal-запросы → employers как лиды
+- [x] **CRM-блок** ✅ DONE 2026-05-17 — БД-поля статусов/действий/реакций, таблица `outreach_events`, junction `lead_in_run`, Streamlit-приложение (`app/`), `launch_crm.bat`. Подробнее — D11 в `../DECISIONS.md`.
+- [x] **Расширенный сбор контактов** ✅ DONE 2026-05-17 — Я.Карты сканируют тело карточки на email/доп.телефоны, website-analyzer сохраняет найденные email/телефоны в лида через `update_lead_contacts`. Флаг `--rescan-sites` для перепрогона старых лидов. Подробнее — D12.
+- [x] **CSV экспорт двух уровней** ✅ DONE 2026-05-17 — `export_run()` (per-прогон с шапкой в `exports/YYYY-MM/`) + `export_master()` (snapshot всей БД).
+- [x] **DDG Find-Sites** ✅ DONE 2026-05-20 — `contacts_finder.py`: поиск сайта через DuckDuckGo HTML + верификация (INN/fuzzy-name + blocklist 80+ агрегаторов). Подробнее — D16.
+- [x] **DaData primary + Rusprofile fallback** ✅ DONE 2026-05-20 — `dadata_enricher.py`: индексирует бренды (находит «ВкусВилл»/«Кофемания»), kladr_id для приоритета по городу. Success rate вырос с ~10% до ~29.6%. Подробнее — D14.
+- [x] **INN из footer сайта (152-ФЗ)** ✅ DONE 2026-05-20 — `analyze_website` пробует 7 contact-страниц, тащит ИНН/ОГРН/КПП → авто-`enrich_egrul_by_inn` (точно). Подробнее — D16.
+- [x] **Blacklist крупных компаний** ✅ DONE 2026-05-20 — `blacklist.py`: 143 лида с `outreach_status='excluded'`. Три стратегии: точные имена / keyword-fragments / prefix. Подробнее — D15.
+- [x] **WB парсер удалён** ✅ DONE 2026-05-20 — селлеры маркетплейса не наша ЦА. Подробнее — D17.
+- [ ] **🔔 Скоринг: SPA-слепота** — `website_analyzer` (requests) не исполняет JS → у JS-SPA сайтов (React/Vue/Next, напр. `niqa.ru` = 759 байт каркас) видит пустышку → ложные «всё отсутствует» → завышенный балл. Фикс: тонкий каркас → сигналы `unknown`, не `0` (+ опц. вес авто-визитки 0.5→1.5). Кейс: Niqa должен быть < Кафе Гурмэ. Решения ①②③ — см. DECISIONS/память.
+- [ ] **🔔 Финансы (оборот + численность)** — обвяз готов (колонки `employee_count`/`revenue`, шаг `--enrich-finance`, CRM-вывод), но бесплатный DaData финансы НЕ отдаёт (проверено: всё null). Нужен источник: Rusprofile-добор (проверить первым) / ФНС открытые данные bulk / платный DaData. `bo.nalog.ru` = JS-SPA с токеном (простой REST не идёт). При рабочем источнике — сбросить `finance_checked_at`.
+- [ ] **Свежие ИП** — Rusprofile «Новые компании» как самостоятельный источник лидов
+- [ ] 2ГИС парсер — в доработке (постпонировано на потом)
+- [ ] VK парсер — в доработке (постпонировано на потом)
+- [ ] Avito парсер (anti-bot самый агрессивный)
+- [ ] Telegram парсер (TGStat API)
+- [ ] SMTP-валидация email
+- [ ] LLM Pain Detection (gpt-4o-mini анализ отзывов Я.Карт)
+- [ ] Migration SQLite → Supabase
+
+### Phase 3 — Outreach ⬜ pending
+- [x] Ручной CRM-режим через Streamlit-приложение ✅ DONE в Phase 2
+- [ ] n8n pipeline для авто-рассылок
+- [ ] Telegram bot для управления
+
+### Phase 4 — Monitor ⬜ pending
+- [ ] Cron еженедельного парсинга
+- [ ] Дельта-синхронизация (только новые)
+- [ ] Telegram-отчёты Теме
+
+---
+
+## Anti-bot настройки
+
+- Задержки между запросами: `random.uniform(MIN_DELAY, MAX_DELAY)` — по умолчанию 2-7 сек
+- Между категориями: `random.uniform(CATEGORY_PAUSE_MIN, CATEGORY_PAUSE_MAX)` — по умолчанию 30-60 сек
+- Botasaurus имитирует браузер на уровне fingerprint
+- При срабатывании captcha N раз — стоп с алертом (`config.MAX_BLOCKED_TRIES = 3`)
+- **Tor / прокси не используем** (D4 в `../DECISIONS.md`). Подключим если домашний IP начнёт лочить.
+
+---
+
+## Внешние ссылки
+
+- **Botasaurus:** https://github.com/omkarcloud/botasaurus
+- **Yandex.Maps URL формат:** `https://yandex.ru/maps/{geo_id}/{slug}/search/{query}/`
+- **Rusprofile (ЕГРЮЛ fallback):** https://www.rusprofile.ru/
+- **DaData Suggestions API (primary ЕГРЮЛ):** https://dadata.ru/api/suggest/party/ (10K/день free)
+- **DuckDuckGo HTML (find-sites):** https://html.duckduckgo.com/html/
+- **VK API:** https://dev.vk.com/reference (постпонировано)
+- **2ГИС API:** https://docs.2gis.com/ru/api/search/3.0 (постпонировано)
+- **HH:** через Botasaurus браузер (api.hh.ru 403'ит)
+
+---
+
+*Версия: v7.1 (Прогрессивный ICP-штраф за зрелость) | Обновлено: 2026-06-01*
+*Changelog:*
+*- v7.1 (2026-06-01): ICP-гейт стал прогрессивным — штраф за отзывы×рейтинг (D18): линейная шкала отзывов, рейтинг усиливает, база гарантирует штраф сетям. Порог hot 7→6. Калибровка под цель «Кафе Гурмэ=6».*
+*- v7 (2026-06-01): Скоринг переписан на v5 — «решаемая нами боль» × ICP (D17). Категорийная релевантность детекторов (booking/social по белым спискам, дефолт консервативный). Фикс потери URL сайта в ЕГРЮЛ-обогащении + восстановление 29 лидов. Рейтинг 4.5+ больше не боль. Instagram исключён (бан РФ). Новые колонки `pain_products`/`band`/`diagnostic_coverage`. CRM: бэнды + «с чем заходить» + фильтр по продукту. Детект конструкторов по домену (Я.Бизнес `.clients.site`). Инструмент `audit_scores.py`.*
+*- v6 (2026-05-21): WB парсер удалён (D17). DaData primary + Rusprofile fallback (D14). DDG Find-Sites (`contacts_finder.py` D16). INN из footer сайта (152-ФЗ). Blacklist крупных компаний (`blacklist.py` D15, 143 leads excluded). `--full` теперь включает `--find-sites` + `--hh-enrich-websites` если source=hh.*
+*- v5 (2026-05-17): CRM-блок + расширенный сбор контактов (Я.Карты body-text + website email/phones).*