657 lines
18 KiB
Markdown
657 lines
18 KiB
Markdown
# Спека: Yandex Market Dashcam Catalog Ingestion
|
||
|
||
## 1. Цель
|
||
|
||
Построить поддерживаемый ingestion engine для каталога автомобильных видеорегистраторов.
|
||
|
||
Целевая категория:
|
||
|
||
`Автомобильные видеорегистраторы`
|
||
|
||
Публичное приложение должно получать только approved canonical catalog:
|
||
|
||
* название
|
||
* бренд
|
||
* модель
|
||
* нормализованные характеристики
|
||
* изображения
|
||
* source metadata
|
||
* дату первого обнаружения
|
||
* дату последнего обновления
|
||
|
||
В MVP не парсим и не экспортируем:
|
||
|
||
* цены
|
||
* продавцов
|
||
* наличие
|
||
* тексты отзывов
|
||
* авторов отзывов
|
||
* review content
|
||
|
||
Общий aggregate rating можно сохранять внутри ingestion как source signal, но он не входит в публичный export и не участвует в `stableContentHash`.
|
||
|
||
Главная мысль: не "краулер, который пролезет", а каталоговый ingestion engine, который можно поддерживать годами.
|
||
|
||
---
|
||
|
||
## 2. Границы и запреты
|
||
|
||
Не реализовывать:
|
||
|
||
* обход rate limiter
|
||
* маскировку под реальных пользователей
|
||
* ротацию User-Agent / browser fingerprint
|
||
* прокси-фермы
|
||
* headless stealth
|
||
* обход captcha
|
||
* агрессивную параллельную загрузку
|
||
* регулярный browser-based crawl
|
||
|
||
В MVP fetcher работает только через обычный HTTP fetch.
|
||
|
||
Headless browser допустим только как ручной diagnostic tool для анализа структуры страницы. Он не является fallback в регулярном crawl path.
|
||
|
||
---
|
||
|
||
## 3. Источники
|
||
|
||
### Primary
|
||
|
||
* публичные category pages Яндекс Маркета
|
||
* публичные product pages
|
||
* JSON-LD, если доступен в HTML
|
||
* embedded state, если доступен в HTML
|
||
* sitemap, но только в ограниченных границах
|
||
|
||
### Preferred official fallback
|
||
|
||
* Yandex Market Partner API, если доступен по условиям проекта
|
||
* фиды продавцов, если доступны легально
|
||
* фиды брендов
|
||
* официальные сайты производителей
|
||
|
||
---
|
||
|
||
## 4. Deployment Model
|
||
|
||
Ingestion деплоится в то же облако, что и web-приложение (один Swarm/Portainer
|
||
environment), а не на отдельный сервер. Раньше предполагался отдельный cloud, но
|
||
управлять двумя независимыми облаками оказалось слишком сложно. См. решение
|
||
`videoreg-nnv.3`.
|
||
|
||
Код хранится в этом же репозитории:
|
||
|
||
```text
|
||
ingestion/
|
||
src/
|
||
migrations/
|
||
docker-compose.yml
|
||
Dockerfile
|
||
```
|
||
|
||
Минимальные сервисы:
|
||
|
||
```text
|
||
postgres
|
||
ingestion-worker
|
||
ingestion-admin
|
||
```
|
||
|
||
`export-server` больше не нужен: ingestion-worker пишет валидированный
|
||
`catalog.json` + `manifest.json` в общий (shared) export-том, а web читает их
|
||
напрямую с этого тома. Никакого HTTP-экспорта и Bearer-токена.
|
||
|
||
Основное Next.js-приложение по-прежнему не подключается напрямую к ingestion DB —
|
||
единственный контакт с каталогом идёт через export-артефакт на shared-томе.
|
||
|
||
---
|
||
|
||
## 5. Source of Truth и Bridge
|
||
|
||
Source of truth для каталога: PostgreSQL ingestion stack.
|
||
|
||
Текущее примитивное хранилище приложения (`data/videoreg.json`) является только read-model cache.
|
||
|
||
Bridge работает со стороны приложения через общий export-том:
|
||
|
||
1. ingestion пишет versioned export (`manifest.json` + `catalog.json`) на shared-том;
|
||
2. приложение/сборка читает `manifest.json` с того же тома;
|
||
3. проверяет `schemaVersion`, `exportId`, `createdAt`, `sha256`, `itemCount`;
|
||
4. читает `catalog.json` с тома;
|
||
5. сверяет `sha256` артефакта;
|
||
6. валидирует payload через shared Zod schema;
|
||
7. атомарно заменяет `data/videoreg.json` (или используется как build-time источник).
|
||
|
||
В MVP import запускается вручную оператором, не по расписанию. HTTP/токен в этом
|
||
обмене не участвуют — оба сервиса в одном облаке и делят том.
|
||
|
||
---
|
||
|
||
## 6. Export Contract
|
||
|
||
Export публикуется как файлы на общем (shared) export-томе: `manifest.json` и
|
||
`artifacts/<exportId>/catalog.json`. HTTP-эндпоинт и Bearer-токен не используются —
|
||
ingestion и web живут в одном облаке и делят том. Целостность гарантируется
|
||
`sha256` в манифесте и shared Zod-схемой при чтении.
|
||
|
||
### Manifest
|
||
|
||
```ts
|
||
type CatalogExportManifest = {
|
||
schemaVersion: 1;
|
||
exportId: string;
|
||
createdAt: string;
|
||
artifactPath: string;
|
||
sha256: string;
|
||
itemCount: number;
|
||
};
|
||
```
|
||
|
||
### Catalog Artifact
|
||
|
||
```ts
|
||
type DashcamCatalogExport = {
|
||
schemaVersion: 1;
|
||
exportId: string;
|
||
createdAt: string;
|
||
products: ExportedDashcamProduct[];
|
||
};
|
||
|
||
type ExportedDashcamProduct = {
|
||
id: string;
|
||
brand: string;
|
||
model: string;
|
||
canonicalName?: string;
|
||
title: string;
|
||
specs: Record<string, string | number | boolean>;
|
||
images: ExportedProductImage[];
|
||
sources: ExportedProductSource[];
|
||
discoveredAt: string;
|
||
updatedAt: string;
|
||
};
|
||
|
||
type ExportedProductImage = {
|
||
url: string;
|
||
originalUrl: string;
|
||
source: MarketSource;
|
||
sha256?: string;
|
||
width?: number;
|
||
height?: number;
|
||
};
|
||
|
||
type ExportedProductSource = {
|
||
source: MarketSource;
|
||
sourceProductId?: string;
|
||
url: string;
|
||
stableContentHash: string;
|
||
fetchedAt: string;
|
||
};
|
||
|
||
type MarketSource = "yandex_market" | "mvideo";
|
||
```
|
||
|
||
Runtime validation: shared Zod schema в репозитории. TypeScript-типы без runtime-валидации недостаточны.
|
||
|
||
---
|
||
|
||
## 7. Image Policy
|
||
|
||
Ingestion кеширует approved images и публикует versioned image artifact URLs.
|
||
|
||
Export содержит:
|
||
|
||
* URL versioned image artifact
|
||
* original source URL
|
||
* source metadata
|
||
* optional checksum/dimensions
|
||
|
||
Приложение не должно hotlink-ить source images напрямую.
|
||
|
||
Юридическое решение о хранении и показе изображений должно быть принято отдельно до production-публикации.
|
||
|
||
---
|
||
|
||
## 8. Crawl Policy
|
||
|
||
Нагрузка:
|
||
|
||
* 1 запрос за 5-15 секунд
|
||
* максимум 100-300 страниц в сутки на источник
|
||
* jitter между запросами
|
||
* exponential backoff при 429/403/5xx
|
||
* остановка источника при captcha
|
||
* отдельный дневной budget на category pages, product pages, sitemap
|
||
* не скачивать повторно страницы, если stable content не изменился
|
||
|
||
HTTP-only fetcher должен явно детектить:
|
||
|
||
```text
|
||
rate_limited
|
||
blocked
|
||
captcha
|
||
not_found
|
||
parse_failed
|
||
needs_manual_review
|
||
```
|
||
|
||
При `captcha`, `403`, `429` источник ставится на паузу. Не пытаться обходить ограничение.
|
||
|
||
---
|
||
|
||
## 9. Discovery Strategy
|
||
|
||
Discovery работает sitemap-first, но не обходит широкий sitemap всего Маркета.
|
||
|
||
Границы discovery задают:
|
||
|
||
* ручные seed category URLs
|
||
* ручные seed product URL patterns
|
||
* product URLs, найденные из category HTTP discovery
|
||
* уже известные product URLs
|
||
|
||
Sitemap используется для:
|
||
|
||
* diff известных URL
|
||
* refresh кандидатных URL
|
||
* обнаружение URL рядом с уже известными границами
|
||
|
||
Category pages используются вторично:
|
||
|
||
* первая страница категории
|
||
* пагинация, если доступна без JS
|
||
* top listings
|
||
* новые product URLs, если они есть в HTML
|
||
|
||
Если category HTML бедный без JS, discovery не должен переходить в regular headless crawl. Такие случаи уходят в `needs_manual_review` или official fallback.
|
||
|
||
```ts
|
||
type DiscoveredProduct = {
|
||
source: MarketSource;
|
||
categoryUrl?: string;
|
||
productUrl: string;
|
||
sourceProductId?: string;
|
||
titlePreview?: string;
|
||
discoveredAt: string;
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Fetch Queue
|
||
|
||
Очередь реализуется в PostgreSQL, без Redis/BullMQ в MVP.
|
||
|
||
State machine:
|
||
|
||
```text
|
||
pending
|
||
-> fetching
|
||
-> fetched
|
||
-> parsed
|
||
-> normalized
|
||
-> deduplicated
|
||
-> needs_review
|
||
-> approved
|
||
-> exported
|
||
```
|
||
|
||
Ошибочные состояния:
|
||
|
||
```text
|
||
rate_limited
|
||
blocked
|
||
captcha
|
||
not_found
|
||
parse_failed
|
||
needs_manual_review
|
||
```
|
||
|
||
Для каждой задачи хранить:
|
||
|
||
* source
|
||
* URL
|
||
* job type
|
||
* state
|
||
* attempts
|
||
* nextRunAt
|
||
* lastError
|
||
* createdAt
|
||
* updatedAt
|
||
|
||
Backoff и daily budgets считаются в PostgreSQL.
|
||
|
||
---
|
||
|
||
## 11. Parser
|
||
|
||
Parser извлекает только разрешенные поля:
|
||
|
||
* title
|
||
* brand
|
||
* model
|
||
* specs
|
||
* images
|
||
* sourceProductId
|
||
* aggregate rating как internal-only signal
|
||
|
||
Приоритет источников внутри страницы:
|
||
|
||
```text
|
||
JSON-LD > embedded state > semantic DOM > fallback DOM
|
||
```
|
||
|
||
Не извлекать:
|
||
|
||
* prices
|
||
* sellers
|
||
* availability
|
||
* review texts
|
||
* review authors
|
||
|
||
```ts
|
||
type ParsedMarketProduct = {
|
||
source: MarketSource;
|
||
sourceProductId?: string;
|
||
title: string;
|
||
brand?: string;
|
||
model?: string;
|
||
aggregateRating?: {
|
||
value: number;
|
||
scale?: number;
|
||
ratingCount?: number;
|
||
};
|
||
images: string[];
|
||
specs: Record<string, string | number | boolean>;
|
||
sourceUrl: string;
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Snapshot и Checksum Model
|
||
|
||
Сырой snapshot хранить всегда. Парсер должен уметь переобрабатывать старые страницы.
|
||
|
||
Нельзя использовать hash всего HTML как сигнал "страница изменилась": динамическая верстка, цены, рекомендации, счетчики и timestamps будут постоянно шуметь.
|
||
|
||
Для каждого snapshot хранить два хэша:
|
||
|
||
```ts
|
||
type ProductSourceSnapshot = {
|
||
source: MarketSource;
|
||
url: string;
|
||
fetchedAt: string;
|
||
httpStatus: number;
|
||
rawSnapshotHash: string;
|
||
stableContentHash?: string;
|
||
rawHtmlPath?: string;
|
||
parsedJson: Record<string, unknown>;
|
||
};
|
||
```
|
||
|
||
### `rawSnapshotHash`
|
||
|
||
Хэш точного raw snapshot для аудита и debug.
|
||
|
||
### `stableContentHash`
|
||
|
||
Source-specific semantic hash. Для Яндекс Маркета в MVP включать:
|
||
|
||
* sourceProductId
|
||
* canonical product URL
|
||
* title
|
||
* brand
|
||
* model
|
||
* normalized specs
|
||
* image identifiers / original image URLs
|
||
|
||
Исключать:
|
||
|
||
* price
|
||
* sellers
|
||
* availability
|
||
* aggregate rating
|
||
* review count
|
||
* timestamps
|
||
* layout
|
||
* recommendations
|
||
* counters
|
||
* tracking data
|
||
|
||
---
|
||
|
||
## 13. Normalization
|
||
|
||
Нужно привести хаотичные характеристики к единому виду.
|
||
|
||
Пример:
|
||
|
||
```json
|
||
{
|
||
"resolution_front": "3840x2160",
|
||
"channels": 2,
|
||
"sensor_front": "Sony STARVIS 2",
|
||
"gps": true,
|
||
"wifi": true,
|
||
"screen": true,
|
||
"parking_mode": true,
|
||
"memory_card_max_gb": 256,
|
||
"view_angle_degrees": 140
|
||
}
|
||
```
|
||
|
||
Компоненты normalizer:
|
||
|
||
* brand dictionary
|
||
* model cleaner
|
||
* spec mapper
|
||
* unit converter
|
||
* boolean detector
|
||
* alias dictionary
|
||
|
||
---
|
||
|
||
## 14. Deduplication
|
||
|
||
Дедупликация работает до модерации. Единица модерации: canonical product, уже сгруппированный из вариантов и source URLs.
|
||
|
||
Сравнивать:
|
||
|
||
* brand
|
||
* normalized model name
|
||
* aliases
|
||
* sourceProductId
|
||
* image perceptual hash
|
||
* specs similarity
|
||
* product URL history
|
||
|
||
Статусы:
|
||
|
||
```text
|
||
new_product
|
||
same_product
|
||
possible_duplicate
|
||
variant
|
||
oem_clone
|
||
```
|
||
|
||
`possible_duplicate`, `variant`, `oem_clone` не должны попадать в public export без ручного решения.
|
||
|
||
---
|
||
|
||
## 15. Moderation Admin
|
||
|
||
Админка живет внутри отдельного ingestion stack.
|
||
|
||
Она работает напрямую с ingestion PostgreSQL, snapshots, очередями и canonical products.
|
||
|
||
MVP-экраны:
|
||
|
||
* новые canonical products
|
||
* bulk select
|
||
* "разрешить все"
|
||
* товары с `parse_failed`
|
||
* возможные дубли
|
||
* конфликтующие характеристики
|
||
* история изменений
|
||
* ручное объединение моделей
|
||
* ручное редактирование canonical specs
|
||
|
||
Публикация в export разрешена только после ручной модерации. Bulk approve допустим, но утверждает canonical products, а не отдельные source URLs.
|
||
|
||
---
|
||
|
||
## 16. Database
|
||
|
||
Минимальная PostgreSQL-модель:
|
||
|
||
```sql
|
||
products
|
||
product_variants
|
||
product_sources
|
||
source_snapshots
|
||
product_specs
|
||
product_images
|
||
source_ratings
|
||
crawl_jobs
|
||
crawl_errors
|
||
moderation_queue
|
||
export_runs
|
||
```
|
||
|
||
Принципы:
|
||
|
||
* raw HTML/JSON snapshots и image artifacts хранить на mounted volume
|
||
* в PostgreSQL хранить пути, checksum, metadata и связи
|
||
* уникальность по `source + url`
|
||
* ingestion DB является source of truth
|
||
* `data/videoreg.json` приложения является replaceable read-model cache
|
||
|
||
---
|
||
|
||
## 17. Sync Schedule
|
||
|
||
### Частый легкий sync
|
||
|
||
Каждые 6-12 часов:
|
||
|
||
* первая страница категории
|
||
* sitemap diff в пределах известных границ
|
||
* новые product URLs
|
||
* изменение top listings, если доступно без JS
|
||
|
||
### Глубокий sync
|
||
|
||
Раз в 7-14 дней:
|
||
|
||
* все известные карточки
|
||
* характеристики
|
||
* изображения
|
||
* source metadata
|
||
|
||
### New product detection
|
||
|
||
Каждый день:
|
||
|
||
* category diff
|
||
* bounded sitemap diff
|
||
* known model aliases search
|
||
* official fallback feeds, если доступны
|
||
|
||
---
|
||
|
||
## 18. MVP Phases
|
||
|
||
### Phase 1 - Legal discovery
|
||
|
||
* проверить robots.txt
|
||
* проверить sitemap
|
||
* проверить доступность API/фидов
|
||
* описать crawl budget
|
||
* описать allowed URL patterns
|
||
* зафиксировать image storage policy
|
||
|
||
### Phase 2 - Shared contract
|
||
|
||
* добавить shared Zod schema для manifest/catalog export
|
||
* добавить TypeScript-типы из схем
|
||
* описать `schemaVersion`
|
||
* добавить app import command
|
||
* заменить `data/videoreg.json` validated catalog payload
|
||
|
||
### Phase 3 - Ingestion stack skeleton
|
||
|
||
* создать `ingestion/`
|
||
* добавить `docker-compose.yml`
|
||
* поднять PostgreSQL
|
||
* добавить migrations
|
||
* добавить mounted volume для snapshots/images
|
||
* добавить healthcheck
|
||
|
||
### Phase 4 - Queue and fetcher
|
||
|
||
* реализовать PostgreSQL-backed queue
|
||
* реализовать HTTP-only fetcher
|
||
* добавить rate limits, retry, backoff
|
||
* stop on captcha / 403 / 429
|
||
* сохранять raw snapshots
|
||
* считать `rawSnapshotHash`
|
||
|
||
### Phase 5 - Parser
|
||
|
||
* category parser
|
||
* bounded sitemap discovery
|
||
* product parser
|
||
* specs parser
|
||
* image parser
|
||
* aggregate rating parser as internal-only
|
||
* source-specific `stableContentHash`
|
||
|
||
### Phase 6 - Normalizer
|
||
|
||
* brand dictionary
|
||
* model cleaner
|
||
* spec mapper
|
||
* unit converter
|
||
* boolean detector
|
||
|
||
### Phase 7 - Deduplication and moderation
|
||
|
||
* exact match
|
||
* fuzzy match
|
||
* alias match
|
||
* canonical product grouping
|
||
* moderation queue
|
||
* bulk approve
|
||
|
||
### Phase 8 - Export and import
|
||
|
||
* publish versioned manifest
|
||
* publish versioned catalog artifact
|
||
* publish versioned image artifacts
|
||
* write export artifacts to the shared export volume (no HTTP, no token)
|
||
* verify checksum in app import
|
||
* atomic replace of `data/videoreg.json`
|
||
|
||
---
|
||
|
||
## 19. Definition of Done
|
||
|
||
Система считается готовой, если:
|
||
|
||
* ingestion и web деплоятся в одно облако; export идёт через shared-том, без HTTP/токена
|
||
* PostgreSQL является source of truth
|
||
* приложение импортирует только approved canonical catalog
|
||
* `data/videoreg.json` заменяется только после manifest/checksum/schema validation
|
||
* crawler не создает заметной нагрузки на источник
|
||
* crawler останавливается при ограничениях
|
||
* crawler не использует regular headless/browser stealth
|
||
* raw snapshots хранятся всегда
|
||
* есть `rawSnapshotHash` и source-specific `stableContentHash`
|
||
* старые snapshots можно переобработать новым parser
|
||
* дубли попадают в moderation queue
|
||
* bulk approve работает по canonical products
|
||
* public export не содержит цены, продавцов, наличие и тексты отзывов
|
||
* public export не содержит aggregate rating в MVP
|
||
* approved images отдаются как versioned image artifacts
|