---
phase: 48-email-template-shipment-variables
plan: 01
subsystem: ui
tags: [email-templates, shipment-tracking, variable-resolver]
requires:
  - phase: 14-email-templates
    provides: bazowy mechanizm zmiennych i edytor Quill
  - phase: 27-shipment-tracking-backend
    provides: model paczek i generator linkow sledzenia
provides:
  - zmienne `{{przesylka.numer}}` i `{{przesylka.link_sledzenia}}` w szablonach e-mail
  - resolver danych paczki oparty o `shipment_packages` + `DeliveryStatus::trackingUrl`
affects: [email-sending, settings-email-templates, shipments]
tech-stack:
  added: []
  patterns: [provider-aware tracking link w mapowaniu zmiennych e-mail]
key-files:
  created: [.paul/phases/48-email-template-shipment-variables/48-01-SUMMARY.md]
  modified: [src/Modules/Email/VariableResolver.php, src/Modules/Settings/EmailTemplateController.php, resources/views/settings/email-templates.php, resources/scss/app.scss, public/assets/css/app.css, routes/web.php, src/Modules/Cron/CronHandlerFactory.php, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md]
key-decisions:
  - "Dodanie zmiennych przesylki bez zmian schematu DB - dane pobierane z najnowszej paczki"
  - "Link sledzenia liczony centralnie przez DeliveryStatus::trackingUrl(provider, tracking, carrier)"
patterns-established:
  - "Nowe zmienne e-mail powinny miec preview (`SAMPLE_DATA`) i wpis w katalogu VARIABLE_GROUPS"
duration: 45min
started: 2026-03-28T15:05:00+01:00
completed: 2026-03-28T15:43:37+01:00
---

# Phase 48 Plan 01: Email Template Shipment Variables Summary

Dodano obsluge numeru przesylki i linku sledzenia w szablonach e-mail wraz z poprawka UI dropdownu, aby lista zmiennych nie byla ucinana.

## Performance

| Metric | Value |
|--------|-------|
| Duration | 45min |
| Started | 2026-03-28T15:05:00+01:00 |
| Completed | 2026-03-28T15:43:37+01:00 |
| Tasks | 3 completed + 1 checkpoint |
| Files modified | 10 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Szablony e-mail obsluguja nowe zmienne przesylki | Pass | `VARIABLE_GROUPS` i `SAMPLE_DATA` rozszerzone o `przesylka.*`; widoczne w pickerze |
| AC-2: Resolver pobiera dane przesylki z zamowienia | Pass | `VariableResolver` pobiera najnowsza paczke przez `findLatestByOrderId()` |
| AC-3: Link sledzenia jest zalezny od provider/carrier | Pass | Link liczony przez `DeliveryStatus::trackingUrl(...)`; fallback do pustego stringu |
| AC-4: Dokumentacja odzwierciedla nowy kontrakt zmiennych | Pass | Zaktualizowano `DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`, `DOCS/todo.md` |

## Accomplishments

- Dodano dwie nowe zmienne szablonow e-mail: numer paczki i link sledzenia.
- Podlaczono resolver do danych paczki i logiki linkow provider/carrier.
- Naprawiono clipping dropdownu `Wstaw zmienna` (styl `overflow` + `z-index`).

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `.paul/phases/48-email-template-shipment-variables/48-01-SUMMARY.md` | Created | Podsumowanie wykonania planu |
| `src/Modules/Settings/EmailTemplateController.php` | Modified | Katalog zmiennych i dane preview (`przesylka.*`) |
| `src/Modules/Email/VariableResolver.php` | Modified | Pobranie najnowszej paczki i mapowanie zmiennych przesylki |
| `routes/web.php` | Modified | Wstrzykniecie `ShipmentPackageRepository` do `VariableResolver` |
| `src/Modules/Cron/CronHandlerFactory.php` | Modified | Wstrzykniecie `ShipmentPackageRepository` do `VariableResolver` w cronie |
| `resources/views/settings/email-templates.php` | Modified | Utrzymanie renderu zmiennych + usuniecie tymczasowego fallbacku |
| `resources/scss/app.scss` | Modified | Naprawa ucinania panelu zmiennych (`overflow: visible`, wyzszy `z-index`) |
| `public/assets/css/app.css` | Modified | Build CSS po zmianie SCSS |
| `DOCS/ARCHITECTURE.md` | Modified | Opis nowych zmiennych przesylki i fallbackow |
| `DOCS/TECH_CHANGELOG.md` | Modified | Log techniczny Phase 48 |
| `DOCS/todo.md` | Modified | Oznaczenie zakresu jako wykonany |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Resolver zmiennych pobiera ostatnia paczke po `order_id` | Najprostszy i stabilny punkt prawdy dla numeru/linku | Spójne podstawianie danych w send/preview |
| Uzycie `DeliveryStatus::trackingUrl` zamiast duplikacji mapowania URL | Jedno miejsce mapowania provider/carrier | Mniejsza duplikacja i latwiejsze utrzymanie |
| Poprawka UI dropdownu przez CSS (`overflow`, `z-index`) | Problem byl wizualny (clipping), nie danych | Picker zmiennych widoczny dla uzytkownika |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Auto-fixed | 1 | Niewielki, UX-only |
| Scope additions | 1 | Dodatkowa poprawka CSS konieczna do uzycia funkcji |
| Deferred | 0 | None |

**Total impact:** Funkcjonalnosc dostarczona zgodnie z celem, z dodatkowa poprawka prezentacji panelu zmiennych.

### Auto-fixed Issues

**1. UI clipping panelu zmiennych**
- **Found during:** checkpoint manual verify
- **Issue:** Dropdown `Wstaw zmienna` byl ucinany przez kolejny element formularza.
- **Fix:** Zmieniono `overflow` kontenera edytora na `visible` oraz podniesiono `z-index` panelu.
- **Files:** `resources/scss/app.scss`, `public/assets/css/app.css`
- **Verification:** Potwierdzenie manualne uzytkownika ("Jst ok")

### Deferred Items

None.

## Verification Results

- `C:\xampp\php\php.exe -l src/Modules/Settings/EmailTemplateController.php` OK
- `C:\xampp\php\php.exe -l src/Modules/Email/VariableResolver.php` OK
- `C:\xampp\php\php.exe -l src/Modules/Email/EmailSendingService.php` OK
- `C:\xampp\php\php.exe -l src/Modules/Cron/CronHandlerFactory.php` OK
- `C:\xampp\php\php.exe -l resources/views/settings/email-templates.php` OK
- `C:\xampp\php\php.exe -l routes/web.php` OK
- Manual checkpoint: potwierdzony przez uzytkownika
## Skill Audit

- Required `sonar-scanner`: not invoked in tym APPLY (gap zarejestrowany w STATE.md)

## Next Phase Readiness

**Ready:**
- Modul e-mail ma komplet zmiennych przesylki do szablonow i preview.
- UI picker zmiennych jest czytelny i nieuciety.

**Concerns:**
- Brak uruchomionego `sonar-scanner` dla tej petli - do nadrobienia przy najblizszym cyklu jakosci.

**Blockers:**
- None.

---
*Phase: 48-email-template-shipment-variables, Plan: 01*
*Completed: 2026-03-28*