Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Jacek Pyziak
2026-03-28 15:32:34 +01:00
parent 2ab0d0e90e
commit 176d740578
9 changed files with 696 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
.paul/phases/50-allegro-shipment-waybill-push/50-01-PLAN.md Normal file
View File

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

36
.paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md Normal file
View File

@@ -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).