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