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

## 📋 Обзор

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

---

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

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

### Запуск:
```bash
pnpm dev
```

### Опционально: указать магазин
```bash
MAGNIT_STORE_CODE=992301 pnpm dev
```

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

---

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

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

### Запуск:
```bash
pnpm enrich
```

### Опционально: указать магазин
```bash
MAGNIT_STORE_CODE=992301 pnpm enrich
```

### Результат:
- Поля `brand`, `description`, `weight`, `unit` заполнены
- Все товары имеют `isDetailsFetched = true`

---

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

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

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

---

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

### Проверить соединение с БД:
```bash
pnpm test-db
```

### Проверить detail endpoint:
```bash
pnpm test-detail-endpoint
```

---

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

### Через SQL:
```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";
```

---

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

### Создать и применить миграцию:
```bash
pnpm prisma:migrate --name название_миграции
```

### Пересоздать Prisma Client:
```bash
pnpm prisma:generate
```

### Открыть Prisma Studio:
```bash
pnpm prisma:studio
```

---

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

### Advisory lock при миграции
Если при миграции возникает `P1002` error:
```bash
# Перезапустить 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 для работы с БД |