refactor: reorganize scripts - move debug code to experiments/

- Move debug/test scripts from src/scripts/ to experiments/ - Remove test-detail-endpoint from package.json - Delete temp-product-page.html - Move E2E_GUIDE.md to docs/ - Add experiments/README.md with documentation - Keep only production scripts in src/scripts/ - Clean up tsconfig.json exclude list (experiments are now outside src/) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-22 01:55:20 +05:00
parent 3299cca574
commit dd4c64c601
10 changed files with 675 additions and 1 deletions
--- a/docs/E2E_GUIDE.md
+++ b/docs/E2E_GUIDE.md
@@ -0,0 +1,158 @@
+# Руководство по скрапингу товаров Магнит
+
+## 📋 Обзор
+
+Процесс состоит из двух этапов:
+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 для работы с БД |