update

2026-03-28 15:04:35 +01:00
parent c1d0d7762f
commit 2ab0d0e90e
44 changed files with 3027 additions and 493 deletions
--- a/.paul/phases/48-email-template-shipment-variables/48-01-PLAN.md
+++ b/.paul/phases/48-email-template-shipment-variables/48-01-PLAN.md
@@ -0,0 +1,197 @@
+---
+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>