# Calendar JSON Fields

Dokument opisuje pola w finalnym merged output:
- `data/calendar/markets/{MARKET}_{YEAR}.json`

To jest warstwa końcowa po:
- normalizacji
- merge źródeł
- feature engineering

## Top-level

Finalny plik marketu ma strukturę:

```json
{
  "market": "CO",
  "year": 2026,
  "events": []
}
```

Pola:
- `market`: kod rynku, np. `CO`, `CH`, `BA`
- `year`: rok kalendarzowy
- `events`: lista finalnych eventów po merge

## Event Identity

Pola identyfikacyjne eventu:
- `event_id`: stabilny identyfikator eventu w merged output
- `market`: kod rynku
- `countryCode`: kod kraju
- `canonical_name`: główna nazwa eventu po merge
- `name_local`: nazwa lokalna, jeśli dostępna
- `name_en`: nazwa angielska, jeśli dostępna
- `name_variants`: wszystkie zebrane warianty nazw po merge

## Dates

- `date_start`: data początku eventu `YYYY-MM-DD`
- `date_end`: data końca eventu `YYYY-MM-DD`
- `duration_days`: liczba dni eventu
- `is_fixed_date`: czy event ma stałą datę w kalendarzu

## Classification

- `event_type`: typ techniczny, np. `holiday`, `observance`
- `event_category`: główna kategoria, np. `public_holiday`, `observance`, `school_break`
- `holiday_subtype`: podtyp święta, jeśli istnieje
- `school_break_type`: podtyp przerwy szkolnej, jeśli istnieje

## Scope

- `scope`: zasięg eventu, np. `national`, `regional`
- `is_nationwide`: czy event obejmuje cały kraj
- `regions`: lista regionów objętych eventem

## Source Metadata

- `descriptions`: opisy zebrane ze źródeł
- `source_count`: liczba źródeł w scalonym evencie
- `sources`: lista surowych źródeł użytych do zbudowania eventu

Każdy wpis w `sources` zawiera:
- `source_name`: nazwa źródła, np. `source_1`, `source_2`, `google_calendar`
- `source_priority`: priorytet źródła
- `raw_name`: nazwa eventu w źródle
- `raw_type`: typ źródła
- `raw_payload`: surowy payload źródłowy

## Normalization Fields

Pola pomocnicze używane przez merge i QA:
- `_normalized_name`: znormalizowana nazwa eventu
- `_name_fingerprint`: uproszczony fingerprint nazwy
- `_canonical_holiday_key`: finalny klucz semantyczny święta lub observance
- `is_day_off_holiday`: czy event jest traktowany jako realny dzień wolny

`_canonical_holiday_key` jest głównym polem semantycznym używanym do:
- merge duplikatów między źródłami
- odróżniania podobnych nazw tego samego dnia
- blokowania over-merge dla różnych świąt

## calendar_features

Pole:

```json
"calendar_features": { ... }
```

Zawiera kontekst kalendarzowy eventu:
- `day_of_week_start`: dzień tygodnia początku eventu
- `day_of_week_end`: dzień tygodnia końca eventu
- `days_until_weekend`: ile dni roboczych zostało do weekendu od startu eventu
- `adjacent_to_weekend`: czy event wypada przy weekendzie lub na weekendzie
- `adjacent_public_holiday_before`: czy dzień przed eventem jest public holiday
- `adjacent_public_holiday_after`: czy dzień po evencie jest public holiday
- `adjacent_off_days_before`: liczba bezpośrednio poprzedzających dni wolnych
- `adjacent_off_days_after`: liczba bezpośrednio następujących dni wolnych
- `bridge_day_potential`: czy układ dat sugeruje bridge / sandwich opportunity
- `long_weekend_potential`: potencjał długiego weekendu

`long_weekend_potential`:
- `none`
- `medium`
- `high`
- `natural`

## time_off_features

Pole:

```json
"time_off_features": { ... }
```

Zawiera interpretację czasu wolnego:
- `daysOffInRow`: liczba kolejnych dni wolnych w oknie eventu
- `workingDaysLost`: liczba dni roboczych objętych samym eventem
- `official_working_days_lost`: liczba oficjalnie utraconych dni roboczych dla realnych day-off holidays
- `bridgePotential`: potencjał bridge w ujęciu operacyjnym
- `bridge_days_used`: ile dni bridge zostało założonych przy budowie okna
- `off_day_pattern`: wzorzec układu wolnych dni
- `travelWindow`: wyliczone okno wyjazdowe związane z eventem

`bridgePotential`:
- `none`
- `medium`
- `high`

`off_day_pattern` może przyjmować np.:
- `none`
- `single_midweek`
- `bridge_candidate`
- `monday_holiday`
- `friday_holiday`
- `weekend_holiday`
- `natural_long_weekend`
- `school_break`

`travelWindow`:
- `from`: początek okna
- `to`: koniec okna
- `type`: typ okna

`travelWindow.type` może przyjmować np.:
- `no_time_off_event`
- `holiday_window`
- `long_weekend_candidate`
- `school_break_peak`

## travel_features

Pole:

```json
"travel_features": { ... }
```

Zawiera interpretację eventu z perspektywy travel demand:
- `travel_segment_tags`: tagi segmentów podróżnych
- `market_coverage`: zasięg geograficzny eventu w uproszczeniu
- `travel_intensity_band`: uproszczona klasa siły wpływu travel
- `vfr_relevance`: znaczenie dla VFR
- `family_travel_relevance`: znaczenie dla ruchu rodzinnego
- `business_travel_impact`: wpływ na business travel
- `leisure_travel_impact`: wpływ na leisure travel
- `travel_relevance_score`: liczbowy score relevance `0-1`

`market_coverage`:
- `nationwide`
- `multi_region`
- `single_region`

`travel_intensity_band`:
- `low`
- `medium`
- `high`
- `peak`

Typowe `travel_segment_tags`:
- `leisure`
- `city_break`
- `short_break`
- `business_negative`
- `family`
- `vfr`
- `homecoming`
- `packages`
- `outbound`
- `school_break`

## travel_product_impact

Pole:

```json
"travel_product_impact": {
  "flights": { ... },
  "holiday_packages": { ... }
}
```

Dla każdego produktu:
- `direction`: kierunek wpływu
- `strength`: siła wpływu
- `drivers`: lista głównych driverów

`direction` może być np.:
- `positive`
- `neutral_to_positive`
- `neutral`
- `mixed`
- `negative`

`strength`:
- `low`
- `medium`
- `high`

## timing_effects

Pole:

```json
"timing_effects": {
  "previous_week": { ... },
  "event_week": { ... },
  "next_week": { ... }
}
```

To jest model wpływu eventu na popyt travel w trzech oknach:
- `previous_week`: tydzień przed eventem
- `event_week`: tydzień, w którym wypada event
- `next_week`: tydzień po evencie

Każde okno zawiera:
- `direction`: kierunek wpływu
- `strength`: siła wpływu
- `effect_types`: lista typów efektów

Przykładowe `effect_types`:
- `planning`
- `pre_holiday_search_lift`
- `booking_lift`
- `vfr_planning`
- `departures_peak`
- `mixed_booking_behavior`
- `holiday_mode`
- `return_travel`
- `post_trip_cooldown`
- `rebound`
- `normalization`

## summary_inputs

Pole:

```json
"summary_inputs": { ... }
```

To jest gotowy, skondensowany kontekst pod przyszły generator summary.

Zawiera:
- `event_identity`
- `time_off`
- `calendar_context`
- `travel_signal`
- `product_impact`
- `timing_effects`
- `llm_summary_ready`

Cel:
- dać downstream summary builderowi mały, stabilny payload
- uniknąć ponownego liczenia feature engineering w promptach lub adapterach LLM

`llm_summary_ready=true` oznacza, że event ma już przygotowaną strukturę pod kolejny etap generacji opisu.

## Notes

Ważne rozróżnienia:
- `workingDaysLost` może być większe niż `official_working_days_lost` dla niektórych kategorii rozszerzanych w analizie czasu wolnego
- `daysOffInRow` liczy całe praktyczne okno wolnych dni, a nie tylko długość samego eventu
- `timing_effects` opisuje wpływ popytowy na travel, nie status prawny święta
- `summary_inputs` nie jest jeszcze finalnym summary tekstowym, tylko kontraktem wejściowym pod generator summary