orderPRO/.paul/phases/48-email-template-shipment-variables/48-01-PLAN.md

---
phase: 48-email-template-shipment-variables
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/Modules/Email/VariableResolver.php
  - src/Modules/Email/EmailSendingService.php
  - src/Modules/Cron/CronHandlerFactory.php
  - src/Modules/Settings/EmailTemplateController.php
  - resources/views/settings/email-templates.php
  - DOCS/ARCHITECTURE.md
  - DOCS/TECH_CHANGELOG.md
  - DOCS/todo.md
autonomous: false
---

<objective>
## Goal
Dodac w szablonach e-mail nowe zmienne: `{{przesylka.numer}}` oraz `{{przesylka.link_sledzenia}}`, tak aby link sledzenia byl budowany zaleznie od provider/carrier danej przesylki.

## Purpose
Szablony e-mail maja przekazywac klientowi realny numer paczki i klikalny URL sledzenia bez recznego dopisywania danych przez operatora.

## Output
Rozszerzony resolver zmiennych e-mail o dane najnowszej paczki, aktualny katalog zmiennych w UI (`/settings/email-templates`) oraz zaktualizowana dokumentacja techniczna.
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@DOCS/ARCHITECTURE.md
@DOCS/DB_SCHEMA.md
@DOCS/todo.md

## Prior Work (only if genuinely needed)
@.paul/phases/14-email-templates/14-02-SUMMARY.md
@.paul/phases/15-email-sending/15-01-SUMMARY.md
@.paul/phases/27-shipment-tracking-backend/27-01-SUMMARY.md

## Source Files
@src/Modules/Email/VariableResolver.php
@src/Modules/Email/EmailSendingService.php
@src/Modules/Settings/EmailTemplateController.php
@resources/views/settings/email-templates.php
@src/Modules/Shipments/ShipmentPackageRepository.php
@src/Modules/Shipments/DeliveryStatus.php
@src/Modules/Cron/CronHandlerFactory.php
</context>

<skills>
## Required Skills (from SPECIAL-FLOWS.md)

| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| `sonar-scanner` | required | Po APPLY, przed UNIFY | o |
| /feature-dev | optional | Przed wdrazaniem nowej funkcjonalnosci | o |
| /code-review | optional | Po APPLY, przed UNIFY | o |

**BLOCKING:** Required skills MUST be loaded before APPLY proceeds.

## Skill Invocation Checklist
- [ ] `sonar-scanner` uruchomiony po APPLY
- [ ] /feature-dev (opcjonalnie)
- [ ] /code-review (opcjonalnie)

</skills>

<acceptance_criteria>

## AC-1: Szablony e-mail obsluguja nowe zmienne przesylki
```gherkin
Given uzytkownik edytuje szablon na `/settings/email-templates`
When wybierze zmienne `{{przesylka.numer}}` i `{{przesylka.link_sledzenia}}`
Then zmienne sa dostepne na liscie i poprawnie podstawiane w preview
```

## AC-2: Resolver pobiera dane przesylki z zamowienia
```gherkin
Given zamowienie ma co najmniej jedna paczke w `shipment_packages`
When system renderuje temat i tresc e-maila
Then `przesylka.numer` zawiera tracking number najnowszej paczki
And `przesylka.link_sledzenia` zawiera URL sledzenia dla tej paczki
```

## AC-3: Link sledzenia jest zalezny od provider/carrier
```gherkin
Given paczka ma `provider` oraz opcjonalnie `carrier_id`
When system oblicza `przesylka.link_sledzenia`
Then korzysta z logiki `DeliveryStatus::trackingUrl(provider, tracking_number, carrier_id)`
And dla braku numeru przesylki zwraca pusty string zamiast blednego URL
```

## AC-4: Dokumentacja odzwierciedla nowy kontrakt zmiennych
```gherkin
Given wdrozone zmienne przesylki w module e-mail
When zespol czyta dokumentacje techniczna
Then ARCHITECTURE i TECH_CHANGELOG opisuja nowe zmienne oraz zasady budowy linku
And todo/changelog zawiera wpis o tym zakresie
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Rozszerz katalog zmiennych szablonow i dane podgladu</name>
  <files>src/Modules/Settings/EmailTemplateController.php, resources/views/settings/email-templates.php</files>
  <action>
    Dodaj nowa grupe/lub rozszerzenie grupy zmiennych o `przesylka.numer` i `przesylka.link_sledzenia`.
    Uaktualnij `SAMPLE_DATA`, aby preview na stronie ustawien pokazywal realistyczny numer oraz przykladowy URL sledzenia.
    Zachowaj aktualny format placeholderow `{{grupa.pole}}` oraz zgodnosc z endpointem `getVariables`.
  </action>
  <verify>rg -n "przesylka|link_sledzenia|tracking" src/Modules/Settings/EmailTemplateController.php resources/views/settings/email-templates.php</verify>
  <done>AC-1 satisfied: nowe zmienne sa widoczne i podstawiane w preview.</done>
</task>

<task type="auto">
  <name>Task 2: Dodaj resolve danych paczki do zmiennych e-mail</name>
  <files>src/Modules/Email/VariableResolver.php, src/Modules/Email/EmailSendingService.php, src/Modules/Cron/CronHandlerFactory.php, src/Modules/Shipments/ShipmentPackageRepository.php</files>
  <action>
    Rozszerz przeplyw budowy mapy zmiennych tak, by resolver mial dostep do najnowszej paczki dla zamowienia.
    Wykorzystaj repozytorium paczek do pobrania ostatniej paczki (`order_id`) i wypelnij:
    - `przesylka.numer` = tracking number,
    - `przesylka.link_sledzenia` = wynik `DeliveryStatus::trackingUrl(provider, tracking_number, carrier_id)`.
    Zapewnij bezpieczny fallback na pusty string, gdy paczka lub tracking nie istnieje.
    Dostosuj konstrukcje zaleznosci serwisu e-mail (factory/DI) bez zmian zachowania innych funkcji.
  </action>
  <verify>rg -n "przesylka\\.numer|przesylka\\.link_sledzenia|trackingUrl|findLatestByOrderId" src/Modules/Email src/Modules/Cron src/Modules/Shipments</verify>
  <done>AC-2 satisfied i AC-3 satisfied: resolver zwraca numer i provider-aware link sledzenia.</done>
</task>

<task type="auto">
  <name>Task 3: Zaktualizuj dokumentacje techniczna po wdrozeniu</name>
  <files>DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md</files>
  <action>
    Dodaj opis nowych zmiennych e-mail i ich zrodla danych (shipment_packages + DeliveryStatus::trackingUrl).
    Opisz ograniczenia (brak paczki/brak trackingu = puste wartosci) i brak zmian schematu DB.
    Uzupelnij wpis changelog/todo zgodnie z praktyka projektu.
  </action>
  <verify>rg -n "przesylka\\.numer|przesylka\\.link_sledzenia|DeliveryStatus::trackingUrl|email template" DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md</verify>
  <done>AC-4 satisfied: dokumentacja techniczna odzwierciedla wdrozenie.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Nowe zmienne szablonow e-mail z numerem i linkiem sledzenia przesylki.</what-built>
  <how-to-verify>
    1. Otworz: `https://orderpro.projectpro.pl/settings/email-templates`.
    2. Edytuj dowolny szablon i wstaw `{{przesylka.numer}}` oraz `{{przesylka.link_sledzenia}}`.
    3. Uruchom preview i potwierdz, ze obie zmienne sa podstawione.
    4. Wyslij testowy e-mail dla zamowienia z paczka i sprawdz, czy link prowadzi do poprawnego sledzenia dla danego kuriera/providera.
    5. Powtorz dla zamowienia bez paczki i potwierdz brak blednych placeholderow/URL.
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- `database/migrations/*` (bez zmian schematu)
- Moduly automatyzacji i synchronizacji statusow niezwiązane z e-mail template variables
- Widoki i style spoza `settings/email-templates`

## SCOPE LIMITS
- Zakres obejmuje tylko zmienne szablonow e-mail zwiazane z przesylka.
- Bez dodawania nowych endpointow API.
- Bez zmian logiki providerow trackingu poza wykorzystaniem istniejacego `DeliveryStatus::trackingUrl`.

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `C:\xampp\php\php.exe -l src/Modules/Settings/EmailTemplateController.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Email/VariableResolver.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Email/EmailSendingService.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/CronHandlerFactory.php`
- [ ] `C:\xampp\php\php.exe -l resources/views/settings/email-templates.php`
- [ ] Manual checkpoint wykonany (preview + realna wysylka)
- [ ] Dokumentacja zaktualizowana (`DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`, `DOCS/todo.md`)
- [ ] All acceptance criteria met
</verification>

<success_criteria>
- `przesylka.numer` i `przesylka.link_sledzenia` sa dostepne w szablonach e-mail.
- Resolver buduje link sledzenia zalezny od provider/carrier.
- Brak regresji w preview i wysylce e-mail.
- Dokumentacja techniczna opisuje nowe zmienne i przeplyw danych.
</success_criteria>

<output>
After completion, create `.paul/phases/48-email-template-shipment-variables/48-01-SUMMARY.md`
</output>