supermarket/PROJECT.md

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 ✅

• PostgreSQL с Docker
• Prisma ORM setup
• Модели: Store, Category, Product, ScrapingSession
• pgvector extension (подготовлено для embeddings)

Этап 2: Magnit API Scraping ✅

• Hybrid approach: Playwright (сессия) + Axios (API запросы)
• Обход 403 Forbidden с auto-reinit
• Streaming mode для больших каталогов
• Retry logic с exponential backoff
• 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

# Установка зависимостей
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)

# 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 - Полная техническая спецификация
• Prisma Schema: src/database/prisma/schema.prisma
• Main Scraper: src/scrapers/api/magnit/MagnitApiScraper.ts

---

Лицензия

Private project