# Supermarket Scraper System

## Обзор проекта

Система для скрапинга товаров из российских супермаркетов (Магнит, Пятёрочка/5ka) с хранением в PostgreSQL, векторным поиском через pgvector, и интеграцией LLM для естественных запросов.

**Текущий статус:** MVP Phase - Magnit API scraping functional

**Последнее обновление:** 2025-01-21

---

## Текущий статус (Progress Tracker)

### ✅ Завершено

| Этап | Название | Статус | Описание |
|------|----------|--------|----------|
| 1 | База данных + Prisma | ✅ Done | PostgreSQL, Prisma ORM, pgvector extension |
| 2 | Magnit API Scraper | ✅ Done | Hybrid Playwright+Axios, streaming mode, retry logic |
| - | Docker Infrastructure | ✅ Done | PostgreSQL + pgAdmin + CloudBeaver |

### ⏳ В работе

| Этап | Название | Статус | Следующий шаг |
|------|----------|--------|---------------|
| - | Debug скрипты → Тесты | ⏳ TODO | Превратить debug scripts в Vitest тесты |

### 📋 Запланировано

| Этап | Название | Приоритет | Зависимости |
|------|----------|-----------|-------------|
| 3 | Embeddings + Vector Search | High | Этап 1-2 |
| 4 | BaseApiScraper + 5ka API | High | Этап 2 |
| 5 | Web Scraping (Playwright) | Medium | Этап 4 |
| 6 | Android Scraping (Appium) | Low | Этап 5 |
| 7 | LangChain Integration | Medium | Этап 3 |
| 8 | REST API + Scheduler | Medium | Этап 7 |

---

## Roadmap

### Этап 1: База данных и Prisma ✅
- [x] PostgreSQL с Docker
- [x] Prisma ORM setup
- [x] Модели: Store, Category, Product, ScrapingSession
- [x] pgvector extension (подготовлено для embeddings)

### Этап 2: Magnit API Scraping ✅
- [x] Hybrid approach: Playwright (сессия) + Axios (API запросы)
- [x] Обход 403 Forbidden с auto-reinit
- [x] Streaming mode для больших каталогов
- [x] Retry logic с exponential backoff
- [x] Rate limiting и защита от infinite loops

### Этап 3: Embeddings и Vector Search 📋
**Следующий приоритетный этап**

- [ ] Добавить `embedding vector(1536)` поля в Product и Category
- [ ] Создать миграцию pgvector
- [ ] EmbeddingService (OpenAI или Ollama)
- [ ] Векторный поиск товаров

### Этап 4: API Scraping - Полная реализация 📋
- [ ] BaseApiScraper с общим функционалом
- [ ] 5ka API scraper
- [ ] Category-based pagination

### Этап 5: Web и Android Scraping 📋
- [ ] MagnitWebScraper (Playwright fallback)
- [ ] 5kaWebScraper
- [ ] MagnitAppScraper (Appium)
- [ ] 5kaAppScraper

### Этап 6: LangChain Integration 📋
- [ ] SQL Agent для natural language запросов
- [ ] Query chains
- [ ] Пример: "найди самый дешевый попкорн"

### Этап 7: Scheduler и REST API 📋
- [ ] SchedulerService (node-cron)
- [ ] REST API server (Express/Fastify)
- [ ] Endpoints для n8n интеграции
- [ ] Job monitoring

### Этап 8: Price History Analytics 📋
- [ ] PriceHistory model (уже в схеме)
- [ ] Автоматический трекинг цен
- [ ] Уведомления об изменениях

---

## Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                     Data Sources                             │
├──────────┬──────────────┬───────────────────────────────────┤
│   API    │  Web Scrapers│    Android App Scrapers           │
│ Scrapers │ (Playwright) │         (Appium)                  │
│          │              │                                    │
│ ✅ Magnit│ ⏳ magnit.ru │ ⏳ Магнит Android App             │
│ ⏳ 5ka   │ ⏳ 5ka.ru     │ ⏳ 5ka Android App                 │
└──────────┴──────────────┴───────────────────────────────────┘
                  │
     ┌────────────▼────────────┐
     │   Data Processing Layer │
     │  - Parsing & Normalize  │
     │  - Embeddings Generation│
     └────────────┬────────────┘
                  │
     ┌────────────▼────────────┐
     │   PostgreSQL Database   │
     │  - pgvector extension   │
     │  - Products, Categories │
     │  - Price History        │
     └────────────┬────────────┘
                  │
     ┌────────────▼────────────┐
     │   LangChain + LLM       │
     │  - SQL Agent            │
     │  - Query Interface      │
     └─────────────────────────┘
```

---

## Стек технологий

| Категория | Технология |
|-----------|------------|
| Runtime | Node.js + TypeScript |
| Database | PostgreSQL 15+ + pgvector |
| ORM | Prisma |
| API Scraping | Axios + Playwright |
| Web Scraping | Playwright |
| Mobile | Appium + WebDriverIO |
| LLM | LangChain + OpenAI/Ollama |
| Scheduler | node-cron |
| HTTP Server | Express/Fastify |
| Testing | Vitest |
| Package Manager | pnpm |

---

## Quick Start

```bash
# Установка зависимостей
pnpm install

# Установка браузеров для Playwright
pnpm exec playwright install chromium

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env: DATABASE_URL, MAGNIT_STORE_CODE

# Запуск PostgreSQL
docker-compose up -d

# Генерация Prisma Client
pnpm prisma:generate

# Создание миграций
pnpm prisma:migrate

# Запуск скрапинга
pnpm dev

# Доступ к DB Admin:
# pgAdmin: http://localhost:5050
# CloudBeaver: http://localhost:8978
```

---

## Конфигурация

### Переменные окружения (.env)

```bash
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/supermarket

# Magnit Store
MAGNIT_STORE_CODE=992301
MAGNIT_STORE_TYPE=6
MAGNIT_CATALOG_TYPE=1

# Scraping Options
MAGNIT_USE_STREAMING=true          # streaming mode (рекомендуется)
MAGNIT_PAGE_SIZE=50                # размер страницы API
MAGNIT_MAX_PRODUCTS=               # лимит товаров (пусто = без лимита)
MAGNIT_RATE_LIMIT_DELAY=300        # задержка между запросами (ms)
MAGNIT_MAX_ITERATIONS=10000        # защита от бесконечного цикла
MAGNIT_HEADLESS=true               # headless режим браузера

# Resilience
MAGNIT_RETRY_ATTEMPTS=3            # количество попыток retry
MAGNIT_REQUEST_TIMEOUT=30000       # timeout запросов (ms)
```

---

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

```
supermarket/
├── src/
│   ├── config/
│   │   └── database.ts            # DB connection & setup
│   ├── database/
│   │   ├── prisma/
│   │   │   └── schema.prisma      # Prisma schema
│   │   └── client.ts              # Prisma Client instance
│   ├── scrapers/
│   │   ├── api/
│   │   │   └── magnit/
│   │   │       ├── MagnitApiScraper.ts
│   │   │       └── types.ts
│   │   ├── web/                   # TODO: Playwright scrapers
│   │   └── android/               # TODO: Appium scrapers
│   ├── services/
│   │   ├── product/
│   │   │   ├── ProductService.ts
│   │   │   └── ProductParser.ts
│   │   └── embeddings/            # TODO: EmbeddingService
│   ├── scripts/
│   │   └── scrape-magnit-products.ts
│   └── utils/
│       ├── logger.ts
│       ├── errors.ts
│       └── retry.ts
├── tests/                         # TODO: Create tests
│   └── integration/
├── docker-compose.yml
├── package.json
├── README.md                      # Basic setup guide
├── CLAUDE.md                      # Instructions for Claude Code
├── PROJECT.md                     # This file - roadmap & status
└── .cursor/
    └── plans/
        └── supermarket_scraper_system_1af4ed29.plan.md
```

---

## Недавние изменения

### [9164527] feat: enhanced Magnit scraper with streaming mode and retry logic (2025-01-21)

- ✅ Streaming mode для memory-efficient больших каталогов
- ✅ Retry logic с exponential backoff
- ✅ Auto session reinitialization on 403 errors
- ✅ Configurable options (pageSize, maxProducts, rateLimitDelay)
- ✅ maxIterations защита от infinite loops
- ✅ retry.ts utility module
- ✅ Docker: pgAdmin + CloudBeaver

---

## Что дальше?

### Ближайшие задачи (Priority Order):

1. **Debug скрипты → Тесты** (в процессе)
   - Превратить `analyze-category-nulls.ts`, `check-product-details.ts`, `inspect-api-response.ts` в Vitest тесты
   - Настроить `tests/integration/` структуру

2. **Embeddings (Этап 3)**
   - Добавить pgvector поля в schema
   - Создать EmbeddingService
   - Генерация embeddings для товаров

3. **5ka API Scraper (Этап 4)**
   - BaseApiScraper abstraction
   - 5ka API integration

4. **REST API + Scheduler (Этап 7)**
   - HTTP server для внешних интеграций
   - Cron-like планировщик

---

## Полезные ссылки

- **Cursor Plan**: [.cursor/plans/supermarket_scraper_system_1af4ed29.plan.md](.cursor/plans/supermarket_scraper_system_1af4ed29.plan.md) - Полная техническая спецификация
- **Prisma Schema**: [src/database/prisma/schema.prisma](src/database/prisma/schema.prisma)
- **Main Scraper**: [src/scrapers/api/magnit/MagnitApiScraper.ts](src/scrapers/api/magnit/MagnitApiScraper.ts)

---

## Лицензия

Private project