carei.pagedev.pl/.paul/phases/01-reservation-form-plugin/01-01-PLAN.md

---
phase: 01-reservation-form-plugin
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - wp-content/plugins/carei-reservation/carei-reservation.php
  - wp-content/plugins/carei-reservation/includes/class-softra-api.php
  - wp-content/plugins/carei-reservation/includes/class-rest-proxy.php
  - wp-content/plugins/carei-reservation/includes/class-elementor-widget.php
autonomous: true
---

<objective>
## Goal
Utworzyć plugin WordPress `carei-reservation` z:
1. Klasą proxy do Softra Rent API (autoryzacja JWT + cache tokenu + endpointy floty)
2. WP REST API endpoints jako proxy (frontend → WP → Softra)
3. Zarejestrowanym widgetem Elementor (shell z przyciskiem triggerującym modal)

## Purpose
Backend i szkielet pluginu to fundament — bez tego nie ma formularza. API proxy chroni credentials (nigdy nie wystawiane na frontend) i zapewnia cache tokenu JWT.

## Output
Nowy plugin `wp-content/plugins/carei-reservation/` z 4 plikami PHP, gotowy do aktywacji.
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md

## Source Files
@.env (credentials Softra API)
@docs/rent-api-01-autoryzacja-i-flota.md (endpointy: auth, branches, car classes, models, prices)
@docs/rent-api-02-klienci-i-konta.md (customer/add, agreement/def/list)
@docs/rent-api-03-rezerwacje-i-platnosci.md (makebooking, confirm, pricingSummary)
@docs/figma-formularz/README.md (specyfikacja UI)
@wp-content/plugins/elementor-addon/elementor-addon.php (wzorzec rejestracji widgetów)
</context>

<acceptance_criteria>

## AC-1: Plugin aktywuje się bez błędów
```gherkin
Given plugin carei-reservation jest w wp-content/plugins/
When administrator aktywuje plugin w panelu WP
Then plugin ładuje się bez PHP errors/warnings
And widget "Carei Reservation" pojawia się w panelu Elementor
```

## AC-2: API Proxy — autoryzacja i cache tokenu
```gherkin
Given credentials Softra API są w .env
When proxy wykonuje pierwsze żądanie do Softra
Then pobiera token JWT przez POST /account/auth
And cachuje token w WP transient na 50 minut (token ważny 60min)
And kolejne żądania używają cached tokenu
```

## AC-3: REST API proxy zwraca dane oddziałów
```gherkin
Given token JWT jest aktywny
When frontend wywołuje GET /wp-json/carei/v1/branches
Then proxy zwraca listę oddziałów z Softra /branch/list
And odpowiedź zawiera name, description, city, street
```

## AC-4: REST API proxy zwraca klasy pojazdów i cennik
```gherkin
Given token JWT jest aktywny
When frontend wywołuje POST /wp-json/carei/v1/car-classes z dateFrom, dateTo, branchName
Then proxy zwraca listę klas z Softra /car/class/list
When frontend wywołuje POST /wp-json/carei/v1/pricelist z category, dateFrom, dateTo, pickUpLocation
Then proxy zwraca cennik z additionalItems z Softra /pricelist/list
```

## AC-5: Widget Elementor renderuje przycisk-trigger
```gherkin
Given widget "Carei Reservation" jest dodany na stronę w Elementorze
When strona jest wyświetlana na froncie
Then widoczny jest przycisk "Złóż zapytanie o rezerwację" (stylowany wg Figmy)
And kliknięcie przycisku otwiera pusty modal (placeholder na krok 2 — Form UI)
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Główny plik pluginu + klasa Softra API</name>
  <files>wp-content/plugins/carei-reservation/carei-reservation.php, wp-content/plugins/carei-reservation/includes/class-softra-api.php</files>
  <action>
    **carei-reservation.php:**
    - Plugin header (Plugin Name: Carei Reservation, Version: 1.0.0)
    - Załaduj .env z ABSPATH (parsuj ręcznie, format: `key: value` — NIE `KEY=value`)
    - Require includes/*.php
    - Hook `plugins_loaded` → inicjalizacja
    - Hook `elementor/widgets/register` → rejestracja widgetu

    **class-softra-api.php:**
    - Klasa `Carei_Softra_API` (singleton)
    - Constructor: przyjmuje url, username, password z .env
    - `get_token()`: sprawdza WP transient `carei_softra_token`, jeśli brak → POST /account/auth, cache na 50 min
    - `request($method, $endpoint, $body = null)`: generyczna metoda z wp_remote_request, Authorization Bearer header, JSON body
    - Metody publiczne:
      - `get_branches()` → GET /branch/list
      - `get_car_classes($dateFrom, $dateTo, $branchName)` → POST /car/class/list
      - `get_car_models($dateFrom, $dateTo, $branchName, $category)` → POST /car/model/list?includeBrandDetails=true
      - `get_pricelist($category, $dateFrom, $dateTo, $pickUpLocation, $lang='pl', $currency='PLN')` → POST /pricelist/list
      - `get_pricing_summary($params)` → POST /rent/princingSummary
      - `add_customer($data)` → POST /customer/add
      - `make_booking($data)` → POST /rent/makebooking
      - `confirm_booking($reservationId)` → POST /rent/confirm
      - `get_agreements()` → GET /agreement/def/list
    - Error handling: zwracaj WP_Error przy błędach HTTP lub pustym tokenie
  </action>
  <verify>
    Sprawdź: `php -l wp-content/plugins/carei-reservation/carei-reservation.php` i `php -l wp-content/plugins/carei-reservation/includes/class-softra-api.php` — brak syntax errors.
  </verify>
  <done>AC-1 częściowo (plugin ładuje się), AC-2 (autoryzacja + cache)</done>
</task>

<task type="auto">
  <name>Task 2: WP REST API proxy endpoints</name>
  <files>wp-content/plugins/carei-reservation/includes/class-rest-proxy.php</files>
  <action>
    **class-rest-proxy.php:**
    - Klasa `Carei_REST_Proxy`
    - Hook `rest_api_init` → rejestracja routes w namespace `carei/v1`
    - Endpoints:
      1. `GET /branches` → `Carei_Softra_API::get_branches()`
      2. `POST /car-classes` (params: dateFrom, dateTo, branchName) → `get_car_classes()`
      3. `POST /car-models` (params: dateFrom, dateTo, branchName, category) → `get_car_models()`
      4. `POST /pricelist` (params: category, dateFrom, dateTo, pickUpLocation) → `get_pricelist()`
      5. `POST /pricing-summary` (params: full booking params) → `get_pricing_summary()`
      6. `POST /customer` (params: customer data) → `add_customer()`
      7. `POST /booking` (params: booking data) → `make_booking()`
      8. `POST /booking/confirm` (params: reservationId) → `confirm_booking()`
      9. `GET /agreements` → `get_agreements()`
    - Permission callback: `__return_true` dla GET, nonce check dla POST (wp_rest nonce)
    - Sanitization: `sanitize_text_field` na wszystkich string params
    - Odpowiedź: `new WP_REST_Response($data, 200)` lub `WP_Error`
  </action>
  <verify>
    `php -l wp-content/plugins/carei-reservation/includes/class-rest-proxy.php` — brak syntax errors.
  </verify>
  <done>AC-3 (branches endpoint), AC-4 (car-classes + pricelist endpoints)</done>
</task>

<task type="auto">
  <name>Task 3: Elementor Widget shell z przyciskiem-triggerem</name>
  <files>wp-content/plugins/carei-reservation/includes/class-elementor-widget.php</files>
  <action>
    **class-elementor-widget.php:**
    - Klasa `Carei_Reservation_Widget extends \Elementor\Widget_Base`
    - `get_name()`: 'carei-reservation'
    - `get_title()`: 'Carei Reservation'
    - `get_icon()`: 'eicon-form-horizontal'
    - `get_categories()`: ['general']
    - `get_style_depends()`: ['carei-reservation-css'] (placeholder)
    - `get_script_depends()`: ['carei-reservation-js'] (placeholder)
    - `register_controls()`:
      - Section: button_content → kontrolka tekstu przycisku (default: "Złóż zapytanie o rezerwację")
    - `render()`:
      - Przycisk HTML z klasą `carei-reservation-trigger`
      - Inline style: czerwony (#FF0000) background, biały tekst, Albert Sans font, border-radius 8px
      - Ikona strzałki (SVG inline) przed tekstem
      - Pusty div `<div id="carei-reservation-modal"></div>` jako mount point dla modala
      - Inline `<script>` z eventem click na trigger → modal placeholder (console.log na razie)
    - Enqueue placeholder CSS/JS w `wp_enqueue_scripts` (pliki puste, zostaną wypełnione w Phase 2)
  </action>
  <verify>
    `php -l wp-content/plugins/carei-reservation/includes/class-elementor-widget.php` — brak syntax errors.
  </verify>
  <done>AC-5 (widget z przyciskiem-trigger i pustym modalem)</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- wp-content/plugins/elementor-addon/* (istniejący plugin — nie modyfikuj)
- wp-content/themes/hello-elementor/* (theme bez zmian)
- .env (tylko odczyt, nigdy nie commituj)
- docs/* (dokumentacja — read only)

## SCOPE LIMITS
- Ten plan NIE buduje UI formularza (to Phase 2)
- Brak frontendu modal/form — tylko pusty placeholder div i console.log
- Brak walidacji formularza — tylko sanitization parametrów REST
- Nie dodawaj zależności composer/npm

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `php -l` na wszystkich 4 plikach PHP — brak błędów składni
- [ ] Plugin structure: carei-reservation.php + includes/ z 3 klasami
- [ ] .env jest parsowany poprawnie (format `key: value`)
- [ ] Softra API class ma get_token() z transient cache
- [ ] REST routes zarejestrowane w namespace carei/v1
- [ ] Widget renderuje przycisk z odpowiednim stylem
- [ ] Credentials NIE są exposowane na frontend
</verification>

<success_criteria>
- Wszystkie 3 taski wykonane
- Brak PHP syntax errors
- Plugin gotowy do aktywacji w WP
- REST API proxy gotowe do konsumpcji przez frontend (Phase 2)
</success_criteria>

<output>
After completion, create `.paul/phases/01-reservation-form-plugin/01-01-SUMMARY.md`
</output>