Mc Smog
6ba22469c7
- Create central project documentation with roadmap - Add progress tracker with status tables - Include architecture diagram and tech stack - Add quick start guide and configuration reference - Document recent changes and next steps Co-Authored-By: Claude <noreply@anthropic.com>
298 lines
11 KiB
Markdown
298 lines
11 KiB
Markdown
# 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
|