feat(50-allegro-shipment-waybill-push): push waybill to allegro checkout form

Phase 50 complete: - add conditional waybill push for allegro orders only - add retry on ALLEGRO_HTTP_401 and non-critical failure handling - add unit tests and update architecture/changelog docs
2026-03-28 15:32:34 +01:00
parent 2ab0d0e90e
commit 176d740578
9 changed files with 696 additions and 30 deletions
--- a/.paul/PROJECT.md
+++ b/.paul/PROJECT.md
@@ -13,7 +13,7 @@ Sprzedawca moĹĽe obsĹ‚ugiwaÄ‡ zamĂłwienia ze wszystkich kanaĹ‚Ăłw
 | Attribute | Value |
 |-----------|-------|
 | Version | 1.0.0 |
-| Status | v2.1 Complete |
+| Status | v2.2 Complete |
 | Last Updated | 2026-03-28 |

 ## Requirements
@@ -58,6 +58,7 @@ Sprzedawca moĹĽe obsĹ‚ugiwaÄ‡ zamĂłwienia ze wszystkich kanaĹ‚Ăłw
 - [x] Automatyzacja przesylek: natychmiastowy event `shipment.created` + akcja `update_shipment_status` - Phase 47
 - [x] Szablony e-mail: zmienne `przesylka.numer` i `przesylka.link_sledzenia` z provider-aware linkiem sledzenia - Phase 48
 - [x] Automatyzacja: tab Historia z filtrowaniem/paginacja + retencja 30 dni + akcja update_order_status - Phase 49
+- [x] Allegro: automatyczne przekazywanie numeru przesylki do checkout form po utworzeniu paczki (tylko source=allegro) - Phase 50

 ### Active (In Progress)

@@ -127,6 +128,7 @@ PHP (XAMPP/Laravel), integracje z API marketplace'Ăłw (Allegro, Erli) oraz API
 | Zmienne e-mail przesylki bazuja na najnowszej paczce `shipment_packages` i `DeliveryStatus::trackingUrl` | Jeden spojny kontrakt dla numeru i linku sledzenia w szablonach | 2026-03-28 | Active |
 | Historia automatyzacji zapisywana per regula (success/failed) i czyszczona cronem po 30 dniach | Audyt wykonywania regul bez recznego utrzymania danych | 2026-03-28 | Active |
 | Akcja update_order_status korzysta z OrdersRepository::updateOrderStatus | Spojnosc z historia statusow i activity log bez duplikowania logiki | 2026-03-28 | Active |
+| Push waybilla do Allegro checkout forms wykonywany tylko dla zamowien source=allegro i jest niekrytyczny dla lokalnego tworzenia paczki | Eliminacja recznego kroku po stronie Allegro bez ryzyka utraty lokalnie utworzonej przesylki przy bledzie API | 2026-03-28 | Active |

 ## Success Metrics

@@ -158,6 +160,6 @@ Quick Reference:

 ---
 *PROJECT.md â€” Updated when requirements or context change*
-*Last updated: 2026-03-28 after Phase 49 completion (Automation History Tab)*
+*Last updated: 2026-03-28 after Phase 50 completion (Allegro Shipment Waybill Push)*


--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@@ -12,6 +12,19 @@ Next action: uruchom $paul-milestone (lub $paul-plan) dla kolejnego celu bizneso

 ## Completed Milestones

+<details>
+<summary>v2.2 Allegro Shipment Waybill Push - 2026-03-28 (1 phase, 1 plan)</summary>
+
+Automatyczne przekazywanie waybilla do Allegro checkout forms przy tworzeniu przesylki, ograniczone do zamowien `source=allegro` i odporne na bledy API Allegro.
+
+| Phase | Name | Plans | Completed |
+|-------|------|-------|-----------|
+| 50 | Allegro Shipment Waybill Push | 1/1 | 2026-03-28 |
+
+Archive: `.paul/phases/50-allegro-shipment-waybill-push/`
+
+</details>
+
 <details>
 <summary>v2.1 Automation History & Observability - 2026-03-28 (1 phase, 1 plan)</summary>

@@ -302,7 +315,7 @@ Archive: `.paul/milestones/v0.1-ROADMAP.md`

 ---
 *Roadmap created: 2026-03-12*
-*Last updated: 2026-03-28 - v2.1 completed (phase 49)*
+*Last updated: 2026-03-28 - v2.2 completed (phase 50)*



--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -1,23 +1,24 @@
-# Project State
+# Project State

 ## Project Reference

 See: .paul/PROJECT.md (updated 2026-03-28)

 **Core value:** Sprzedawca moze obslugiwac zamowienia ze wszystkich kanalow sprzedazy i nadawac przesylki bez przelaczania sie miedzy platformami.
-**Current focus:** Milestone v2.1 completed; ready for next milestone planning
+**Core value:** Sprzedawca moze obslugiwac zamowienia ze wszystkich kanalow sprzedazy i nadawac przesylki bez przelaczania sie miedzy platformami.
+**Current focus:** Milestone v2.2 completed; ready for next PLAN / next milestone

 ## Current Position

-Milestone: v2.1 Automation History & Observability - Complete
-Phase: 1 of 1 (49 - Automation History Tab) - Complete
-Plan: 49-01 complete
-Status: Ready for next PLAN / next milestone
-Last activity: 2026-03-28 14:47:06 - UNIFY closed for 49-01, SUMMARY created
+Milestone: v2.2 Allegro Shipment Waybill Push - Complete
+Phase: 1 of 1 (50 - Allegro Shipment Waybill Push) - Complete
+Plan: 50-01 complete
+Status: Loop complete - ready for next PLAN
+Last activity: 2026-03-28 15:33:00 - UNIFY closed for 50-01, SUMMARY created

 Progress:
 - Milestone: [##########] 100%
- Phase 49: [##########] 100%
+- Phase 50: [##########] 100%

 ## Loop Position

@@ -29,25 +30,19 @@ PLAN --> APPLY --> UNIFY

 ## Session Continuity

-Last session: 2026-03-28 14:47:06
-Stopped at: Phase 49 complete, milestone v2.1 complete
-Next action: Uruchom `$paul-milestone` (lub `$paul-plan`) dla kolejnego celu
-Resume file: .paul/ROADMAP.md
+Last session: 2026-03-28 15:33:00
+Stopped at: Phase 50 complete, milestone v2.2 complete
+Next action: Uruchom $paul-milestone (lub $paul-plan) dla kolejnego celu
+Resume file: .paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md

 ## Accumulated Context

 ### Decisions
 | Date | Decision | Impact |
 |------|----------|--------|
-| 2026-03-28 | Rozdzielenie `/settings/automation` na taby `Ustawienia` i `Historia` | Lepsza czytelnosc i oddzielenie konfiguracji od audytu wykonania |
-| 2026-03-28 | Historia automatyzacji zapisywana per regula (success/failed) + filtry/paginacja | Szybsza diagnostyka triggerow i wynikow regul |
-| 2026-03-28 | Retencja historii starszej niz 30 dni przez cron `automation_history_cleanup` | Kontrola rozmiaru danych i automatyczne porzadkowanie |
-| 2026-03-28 | Akcja `update_order_status` przez `OrdersRepository::updateOrderStatus` | Spojnosc z historia statusow i activity logiem |
-
-### Skill Audit Carry-Over
-| Expected | Invoked | Notes |
-|----------|---------|-------|
-| sonar-scanner | yes | Uruchomiony po APPLY, analiza zakonczona sukcesem |
+| 2026-03-28 | Push waybilla do Allegro wykonywany tylko dla `orders.source='allegro'` i `source_order_id` | Brak falszywych pushy dla innych integracji |
+| 2026-03-28 | Blad pushu waybilla do Allegro jest niekrytyczny dla tworzenia paczki | Lokalna przesylka nie ginie przy problemie API Allegro |
+| 2026-03-28 | Retry pushu po `ALLEGRO_HTTP_401` przez ponowne `resolveToken()` | Wyzsza odpornosc na wygasle tokeny |

 ## Git State

--- a/.paul/phases/50-allegro-shipment-waybill-push/50-01-PLAN.md
+++ b/.paul/phases/50-allegro-shipment-waybill-push/50-01-PLAN.md
@@ -0,0 +1,177 @@
+---
+phase: 50-allegro-shipment-waybill-push
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Shipments/AllegroShipmentService.php
+  - tests/Unit/AllegroShipmentServiceTest.php
+  - DOCS/ARCHITECTURE.md
+  - DOCS/TECH_CHANGELOG.md
+autonomous: true
+---
+
+<objective>
+## Goal
+Dodac automatyczne przekazywanie numeru przesylki do Allegro w momencie skutecznego wygenerowania przesylki, ale tylko dla zamowien zrodla `allegro`.
+
+## Purpose
+Operator nie powinien recznie dopisywac numeru przesylki w Allegro po utworzeniu paczki w orderPRO, bo to spowalnia obsluge i zwieksza ryzyko pomylek.
+
+## Output
+Rozszerzony flow `AllegroShipmentService` o push waybilla do endpointu checkout form shipments Allegro (z ochrona na przypadki spoza Allegro), testy jednostkowe nowej logiki oraz aktualizacja dokumentacji technicznej.
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+@DOCS/DB_SCHEMA.md
+@DOCS/ARCHITECTURE.md
+
+## Prior Work (only if genuinely needed)
+@.paul/phases/46-allegro-status-push/46-01-SUMMARY.md
+@.paul/phases/47-shipment-created-automation/47-01-SUMMARY.md
+
+## Source Files
+@src/Modules/Shipments/AllegroShipmentService.php
+@src/Modules/Settings/AllegroApiClient.php
+@src/Modules/Orders/OrdersRepository.php
+@src/Modules/Shipments/ShipmentPackageRepository.php
+@tests/Unit/AllegroStatusSyncServiceTest.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 integracyjnej | 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: Numer przesylki jest wysylany do Allegro dla zamowienia Allegro
+```gherkin
+Given zamowienie ma `source = allegro` i posiada `source_order_id`
+When przesylka Allegro WZA zostanie utworzona i ma tracking number
+Then system wywola API Allegro `POST /order/checkout-forms/{id}/shipments`
+And do Allegro trafi waybill oraz dane przewoznika
+```
+
+## AC-2: Zamowienia spoza Allegro nie wykonuja pushu do Allegro
+```gherkin
+Given zamowienie ma inne zrodlo niz `allegro` (np. shoppro, erli)
+When przesylka zostanie wygenerowana
+Then system nie wywola endpointu pushu shipment do Allegro
+And pozostale elementy flow tworzenia przesylki dzialaja bez zmian
+```
+
+## AC-3: Blad pushu numeru do Allegro nie blokuje lokalnego procesu
+```gherkin
+Given przesylka lokalnie zostala utworzona i ma tracking number
+When wywolanie endpointu Allegro zwroci blad lub wyjatek
+Then rekord paczki w orderPRO pozostaje poprawnie zapisany
+And uzytkownik nie traci utworzonej przesylki z powodu bledu pushu
+```
+
+## AC-4: Dokumentacja odzwierciedla nowy kontrakt
+```gherkin
+Given wdrozono push tracking number do Allegro checkout form shipments
+When zespol czyta dokumentacje techniczna
+Then `DOCS/ARCHITECTURE.md` i `DOCS/TECH_CHANGELOG.md` opisuja nowy moment i warunki pushu
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Rozszerz AllegroShipmentService o push waybill do checkout form shipments</name>
+  <files>src/Modules/Shipments/AllegroShipmentService.php</files>
+  <action>
+    Dodaj wewnetrzny flow, ktory po skutecznym utworzeniu przesylki i uzyskaniu tracking number wysyla numer do Allegro przez istniejace `AllegroApiClient::addShipmentToOrder(...)`.
+    Logike uruchamiaj tylko dla zamowien `source = allegro` oraz niepustego `source_order_id`.
+    Nie zmieniaj zachowania dla innych zrodel zamowien i providerow.
+    Blad pushu do Allegro traktuj jako niekrytyczny dla lokalnego lifecycle paczki (zapis paczki pozostaje sukcesem).
+    Utrzymaj retry po `ALLEGRO_HTTP_401` zgodnie z obecnym wzorcem token managera.
+  </action>
+  <verify>rg -n "addShipmentToOrder|source_order_id|source = 'allegro'|ALLEGRO_HTTP_401" src/Modules/Shipments/AllegroShipmentService.php</verify>
+  <done>AC-1 satisfied, AC-2 satisfied i AC-3 satisfied: push dziala tylko dla Allegro i nie psuje lokalnego flow przy bledzie API.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Dodaj testy jednostkowe dla scenariuszy pushu tracking number</name>
+  <files>tests/Unit/AllegroShipmentServiceTest.php</files>
+  <action>
+    Dodaj testy obejmujace co najmniej:
+    - wywolanie pushu dla zamowienia Allegro z tracking number,
+    - brak wywolania pushu dla zamowienia nie-Allegro,
+    - odporne zachowanie przy bledzie pushu (przesylka lokalnie pozostaje utworzona),
+    - retry po `ALLEGRO_HTTP_401`.
+    Mockuj zaleznosci zgodnie z obecnym stylem testow (`PHPUnit` + `dg/bypass-finals`).
+  </action>
+  <verify>C:/xampp/php/php.exe vendor/bin/phpunit --filter AllegroShipmentServiceTest --testdox</verify>
+  <done>AC-1 satisfied, AC-2 satisfied i AC-3 satisfied: testy potwierdzaja warunki i odpornosc implementacji.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Zaktualizuj dokumentacje techniczna</name>
+  <files>DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md</files>
+  <action>
+    Opisz nowy krok przeplywu tworzenia przesylki Allegro: automatyczne przekazanie waybilla do checkout form shipment po uzyskaniu tracking number.
+    Dodaj informacje o warunku ograniczajacym zakres do zamowien zrodla Allegro i o fallbacku na niekrytyczny blad pushu.
+    Potwierdz brak zmian w schemacie bazy.
+  </action>
+  <verify>rg -n "checkout-forms/.*/shipments|waybill|source = allegro|tracking number" DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md</verify>
+  <done>AC-4 satisfied: dokumentacja odzwierciedla nowa logike i ograniczenia zakresu.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `database/migrations/*` (brak zmian schematu DB)
+- Flow tworzenia przesylek dla providerow innych niz `allegro_wza`
+- Logika status sync orderPRO -> Allegro z fazy 46 (to osobny mechanizm)
+
+## SCOPE LIMITS
+- Zakres obejmuje tylko push numeru przesylki do Allegro przy generowaniu przesylki.
+- Bez zmian UI i bez nowych formularzy.
+- Bez dodawania nowego cron joba.
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `C:\xampp\php\php.exe -l src/Modules/Shipments/AllegroShipmentService.php`
+- [ ] `C:\xampp\php\php.exe -l tests/Unit/AllegroShipmentServiceTest.php`
+- [ ] `C:\xampp\php\php.exe vendor/bin/phpunit --filter AllegroShipmentServiceTest --testdox`
+- [ ] Brak regresji lokalnego flow tworzenia paczki dla zamowien nie-Allegro
+- [ ] Dokumentacja zaktualizowana (`DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`)
+- [ ] All acceptance criteria met
+</verification>
+
+<success_criteria>
+- Po wygenerowaniu przesylki dla zamowienia Allegro system automatycznie wysyla numer przesylki do Allegro.
+- Dla zamowien spoza Allegro nie ma wywolan endpointu Allegro shipment push.
+- Ewentualny blad pushu nie anuluje lokalnie utworzonej przesylki.
+- Dokumentacja opisuje nowy kontrakt i brak zmian DB.
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md`
+</output>
--- a/.paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md
+++ b/.paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md
@@ -0,0 +1,36 @@
+---
+phase: 50-allegro-shipment-waybill-push
+plan: 01
+status: completed
+completed: 2026-03-28
+---
+
+# Phase 50 Plan 01 Summary
+
+## Result
+- Dodano automatyczny push numeru przesylki do Allegro (`POST /order/checkout-forms/{id}/shipments`) po uzyskaniu `tracking_number`.
+- Push wykonuje sie tylko dla zamowien Allegro (`orders.source='allegro'`) z niepustym `source_order_id`.
+- Blad pushu jest niekrytyczny - lokalna paczka pozostaje utworzona.
+- Dodano retry pushu po `ALLEGRO_HTTP_401` z odswiezeniem tokenu.
+
+## Acceptance Criteria
+- AC-1: Pass
+- AC-2: Pass
+- AC-3: Pass
+- AC-4: Pass
+
+## Verification
+- `C:\xampp\php\php.exe -l src/Modules/Shipments/AllegroShipmentService.php` PASS
+- `C:\xampp\php\php.exe -l tests/Unit/AllegroShipmentServiceTest.php` PASS
+- `C:\xampp\php\php.exe vendor/bin/phpunit --filter AllegroShipmentServiceTest --testdox` PASS (4 tests, 54 assertions)
+- `sonar-scanner` PASS (analysis successful): https://sonar.project-pro.pl/dashboard?id=orderPRO
+
+## Files
+- `src/Modules/Shipments/AllegroShipmentService.php`
+- `tests/Unit/AllegroShipmentServiceTest.php`
+- `DOCS/ARCHITECTURE.md`
+- `DOCS/TECH_CHANGELOG.md`
+
+## Notes
+- Brak zmian schematu DB.
+- Brak checkpointow manualnych (plan autonomiczny).