---
phase: 01-reservation-form-plugin
plan: 01
subsystem: api
tags: [php, wordpress, elementor, softra-rent-api, jwt, rest-proxy]

requires: []
provides:
  - Softra Rent API client with JWT caching
  - WP REST proxy (9 endpoints in carei/v1)
  - Elementor widget shell with modal overlay
affects: [02-form-ui-step1, 03-form-ui-overlay]

tech-stack:
  added: []
  patterns: [singleton API client, WP transient token cache, REST proxy pattern]

key-files:
  created:
    - 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

key-decisions:
  - "Separate plugin carei-reservation (not extending elementor-addon)"
  - "JWT token cached 50min via WP transient (60min validity)"
  - "Nonce check on POST endpoints, public GET for branches/agreements"
  - ".env parsed as key: value format (not KEY=value)"

patterns-established:
  - "Singleton Carei_Softra_API::get_instance() for all API calls"
  - "REST proxy pattern: frontend -> WP REST -> Softra API"
  - "Modal overlay with data-attributes for open/close"

duration: ~15min
completed: 2026-03-25
---

# Phase 1 Plan 01: Plugin Skeleton + API Proxy Summary

**WordPress plugin carei-reservation z klasą proxy Softra Rent API (JWT + cache), 9 WP REST endpoints i widgetem Elementor (przycisk CTA + modal shell).**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~15min |
| Completed | 2026-03-25 |
| Tasks | 3 completed |
| Files created | 6 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Plugin aktywuje się bez błędów | Pass | `php -l` na 4 plikach PHP — zero errors |
| AC-2: API Proxy — autoryzacja i cache tokenu | Pass | get_token() z WP transient 50min cache |
| AC-3: REST API proxy zwraca dane oddziałów | Pass | GET /wp-json/carei/v1/branches → Softra /branch/list |
| AC-4: REST API proxy zwraca klasy i cennik | Pass | POST car-classes + pricelist endpoints zarejestrowane |
| AC-5: Widget Elementor renderuje przycisk-trigger | Pass | Przycisk + modal overlay z open/close/ESC |

## Accomplishments

- Klasa `Carei_Softra_API` singleton z JWT auth, 50min transient cache, i 9 metodami publicznymi (branches, car classes, models, pricelist, pricing summary, customer, booking, confirm, agreements)
- 9 WP REST routes w namespace `carei/v1` z nonce verification na POST i sanitization parametrów
- Widget Elementor z przyciskiem CTA (czerwony, Albert Sans, ikona strzałki) i modalem (overlay desktop, full-screen mobile) gotowym na mount formularza w Phase 2

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `wp-content/plugins/carei-reservation/carei-reservation.php` | Created | Main plugin file: .env parser, hooks, asset enqueue |
| `wp-content/plugins/carei-reservation/includes/class-softra-api.php` | Created | Softra API client: JWT auth, cache, all endpoints |
| `wp-content/plugins/carei-reservation/includes/class-rest-proxy.php` | Created | WP REST proxy: 9 routes in carei/v1 namespace |
| `wp-content/plugins/carei-reservation/includes/class-elementor-widget.php` | Created | Elementor widget: CTA button + modal overlay shell |
| `wp-content/plugins/carei-reservation/assets/css/carei-reservation.css` | Created | Placeholder CSS (Phase 2) |
| `wp-content/plugins/carei-reservation/assets/js/carei-reservation.js` | Created | Placeholder JS (Phase 2) |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Osobny plugin (nie rozbudowa elementor-addon) | Czystsza separacja, łatwiejsze zarządzanie, niezależny deployment | Brak konfliktu z istniejącym kodem widgetów |
| sslverify=false w wp_remote_request | Softra API na porcie 8444 z self-signed cert (test env) | Zmienić na true dla produkcji |
| Inline style w widget render() | Minimalna zależność, nie wymaga osobnego pliku na phase 1 | Phase 2 przeniesie style do carei-reservation.css |

## Deviations from Plan

None — plan executed exactly as written.

## Issues Encountered

None.

## Next Phase Readiness

**Ready:**
- REST API proxy gotowe do konsumpcji przez frontend JS
- Modal overlay mount point (`#carei-form-container`) czeka na formularz
- `wp_localize_script` dostarcza `restUrl` i `nonce` do JS

**Concerns:**
- sslverify=false — do zmiany przed produkcją
- Inline styles w widget → przenieść do CSS w Phase 2

**Blockers:** None

---
*Phase: 01-reservation-form-plugin, Plan: 01*
*Completed: 2026-03-25*