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 <noreply@anthropic.com>
This commit is contained in:
297
PROJECT.md
Normal file
297
PROJECT.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user