From 6ba22469c78c381fcccefa6e2a7dc9e302f8a9cd Mon Sep 17 00:00:00 2001 From: Mc Smog Date: Wed, 21 Jan 2026 22:23:45 +0500 Subject: [PATCH] docs: add PROJECT.md with roadmap and progress tracker - 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 --- PROJECT.md | 297 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 297 insertions(+) create mode 100644 PROJECT.md diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..cab4768 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,297 @@ +# 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