Product Requirements Document (PRD)

rpscrape Enhanced Fork - "rpscrape-pro"

Verzia: 1.0 Dátum: 2025-12-09 Status: In Development

1. EXECUTIVE SUMMARY

1.1 Účel dokumentu

Tento PRD definuje požiadavky na vylepšený fork projektu rpscrape s dôrazom na produkčnú stabilitu, profesionálny debugging, anti-ban ochranu a reálne použitie.

1.2 Cieľ projektu

Vytvoriť produkčne-ready nástroj na scraping koňských dostihových dát, ktorý:

Funguje spoľahlivo bez manuálneho zásahu
Loguje všetky operácie pre debugging
Chráni sa pred IP banmi a detekciou
Automaticky sa zotavuje z chýb

1.3 Non-Goals (Čo NEROBÍME)

Web UI/Dashboard (nie je potrebné)
Multi-tenancy (jednouzívateľský nástroj)
Real-time streaming (batch processing stačí)
Komplexné ML predikcie (mimo scope)

2. POŽIADAVKY

2.1 Funkčné požiadavky

FR-001: Scraping historických dát

ID	Požiadavka	Priorita
FR-001.1	Scrapovať výsledky pretekkov podľa regiónu	P0
FR-001.2	Scrapovať výsledky podľa závodiská	P0
FR-001.3	Scrapovať výsledky podľa dátumu/rozsahu	P0
FR-001.4	Filtrovať podľa typu (flat/jumps)	P0
FR-001.5	Inkrementálny scraping (len nové dáta)	P1

FR-002: Scraping racecards

ID	Požiadavka	Priorita
FR-002.1	Scrapovať aktuálne závodné karty	P0
FR-002.2	Získať detaily o koňoch a jazdcoch	P0
FR-002.3	Získať Betfair odds (ak dostupné)	P1

FR-003: Export dát

ID	Požiadavka	Priorita
FR-003.1	Export do CSV	P0
FR-003.2	Export do JSON	P0
FR-003.3	Export do gzip komprimovaného formátu	P1
FR-003.4	Konfigurovateľné polia exportu	P1

2.2 Non-funkčné požiadavky

NFR-001: Spoľahlivosť

ID	Požiadavka	Metrika
NFR-001.1	Úspešnosť scrapingu	>95% requestov úspešných
NFR-001.2	Automatické zotavenie z chýb	100% transient errors handled
NFR-001.3	Žiadna strata dát pri páde	Checkpointing každých 100 záznamov

NFR-002: Výkon

ID	Požiadavka	Metrika
NFR-002.1	Rýchlosť scrapingu	Min 1 request/sekundu (bezpečná)
NFR-002.2	Pamäťová efektivita	Max 500MB RAM pre 10K záznamov
NFR-002.3	Concurrent connections	Konfigurovateľné 1-10

NFR-003: Bezpečnosť (Anti-Ban)

ID	Požiadavka	Metrika
NFR-003.1	Rotácia User-Agents	Min 50 rôznych UA
NFR-003.2	Rate limiting	Konfigurovateľné, default 1 req/s
NFR-003.3	Random delays	0.5-2s jitter medzi requestami
NFR-003.4	Session management	Automatická rotácia sessions
NFR-003.5	Proxy support	Voliteľná podpora proxy

NFR-004: Observabilita

ID	Požiadavka	Metrika
NFR-004.1	Structured logging	100% operácií logovaných
NFR-004.2	Log levels	DEBUG/INFO/WARNING/ERROR/CRITICAL
NFR-004.3	Log persistence	Rotované logy, max 100MB
NFR-004.4	Traceable requests	Každý request má unique ID
NFR-004.5	Performance metrics	Čas, success rate, data volume

3. TECHNICKÁ ŠPECIFIKÁCIA

3.1 Logging System

3.1.1 Architektúra

┌─────────────────────────────────────────────────────────────┐
│                     LOGGING PIPELINE                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐   │
│  │   Logger    │────▶│  Processor  │────▶│   Handler   │   │
│  │  (source)   │     │ (enrichment)│     │  (output)   │   │
│  └─────────────┘     └─────────────┘     └─────────────┘   │
│                                                             │
│  Processors:                      Handlers:                 │
│  • add_timestamp                  • Console (colored)       │
│  • add_log_level                  • File (JSON lines)       │
│  • add_request_id                 • File (human readable)   │
│  • add_context                    • Rotating file handler   │
│  • exception_info                                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3.1.2 Log Formát

{
  "timestamp": "2025-12-09T14:32:15.123456Z",
  "level": "INFO",
  "logger": "rpscrape.http_client",
  "request_id": "req_abc123",
  "event": "request_completed",
  "url": "https://www.racingpost.com/...",
  "status_code": 200,
  "duration_ms": 234,
  "retry_count": 0,
  "context": {
    "region": "gb",
    "year": 2024,
    "race_type": "flat"
  }
}

3.1.3 Log Levels

Level	Použitie
DEBUG	Detailné info pre vývoj (selektory, raw data)
INFO	Normálne operácie (request start/end, records saved)
WARNING	Potenciálne problémy (retry, missing data)
ERROR	Chyby ktoré neprekazili operáciu
CRITICAL	Fatálne chyby vyžadujúce ukončenie

3.2 Anti-Ban System

3.2.1 Komponenty

┌─────────────────────────────────────────────────────────────┐
│                    ANTI-BAN SYSTEM                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               Request Pipeline                       │   │
│  │  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐  │   │
│  │  │ Rate │─▶│ UA   │─▶│Header│─▶│Delay │─▶│ Send │  │   │
│  │  │Limit │  │Rotate│  │Inject│  │Jitter│  │      │  │   │
│  │  └──────┘  └──────┘  └──────┘  └──────┘  └──────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Response Pipeline                       │   │
│  │  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐            │   │
│  │  │ Ban  │─▶│Captch│─▶│ Rate │─▶│ Log  │            │   │
│  │  │Detect│  │Detect│  │ Adapt│  │      │            │   │
│  │  └──────┘  └──────┘  └──────┘  └──────┘            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3.2.2 User-Agent Rotation

Pool 50+ reálnych browser User-Agents
Weighted random selection (novšie browsery častejšie)
Konzistentný UA počas session
Platform-appropriate UAs (Windows, Mac, Linux)

3.2.3 Request Headers

STEALTH_HEADERS = {
    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
    'Accept-Language': 'en-GB,en;q=0.9,en-US;q=0.8',
    'Accept-Encoding': 'gzip, deflate, br',
    'Cache-Control': 'no-cache',
    'Pragma': 'no-cache',
    'Sec-Ch-Ua': '"Not_A Brand";v="8", "Chromium";v="120"',
    'Sec-Ch-Ua-Mobile': '?0',
    'Sec-Ch-Ua-Platform': '"Windows"',
    'Sec-Fetch-Dest': 'document',
    'Sec-Fetch-Mode': 'navigate',
    'Sec-Fetch-Site': 'none',
    'Sec-Fetch-User': '?1',
    'Upgrade-Insecure-Requests': '1',
}

3.2.4 Rate Limiting Strategy

Scenár	Delay	Jitter
Normal	1.0s	±0.5s
After 429	30s	±10s
After error	5s	±2s
Burst detected	60s pause	-

3.2.5 Ban Detection

Signál	Akcia
HTTP 403/429	Pause 60s, rotate session
CAPTCHA detected	Log + pause + alert
Empty response	Retry 3x, then skip
Connection reset	Backoff, check IP

3.3 Resilient HTTP Client

3.3.1 Retry Strategy

RETRY_CONFIG = {
    'max_attempts': 5,
    'backoff_base': 2,  # seconds
    'backoff_max': 60,  # seconds
    'backoff_jitter': True,
    'retry_on_status': [500, 502, 503, 504, 520, 521, 522, 523, 524],
    'retry_on_exception': [
        'ConnectionError',
        'Timeout',
        'SSLError',
        'ChunkedEncodingError',
    ]
}

3.3.2 Circuit Breaker

Stav	Podmienka	Akcia
CLOSED	Normal operation	Requesty prechádzajú
OPEN	5 failures in 60s	Všetky requesty blokované
HALF-OPEN	Po 120s v OPEN	Testovací request

3.4 Data Validation (Pydantic)

3.4.1 Modely

class RaceResult(BaseModel):
    race_id: str
    date: date
    course: str
    race_name: str
    distance_furlongs: float = Field(ge=0)
    going: str
    race_class: Optional[int] = Field(None, ge=1, le=7)
    prize_money: Optional[Decimal] = Field(None, ge=0)

    class Config:
        extra = 'ignore'  # Ignoruj neznáme polia

    @validator('distance_furlongs', pre=True)
    def parse_distance(cls, v):
        # Robustná konverzia
        ...

4. IMPLEMENTAČNÝ PLÁN

4.1 Fáza 1: Foundation (Týždeň 1)

4.2 Fáza 2: Core Fixes (Týždeň 2)

4.3 Fáza 3: Enhancement (Týždeň 3)

Pydantic validácia
Vylepšené CLI (progress bars)
Checkpoint/resume funkcionalita
Performance optimalizácia

4.4 Fáza 4: Production Ready (Týždeň 4)

End-to-end testovanie
Dokumentácia
Deployment ready
Monitoring a alerting

5. SUCCESS METRICS

Metrika	Cieľ	Meranie
Scraping success rate	>95%	Úspešné/Celkové requesty
Ban rate	<1%	Ban events/Session
Recovery rate	100%	Auto-recovered/Total errors
Data completeness	>98%	Fields populated/Expected
Mean time to debug	<5 min	Log → Root cause time

6. RIZIKÁ A MITIGÁCIA

Riziko	Pravdepodobnosť	Dopad	Mitigácia
Racing Post zmení HTML	Vysoká	Vysoký	Fallback selektory, alerting
IP ban	Stredná	Vysoký	Rate limiting, proxy support
API rate limits	Stredná	Stredný	Adaptive rate limiting
Data format changes	Stredná	Stredný	Pydantic validation + logging

7. APPENDIX

A. Konfiguračný súbor

[scraping]
rate_limit = 1.0  # requests per second
max_concurrent = 3
timeout = 30
max_retries = 5

[anti_ban]
rotate_user_agent = true
random_delay_min = 0.5
random_delay_max = 2.0
session_lifetime = 300  # seconds

[logging]
level = "INFO"
file = "logs/rpscrape.log"
format = "json"
max_size_mb = 50
backup_count = 5

[export]
format = "csv"
compress = false
output_dir = "data/"

B. CLI Commands

# Základný scraping
rpscrape scrape --region gb --year 2024 --type flat

# S debug logovaním
rpscrape scrape --region gb --year 2024 --log-level DEBUG

# Racecards
rpscrape racecards --date today --region gb

# Resume po páde
rpscrape scrape --resume --checkpoint-file .checkpoint

# Dry run (test bez scrapingu)
rpscrape scrape --region gb --year 2024 --dry-run

Dokument schválený: 2025-12-09 Ďalšia revízia: Po Fáze 1

FilesExpand file tree

PRD.md

Latest commit

History