update

.paul/phases/09-finalizacja/09-02-PLAN.md

@@ -0,0 +1,325 @@
+---
+phase: 09-finalizacja
+plan: 02
+type: execute
+wave: 1
+depends_on: ["09-01"]
+files_modified:
+  - wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-feed.php
+  - wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-import.php
+  - wp-content/plugins/yacht-booking-system/admin/class-admin.php
+  - wp-content/plugins/yacht-booking-system/admin/views/settings.php
+  - wp-content/plugins/yacht-booking-system/includes/class-yacht.php
+  - wp-content/plugins/yacht-booking-system/admin/views/yacht-edit.php
+  - wp-content/plugins/yacht-booking-system/includes/class-installer.php
+autonomous: false
+delegation: off
+---
+
+<objective>
+## Goal
+Wprowadzić dwukierunkową synchronizację z **jednym wspólnym Google Calendar** (przez iCal feed) z rozróżnieniem rezerwacji per jacht po prefiksie w tytule eventu (`"{nazwa_jachtu} - {tekst}"`). Frontend kalendarz dla danego jachtu pokazuje tylko jego rezerwacje.
+
+## Purpose
+Klient (właściciel wypożyczalni) chce zarządzać rezerwacjami wszystkich jachtów w jednym Google Calendar — jednym widokiem floty. Tworzy ręcznie eventy w GCal (np. blokady, rezerwacje telefoniczne) używając prefiksu z nazwą jachtu, a strona automatycznie przypisuje je do właściwego jachtu. Jednocześnie rezerwacje złożone przez frontend trafiają z powrotem do tego samego kalendarza w spójnym formacie.
+
+## Output
+- Globalny iCal Export feed (jeden URL z tokenem) — zawiera rezerwacje wszystkich jachtów z prefiksem nazwy jachtu w SUMMARY
+- Globalny iCal Import URL — parser dopasowuje prefiks do jachtu, importuje tylko rozpoznane eventy
+- Settings page — pola dla globalnego import URL i wyświetlanie globalnego export URL
+- Pole `_yacht_gcal_alias` (opcjonalny alias dla skróconej nazwy w GCal)
+- Per-yacht feedy iCal pozostają sprawne (kompatybilność wsteczna)
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+@.paul/codebase/architecture.md
+
+## Source Files
+@wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-feed.php
+@wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-import.php
+@wp-content/plugins/yacht-booking-system/admin/class-admin.php
+@wp-content/plugins/yacht-booking-system/includes/class-yacht.php
+@wp-content/plugins/yacht-booking-system/includes/class-settings.php
+
+<clarifications>
+- **Mechanizm** — iCal feed (publiczny URL Google Calendar) zamiast OAuth API. Powód: klient nie chce przechodzić przez OAuth, woli dodać URL i mieć synchronizację automatyczną.
+  → Odpowiedź: dwukierunkowo przez iCal — import z GCal feedu + export własnego feedu (admin subskrybuje go w GCal).
+
+- **Identyfikacja jachtu** — po prefiksie w tytule eventu, separator `" - "`. Przykład: `"Maja - Kowalski 5 osób"`, `"Kubuś - blokada serwisowa"`.
+  → Odpowiedź: parser wyciąga tekst przed pierwszym `" - "`, dopasowuje case-insensitive do `post_title` jachtu lub `_yacht_gcal_alias` (jeśli ustawiony — ma priorytet).
+
+- **Eventy bez rozpoznanego jachtu** — ignorowane.
+  → Odpowiedź: jeśli prefiks nie pasuje do żadnego jachtu (lub brak separatora `" - "`), event pomijany w imporcie. Brak fallbacku na "blokuj wszystkie" — klient nie chce niespodzianek.
+
+- **Push do GCal** — przez ten sam globalny feed iCal (admin subskrybuje feed pluginu w GCal).
+  → Odpowiedź: rezerwacje ze strony pojawiają się w GCal po następnej refresh subskrypcji (Google odświeża iCal subscription co kilka godzin — limit Google'a, nie pluginu).
+
+- **Frontend filtrowanie** — kalendarz per jacht pokazuje tylko eventy danego jachtu.
+  → Odpowiedź: bez zmian w widgecie — działa już teraz przez `_booking_yacht_id`. Wystarczy że import poprawnie przypisze yacht_id.
+</clarifications>
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Globalny iCal Export feed
+```gherkin
+Given admin ma kilka rezerwacji w bazie dla różnych jachtów (np. "Maja", "Kubuś")
+When admin otwiera URL `/yacht-ical-global/{token}.ics`
+Then odpowiedź ma Content-Type `text/calendar`
+And feed zawiera VEVENT dla każdej niezanullowanej rezerwacji wszystkich jachtów
+And SUMMARY każdego eventu ma format `"{nazwa_jachtu} - {imię_klienta}"` (lub z prefiksem `[Oczekująca]` gdy status pending)
+And UID jest stabilny (`booking-{id}@{domain}`) — kolejne fetche zwracają ten sam UID
+```
+
+## AC-2: Globalny iCal Import — dopasowanie po prefiksie
+```gherkin
+Given globalny iCal Import URL jest ustawiony w Settings
+And kalendarz Google zawiera event "Maja - Test rezerwacja" (jacht "Maja" istnieje w bazie)
+And kalendarz Google zawiera event "Nieznany - cokolwiek" (brak takiego jachtu)
+And kalendarz Google zawiera event "Brak separatora" (bez " - ")
+When uruchamiany jest cron `yacht_booking_ical_import` (lub manualny przycisk)
+Then plugin tworzy/aktualizuje booking dla jachtu "Maja" z source `ical_import_global`
+And blokuje dostępność `wp_yacht_availability` tylko dla yacht_id jachtu "Maja"
+And event "Nieznany" jest pominięty (logowane jako info, brak booking)
+And event "Brak separatora" jest pominięty
+And kolejny przebieg (nawet bez zmian w GCal) nie tworzy duplikatów (idempotencja po UID)
+```
+
+## AC-3: Globalny Import — czyszczenie usuniętych eventów
+```gherkin
+Given event "Maja - Foo" został zaimportowany przy poprzednim cron'ie
+When admin usuwa go z Google Calendar
+And uruchamia się kolejny cron import
+Then powiązany booking (z source `ical_import_global` i tym UID) jest usuwany
+And `Availability::clear_booking_availability()` zwalnia daty
+```
+
+## AC-4: Alias jachtu (opcjonalny)
+```gherkin
+Given jacht ma `post_title="Marina Maja Sailing 35"` i `_yacht_gcal_alias="Maja"`
+And event w GCal ma SUMMARY "Maja - Klient X"
+When uruchamia się import
+Then plugin dopasowuje event do tego jachtu po aliasie
+And tworzy booking z `_booking_yacht_id` = ID tego jachtu
+```
+
+## AC-5: Frontend filtrowanie (regresja)
+```gherkin
+Given booking dla jachtu "Maja" zaimportowany przez globalny iCal
+When klient otwiera stronę z widgetem `[yacht_calendar yacht_id=ID_MAJA]`
+Then kalendarz pokazuje datę rezerwacji jako zablokowaną
+And widget jachtu "Kubuś" NIE pokazuje tej daty jako zablokowanej
+```
+
+## AC-6: Settings UI
+```gherkin
+Given admin otwiera Settings → zakładka Google Calendar / iCal
+When widzi sekcję "Globalna synchronizacja iCal"
+Then widzi pole "iCal Import URL" (input type=url) — globalny URL kalendarza Google
+And widzi pole tylko-do-odczytu "iCal Export URL" z linkiem `/yacht-ical-global/{token}.ics` i przyciskiem "Kopiuj"
+And widzi przycisk "Wygeneruj nowy token" (regeneruje token, unieważniając poprzedni URL)
+And widzi przycisk "Importuj teraz" (manual trigger run_global_import)
+And w yacht-edit jest nowe pole "Alias dla Google Calendar" (placeholder: nazwa jachtu) — opcjonalne
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Globalny iCal Export feed + alias jachtu</name>
+  <files>
+    wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-feed.php,
+    wp-content/plugins/yacht-booking-system/includes/class-yacht.php,
+    wp-content/plugins/yacht-booking-system/includes/class-installer.php
+  </files>
+  <action>
+    1. W `class-ical-feed.php` dodaj nową ścieżkę feed:
+       - rewrite rule `^yacht-ical-global/([a-zA-Z0-9]+)\.ics$` → `index.php?yacht_ical_global=1&yacht_ical_token=$matches[1]`
+       - query var `yacht_ical_global`
+       - handler `handle_global_feed_request()` weryfikuje token przez `hash_equals` względem opcji `yacht_booking_global_ical_token`
+       - metoda `output_global_ics()`: pobiera WSZYSTKIE bookingi (nie filtrowane po yacht), iteruje, dla każdego ustala SUMMARY = `"{nazwa_jachtu} - {imię_klienta}"` (analogicznie do istniejącego `output_ics`, ale z prefiksem nazwy jachtu z `Yacht::get_post_title( yacht_id )` zamiast tylko klienta)
+       - skip bookingi ze statusem `cancelled` oraz z source `ical_import_global` (nie wysyłaj z powrotem do Google tego co stamtąd przyszło — anti-loop)
+       - UID format: `booking-{id}@{domain}` (taki sam jak per-yacht — zachować stabilność)
+       - X-WR-CALNAME: `"Wszystkie jachty - " . get_bloginfo('name')`
+    2. Helper `get_global_feed_token()` — generuje/zwraca token z opcji, `regenerate_global_token()` — nadpisuje token.
+    3. Helper `get_global_feed_url()` — zwraca pełny URL.
+    4. W `class-yacht.php` dodaj akcesory:
+       - `get_gcal_alias( $yacht_id )` → `get_post_meta( $yacht_id, '_yacht_gcal_alias', true )`
+       - `update_gcal_alias( $yacht_id, $alias )` → sanitize_text_field + update_post_meta
+    5. W `class-installer.php` (jeśli wersja schematu się ewoluuje) dodaj domyślne opcje:
+       - `add_option( 'yacht_booking_global_ical_import_url', '' )`
+       - `add_option( 'yacht_booking_global_ical_token', '' )` (token generowany lazy przy pierwszym fetch URL)
+       - flush_rewrite_rules przy aktywacji (rewrite rule).
+
+    Avoid: nie modyfikuj istniejących per-yacht feedów — działają jako fallback i są używane przez OTA/iCal subscribers innych systemów.
+  </action>
+  <verify>
+    - `php -l class-ical-feed.php` (syntax OK)
+    - W przeglądarce: po zapisie pluginu i flush rewrite, URL `/yacht-ical-global/{token}.ics` zwraca .ics z eventami wszystkich jachtów, każdy z prefiksem nazwy jachtu
+    - `curl /yacht-ical-global/{token}.ics | grep "SUMMARY"` zawiera np. `SUMMARY:Maja - Kowalski`
+    - URL z błędnym tokenem zwraca 403
+  </verify>
+  <done>AC-1, AC-4 (część dot. aliasu — akcesory) zaspokojone</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Globalny iCal Import + parser prefiksu</name>
+  <files>
+    wp-content/plugins/yacht-booking-system/integrations/ical/class-ical-import.php
+  </files>
+  <action>
+    1. Dodaj stałą `const GLOBAL_IMPORT_SOURCE = 'ical_import_global';` (osobna od per-yacht `IMPORT_SOURCE = 'ical_import'`).
+    2. Nowa metoda statyczna `run_global_import()`:
+       - Pobiera URL z `get_option( 'yacht_booking_global_ical_import_url' )`
+       - Jeśli pusty — return false
+       - `wp_remote_get` z timeout 30s
+       - parse_ics (re-use istniejącej metody, jest prywatna — wystawić jako protected lub wynieść do helpera; preferowane: zmienić visibility na `protected` lub utworzyć publiczną wrapping)
+       - Pre-fetch: lista jachtów + mapa `lowercase_name_or_alias → yacht_id`. Budowa: dla każdego jachtu klucz = `_yacht_gcal_alias` (jeśli != '') albo `post_title`, wszystko `mb_strtolower` + trim.
+       - Pre-fetch: `existing_global_map` — bookingi z source `GLOBAL_IMPORT_SOURCE`, mapa `uid → booking_id` (analogicznie do `get_existing_import_map` ale bez filtrowania po yacht).
+       - Iteracja po eventach:
+         a. Skip jeśli brak uid/start/end lub event w przeszłości (`strtotime($event['end']) < time()`)
+         b. Parse SUMMARY: `$pos = mb_strpos( $summary, ' - ' )`. Jeśli `$pos === false` → log "skip: no separator", continue.
+         c. `$prefix = mb_strtolower( trim( mb_substr( $summary, 0, $pos ) ) )`
+         d. Lookup w mapie. Jeśli brak → log "skip: yacht not found for prefix '{prefix}'", continue.
+         e. Wywołaj `upsert_global_booking( $yacht_id, $event, $existing_id )` (nowa metoda — jak `upsert_booking` ale z `_booking_source = GLOBAL_IMPORT_SOURCE`, `_booking_customer_name = "Google Calendar (import)"`, post_title `"GCal: {summary}"`).
+         f. Dodaj uid do `$seen_uids`.
+       - Po pętli: stale cleanup — dla każdego `$uid => $booking_id` w `$existing_global_map` którego nie ma w `$seen_uids` → `Availability::clear_booking_availability($booking_id)` + `wp_delete_post($booking_id, true)`.
+       - `update_option( 'yacht_booking_global_ical_last_import', current_time('mysql') )`.
+       - return true.
+    3. Hook cron: w `register()` dodać `add_action( 'yacht_booking_ical_global_import', array( __CLASS__, 'run_global_import' ) )` i w `setup_cron()` zarejestruj hourly.
+    4. Hook do uruchomienia obu importów (per-yacht + global) z jednego cron tick'a — nie zmieniać istniejącego, dodać osobny `wp_schedule_event` dla `yacht_booking_ical_global_import`.
+
+    Avoid:
+    - Nie usuwać per-yacht importu (kompatybilność)
+    - Nie używać sztywno `strpos` po bajtach — używać `mb_*` (polskie znaki w nazwach jachtów: "Kubuś", "Maja Słoneczna")
+    - Nie matchować po fragmentach — tylko exact equality po lower-case (inaczej "Maja" pasuje do "Maja Słoneczna" jednocześnie)
+  </action>
+  <verify>
+    - `php -l class-ical-import.php`
+    - Test ręczny: stworzyć w Google Calendar event "Maja - test", subskrybować feed Google iCal URL w settings, kliknąć "Importuj teraz", sprawdzić że w admin → Bookings pojawia się booking przypisany do jachtu "Maja"
+    - Event "FooBar - test" (brak takiego jachtu) — nie tworzy bookingu, w error log linia "skip: yacht not found"
+    - Event "BezSeparatora" — nie tworzy bookingu
+    - Drugi cron tick — brak duplikatu
+    - Usunięcie eventu w GCal + cron → booking zniknął, daty zwolnione w `wp_yacht_availability`
+  </verify>
+  <done>AC-2, AC-3, AC-4 (matching po aliasie) zaspokojone</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Settings UI + yacht-edit alias + admin actions</name>
+  <files>
+    wp-content/plugins/yacht-booking-system/admin/class-admin.php,
+    wp-content/plugins/yacht-booking-system/admin/views/settings.php,
+    wp-content/plugins/yacht-booking-system/admin/views/yacht-edit.php
+  </files>
+  <action>
+    1. `settings.php` — dodaj sekcję "Globalna synchronizacja iCal":
+       - Pole `yacht_booking_global_ical_import_url` (input type=url, full width)
+       - Read-only display: globalny export URL (`ICal_Feed::get_global_feed_url()`) — input readonly + przycisk "Kopiuj" (JS clipboard)
+       - Przycisk "Wygeneruj nowy token" (form POST z nonce + action `regenerate_global_ical_token`)
+       - Przycisk "Importuj teraz" (form POST z nonce + action `run_global_ical_import`)
+       - Wyświetl `yacht_booking_global_ical_last_import` ("Ostatni import: ...")
+       - Krótka instrukcja: "Skopiuj Export URL i dodaj jako 'Z URL-a' w Google Calendar (Inne kalendarze → Z URL). Eventy w Google nazywaj wg wzorca: 'Nazwa jachtu - opis'. Wklej iCal URL kalendarza Google poniżej."
+    2. `class-admin.php` — w `process_settings_save()` (lub equivalent) zapisz nowe pole.
+    3. `class-admin.php` — `process_booking_actions()` (lub nowy `process_ical_actions()`):
+       - obsłuż `regenerate_global_ical_token` → `ICal_Feed::regenerate_global_token()` + `?notice=token_regenerated` redirect
+       - obsłuż `run_global_ical_import` → `ICal_Import::run_global_import()` + `?notice=import_done` redirect
+    4. `yacht-edit.php` — dodaj wiersz tabeli "Alias dla Google Calendar":
+       - input text `yacht_gcal_alias`, value = `Yacht::get_gcal_alias( $yacht_id )`
+       - Description: "Opcjonalny krótki alias używany w tytule eventu Google Calendar (np. 'Maja' zamiast 'Marina Maja Sailing 35'). Jeśli puste — używana jest pełna nazwa jachtu."
+    5. `class-admin.php::process_yacht_save()` — zapisz `yacht_gcal_alias` przez `Yacht::update_gcal_alias()`.
+    6. Dodaj admin notices dla token_regenerated i import_done.
+
+    Avoid:
+    - Nie usuwaj istniejących pól per-yacht ("Google Calendar ID" i "iCal Import URL") — out of scope. Klient zdecyduje w kolejnym planie czy je sprzątać.
+    - Nie dotykaj OAuth UI (sekcja Google Calendar OAuth zostaje bez zmian).
+  </action>
+  <verify>
+    - `php -l` na każdym zmienionym pliku
+    - W panelu admin → Settings: nowa sekcja jest widoczna, zapis URL działa, "Wygeneruj token" zmienia URL, "Importuj teraz" wywołuje import (sprawdzalne w error log lub bookingach)
+    - W yacht-edit: pole alias zapisuje się i odczytuje
+    - Token w URL ma >=20 znaków, zmiana tokenu unieważnia stary URL (403)
+  </verify>
+  <done>AC-6 zaspokojone, AC-4 (UI dla aliasu) zaspokojone</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+    Dwukierunkowa synchronizacja iCal z jednym wspólnym Google Calendar:
+    - Globalny export feed (admin subskrybuje w GCal)
+    - Globalny import URL (plugin pobiera kalendarz Google)
+    - Identyfikacja jachtu po prefiksie "Nazwa - opis" w tytule eventu
+    - Frontend per-jacht pokazuje tylko swoje eventy
+  </what-built>
+  <how-to-verify>
+    1. Settings → skopiuj Export URL.
+    2. W Google Calendar → "Inne kalendarze" → "Z URL-a" → wklej Export URL → potwierdź że pojawiają się rezerwacje wszystkich jachtów z prefiksem nazwy.
+    3. W Google Calendar (głównym admina) utwórz event ręczny: tytuł "Maja - Test ręcznie", data za tydzień.
+    4. Skopiuj URL iCal swojego głównego kalendarza Google (Ustawienia kalendarza → Tajny adres w formacie iCal).
+    5. Wklej do Settings pluginu → "iCal Import URL".
+    6. Kliknij "Importuj teraz".
+    7. Sprawdź: WP Admin → Rezerwacje → pojawia się booking "GCal: Maja - Test ręcznie" przypisany do jachtu "Maja".
+    8. Otwórz frontend kalendarz jachtu Maja — data zablokowana. Otwórz kalendarz innego jachtu — data wolna.
+    9. Usuń event w Google → uruchom "Importuj teraz" ponownie → booking znika.
+    10. Stwórz w GCal "Nieznany - test" → import → brak bookingu (sprawdź WP error log: "skip: yacht not found").
+  </how-to-verify>
+  <resume-signal>Wpisz "approved" gdy wszystkie 10 punktów weryfikacji przejdzie, lub opisz problemy do poprawy</resume-signal>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `class-availability.php` (logika availability stabilna)
+- `class-booking.php` (CPT booking — nie ruszamy)
+- `wp_yacht_availability` schema (zablokowane)
+- `frontend/class-calendar-widget.php` i `frontend/class-shortcode.php` (widget renderingu — działa już per-yacht)
+- `class-rest-controller.php` (REST endpointy — bez zmian)
+- OAuth integration (`class-oauth-handler.php`, `class-gcal-service.php`, `class-sync-controller.php`) — out of scope tego planu, push przez OAuth zostaje na razie jak jest (drugi mechanizm; klient użyje iCal a OAuth zignoruje, lub w kolejnym planie wyłączymy)
+- Per-yacht iCal feed (`output_ics`) i per-yacht import (`run_import` + `import_for_yacht`) — pozostają funkcjonalne dla kompatybilności wstecznej
+
+## SCOPE LIMITS
+- Plan NIE usuwa pól per-yacht ("Google Calendar ID", "iCal Import URL") z yacht-edit — to decyzja na osobny plan po pozytywnej weryfikacji nowej globalnej synchronizacji
+- Plan NIE wyłącza OAuth push do GCal — drugi (równoległy) mechanizm; jeśli klient nie połączy OAuth, nie jest aktywny
+- Brak nowych zależności (PHP libs, npm, CDN)
+- Brak zmian w bazie poza dodaniem `wp_options` keys i opcjonalnym yacht meta `_yacht_gcal_alias`
+- Brak tłumaczeń .pot w tym planie (Phase 9 osobno)
+
+</boundaries>
+
+<verification>
+Przed deklaracją ukończenia planu:
+- [ ] `php -l` na wszystkich zmodyfikowanych plikach przechodzi
+- [ ] Globalny export URL zwraca poprawny .ics z prefiksami nazw jachtów
+- [ ] Globalny import URL parsuje eventy z GCal i przypisuje do jachtów po prefiksie
+- [ ] Eventy bez separatora lub bez dopasowanego jachtu są ignorowane (logowane)
+- [ ] Idempotencja: wielokrotne uruchomienie importu nie tworzy duplikatów
+- [ ] Stale cleanup: usunięcie eventu w GCal + import → booking znika
+- [ ] Frontend kalendarz per-jacht pokazuje tylko swoje rezerwacje (regresja)
+- [ ] Per-yacht feedy iCal nadal działają (nie zostały zepsute)
+- [ ] Settings UI: zapis URL, regeneracja tokenu, manual import, alias jachtu działają
+- [ ] Wszystkie acceptance criteria spełnione
+- [ ] Checkpoint human-verify zaakceptowany przez klienta
+</verification>
+
+<success_criteria>
+- Klient może zarządzać rezerwacjami całej floty w jednym Google Calendar
+- Eventy ręczne w GCal z prefiksem "Nazwa jachtu - ..." automatycznie pojawiają się jako blokady na frontendzie tego jachtu
+- Rezerwacje ze strony pojawiają się w GCal admina (po refresh subskrypcji Google)
+- Każdy frontend kalendarz pokazuje tylko swoje rezerwacje
+- Zachowana kompatybilność wsteczna (per-yacht feedy + OAuth push nadal działają)
+</success_criteria>
+
+<output>
+Po ukończeniu utwórz `.paul/phases/09-finalizacja/09-02-SUMMARY.md` zawierający:
+- Co zbudowano (export feed, import, settings UI, alias)
+- Decyzje (separator " - ", lookup case-insensitive po post_title/alias, ignore unmatched)
+- Otwarte pytania na kolejny plan (czy usuwać pola per-yacht? czy wyłączać OAuth push?)
+- Ścieżkę testową odtworzeniową
+</output>