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

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
48-email-template-shipment-variables	01	execute	1		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	false

## 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.

## 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

## 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)

<acceptance_criteria>

AC-1: Szablony e-mail obsluguja nowe zmienne przesylki

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

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

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

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>

Task 1: Rozszerz katalog zmiennych szablonow i dane podgladu src/Modules/Settings/EmailTemplateController.php, resources/views/settings/email-templates.php 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`. rg -n "przesylka|link_sledzenia|tracking" src/Modules/Settings/EmailTemplateController.php resources/views/settings/email-templates.php AC-1 satisfied: nowe zmienne sa widoczne i podstawiane w preview. Task 2: Dodaj resolve danych paczki do zmiennych e-mail src/Modules/Email/VariableResolver.php, src/Modules/Email/EmailSendingService.php, src/Modules/Cron/CronHandlerFactory.php, src/Modules/Shipments/ShipmentPackageRepository.php 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. rg -n "przesylka\\.numer|przesylka\\.link_sledzenia|trackingUrl|findLatestByOrderId" src/Modules/Email src/Modules/Cron src/Modules/Shipments AC-2 satisfied i AC-3 satisfied: resolver zwraca numer i provider-aware link sledzenia. Task 3: Zaktualizuj dokumentacje techniczna po wdrozeniu DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md 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. rg -n "przesylka\\.numer|przesylka\\.link_sledzenia|DeliveryStatus::trackingUrl|email template" DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md AC-4 satisfied: dokumentacja techniczna odzwierciedla wdrozenie. Nowe zmienne szablonow e-mail z numerem i linkiem sledzenia przesylki. 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. Type "approved" to continue, or describe issues to fix

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.

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

<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>

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