20 KiB
20 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, delegation
| phase | plan | type | wave | depends_on | files_modified | autonomous | delegation | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 09-finalizacja | 02 | execute | 1 |
|
|
false | off |
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)
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
- **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 dopost_titlejachtu 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.
<acceptance_criteria>
AC-1: Globalny iCal Export feed
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
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
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)
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)
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
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>
Task 1: Globalny iCal Export feed + alias jachtu 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 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.
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)
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).
DO NOT CHANGE
class-availability.php(logika availability stabilna)class-booking.php(CPT booking — nie ruszamy)wp_yacht_availabilityschema (zablokowane)frontend/class-calendar-widget.phpifrontend/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_optionskeys i opcjonalnym yacht meta_yacht_gcal_alias - Brak tłumaczeń .pot w tym planie (Phase 9 osobno)
<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>