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>
--- a/.paul/phases/48-email-template-shipment-variables/48-01-SUMMARY.md
+++ b/.paul/phases/48-email-template-shipment-variables/48-01-SUMMARY.md
@@ -0,0 +1,137 @@
+---
+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*
+