supermarket/docs/E2E_GUIDE.md

Руководство по скрапингу товаров Магнит

📋 Обзор

Процесс состоит из двух этапов:

1. Базовый скрапинг - получение списка товаров через API поиска
2. Обогащение деталями - получение бренда, описания, веса для каждого товара

---

🚀 Этап 1: Базовый скрапинг

Что делает:

• Сканирует каталог товаров через API поиска
• Сохраняет базовую информацию: название, цена, рейтинг, изображение
• Сохраняет товары в базу данных с isDetailsFetched = false

Запуск:

pnpm dev

Опционально: указать магазин

MAGNIT_STORE_CODE=992301 pnpm dev

Результат:

• В таблице Product появляются записи с базовыми данными
• Поля brand, description, weight, unit пустые
• isDetailsFetched = false

---

✨ Этап 2: Обогащение деталями

Что делает:

• Получает товары с isDetailsFetched = false
• Для каждого товара запрашивает детали через специальный API endpoint
• Обновляет: бренд, описание, вес, единицу измерения
• Ставит isDetailsFetched = true

Запуск:

pnpm enrich

Опционально: указать магазин

MAGNIT_STORE_CODE=992301 pnpm enrich

Результат:

• Поля brand, description, weight, unit заполнены
• Все товары имеют isDetailsFetched = true

---

🔄 Полный цикл (последовательный)

# 1. Базовый скрапинг
pnpm dev

# 2. Обогащение деталями
pnpm enrich

---

🧪 Тестирование

Проверить соединение с БД:

pnpm test-db

Проверить detail endpoint:

pnpm test-detail-endpoint

---

📊 Проверка результатов

Через SQL:

-- Количество товаров
SELECT COUNT(*) FROM "Product";

-- Сколько обогащено
SELECT
  COUNT(*) FILTER (WHERE "isDetailsFetched" = true) as enriched,
  COUNT(*) FILTER (WHERE "isDetailsFetched" = false) as pending
FROM "Product";

-- Процент NULL полей
SELECT
  'brand' as field,
  ROUND(100.0 * SUM(CASE WHEN brand IS NULL THEN 1 ELSE 0 END) / COUNT(*), 2) as null_percent
FROM "Product"
UNION ALL
SELECT 'description', ROUND(100.0 * SUM(CASE WHEN description IS NULL THEN 1 ELSE 0 END) / COUNT(*), 2) FROM "Product"
UNION ALL
SELECT 'weight', ROUND(100.0 * SUM(CASE WHEN weight IS NULL THEN 1 ELSE 0 END) / COUNT(*), 2) FROM "Product"
UNION ALL
SELECT 'unit', ROUND(100.0 * SUM(CASE WHEN unit IS NULL THEN 1 ELSE 0 END) / COUNT(*), 2) FROM "Product";

---

🛠️ Управление миграциями

Создать и применить миграцию:

pnpm prisma:migrate --name название_миграции

Пересоздать Prisma Client:

pnpm prisma:generate

Открыть Prisma Studio:

pnpm prisma:studio

---

⚠️ Возможные проблемы

Advisory lock при миграции

Если при миграции возникает P1002 error:

# Перезапустить PostgreSQL контейнер
docker restart supermarket-postgres

403 Forbidden при скрапинге

Скрапер автоматически переинициализирует сессию. Проверьте логи.

Пустые результаты

Проверьте, что магазин с указанным MAGNIT_STORE_CODE существует.

---

📝 Доступные команды

Команда	Описание
pnpm dev	Базовый скрапинг товаров
pnpm enrich	Обогащение деталями
pnpm test-db	Проверка соединения с БД
pnpm test-detail-endpoint	Тест detail API
pnpm type-check	Проверка типов TypeScript
pnpm prisma:studio	GUI для работы с БД