orderPRO/.paul/phases/50-allegro-shipment-waybill-push/50-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
50-allegro-shipment-waybill-push	01	execute	1		src/Modules/Shipments/AllegroShipmentService.php tests/Unit/AllegroShipmentServiceTest.php DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md	true

## 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.

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

## 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)

<acceptance_criteria>

AC-1: Numer przesylki jest wysylany do Allegro dla zamowienia Allegro

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

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

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

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>

Task 1: Rozszerz AllegroShipmentService o push waybill do checkout form shipments src/Modules/Shipments/AllegroShipmentService.php 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. rg -n "addShipmentToOrder|source_order_id|source = 'allegro'|ALLEGRO_HTTP_401" src/Modules/Shipments/AllegroShipmentService.php AC-1 satisfied, AC-2 satisfied i AC-3 satisfied: push dziala tylko dla Allegro i nie psuje lokalnego flow przy bledzie API. Task 2: Dodaj testy jednostkowe dla scenariuszy pushu tracking number tests/Unit/AllegroShipmentServiceTest.php 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`). C:/xampp/php/php.exe vendor/bin/phpunit --filter AllegroShipmentServiceTest --testdox AC-1 satisfied, AC-2 satisfied i AC-3 satisfied: testy potwierdzaja warunki i odpornosc implementacji. Task 3: Zaktualizuj dokumentacje techniczna DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md 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. rg -n "checkout-forms/.*/shipments|waybill|source = allegro|tracking number" DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md AC-4 satisfied: dokumentacja odzwierciedla nowa logike i ograniczenia zakresu.

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.

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

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

After completion, create `.paul/phases/50-allegro-shipment-waybill-push/50-01-SUMMARY.md`