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/46-allegro-status-push/46-01-PLAN.md
+++ b/.paul/phases/46-allegro-status-push/46-01-PLAN.md
@@ -0,0 +1,199 @@
+---
+phase: 46-allegro-status-push
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Settings/AllegroStatusSyncService.php
+  - src/Modules/Settings/AllegroApiClient.php
+  - src/Modules/Settings/AllegroStatusMappingRepository.php
+  - src/Modules/Settings/AllegroOrderSyncStateRepository.php
+  - src/Modules/Settings/AllegroIntegrationController.php
+  - resources/views/settings/allegro.php
+  - resources/lang/pl.php
+  - tests/Unit/AllegroStatusSyncServiceTest.php
+  - DOCS/ARCHITECTURE.md
+  - DOCS/TECH_CHANGELOG.md
+autonomous: true
+---
+
+<objective>
+## Goal
+Wdrozyc dzialajaca synchronizacje statusow zamowien w kierunku `orderPRO -> Allegro` i aktywowac ten kierunek w konfiguracji integracji Allegro.
+
+## Purpose
+Opcja kierunku `orderPRO -> Allegro` jest dostepna w UI, ale obecnie jest zablokowana i backend zwraca komunikat "jeszcze nie wdrozony". Operator nie moze wypchnac zmian statusu wykonanych recznie w orderPRO do Allegro.
+
+## Output
+- Pelna obsluga push direction w `AllegroStatusSyncService`
+- Metoda API do aktualizacji statusu checkout form w Allegro
+- Reverse mapping statusow `orderpro_status_code -> allegro_status_code`
+- Aktywna opcja kierunku w UI ustawien Allegro
+- Testy jednostkowe krytycznej logiki push
+- Aktualizacja dokumentacji technicznej
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Prior Work
+@.paul/phases/45-shoppro-status-push/45-01-SUMMARY.md
+
+## Source Files
+@src/Modules/Settings/AllegroStatusSyncService.php
+@src/Modules/Settings/AllegroApiClient.php
+@src/Modules/Settings/AllegroStatusMappingRepository.php
+@src/Modules/Settings/AllegroOrderSyncStateRepository.php
+@src/Modules/Settings/AllegroIntegrationController.php
+@resources/views/settings/allegro.php
+@resources/lang/pl.php
+@src/Modules/Cron/AllegroStatusSyncHandler.php
+</context>
+
+<skills>
+## Required Skills (from SPECIAL-FLOWS.md)
+
+| Skill | Priority | When to Invoke | Loaded? |
+|-------|----------|----------------|---------|
+| sonar-scanner | required | Po APPLY, przed UNIFY | o |
+
+**BLOCKING:** Required skills MUST be loaded before APPLY proceeds.
+
+## Skill Invocation Checklist
+- [ ] sonar-scanner loaded (run command or confirm)
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: Cron pushuje reczne zmiany statusu orderPRO do Allegro
+```gherkin
+Given integracja Allegro ma ustawiony kierunek synchronizacji statusow na orderPRO -> Allegro
+  And zamowienie Allegro ma reczna zmiane statusu w orderPRO (order_status_history.change_source = manual)
+  And istnieje mapowanie statusu orderPRO na status Allegro
+When uruchamia sie job cron allegro_status_sync
+Then AllegroStatusSyncService wykonuje push statusu do API Allegro
+  And wynik synchronizacji zawiera licznik pushed i failed
+```
+
+## AC-2: Brak mapowania nie zatrzymuje przetwarzania
+```gherkin
+Given czesc zamowien nie ma reverse mapowania statusu orderPRO -> Allegro
+When cron przetwarza batch zmian statusow
+Then zamowienia bez mapowania sa oznaczone jako skipped
+  And pozostale zamowienia sa dalej przetwarzane
+```
+
+## AC-3: Ustawienie kierunku jest aktywne i zapisywalne w UI
+```gherkin
+Given operator otworzy Ustawienia > Integracje > Allegro > Ustawienia
+When wybierze kierunek orderPRO -> Allegro i zapisze formularz
+Then opcja nie jest zablokowana jako disabled
+  And wartosc jest zapisana w app_settings (allegro_status_sync_direction)
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Implementacja push direction w AllegroStatusSyncService i reverse mapowania</name>
+  <files>src/Modules/Settings/AllegroStatusSyncService.php, src/Modules/Settings/AllegroStatusMappingRepository.php, src/Modules/Settings/AllegroOrderSyncStateRepository.php</files>
+  <action>
+    1. Rozszerzyc `AllegroStatusSyncService::sync()` o realna sciezke dla `orderpro_to_allegro` zamiast zwracania "jeszcze nie wdrozony".
+    2. Dodac prywatna metode push (np. `syncOrderproToAllegro()`), ktora:
+       - pobiera zamowienia Allegro z recznymi zmianami statusu (`order_status_history.change_source = manual`) od ostatniego kursora,
+       - filtruje tylko zamowienia `source = allegro`,
+       - buduje reverse mapowanie na podstawie `allegro_order_status_mappings` (`orderpro_status_code -> allegro_status_code`, first match wins),
+       - dla brakow mapowania zwieksza `skipped`, bez przerywania petli,
+       - aktualizuje kursor push po sukcesie batcha.
+    3. W `AllegroStatusMappingRepository` dodac metode zwracajaca reverse map dla push direction.
+    4. W `AllegroOrderSyncStateRepository` dodac obsluge kursora `last_status_pushed_at` (get/update), defensywnie wobec srodowisk bez kolumny.
+    5. Zachowac obecna logike `allegro_to_orderpro` bez regresji.
+
+    Avoid:
+    - nie pushowac zmian z `change_source = import` ani `sync` (petla synchronizacji),
+    - nie modyfikowac flow importu zamowien Allegro.
+  </action>
+  <verify>php -l src/Modules/Settings/AllegroStatusSyncService.php && php -l src/Modules/Settings/AllegroStatusMappingRepository.php && php -l src/Modules/Settings/AllegroOrderSyncStateRepository.php</verify>
+  <done>AC-1 i AC-2 satisfied: backend obsluguje push direction i bezpiecznie pomija brak mapowania</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Dodanie metody API update statusu checkout-form w AllegroApiClient</name>
+  <files>src/Modules/Settings/AllegroApiClient.php, src/Modules/Settings/AllegroStatusSyncService.php</files>
+  <action>
+    1. Dodac do `AllegroApiClient` metode aktualizacji statusu realizacji zamowienia Allegro (checkout form fulfillment) z obsluga tokena i bledow HTTP analogiczna do istniejacych metod.
+    2. Uzyc tej metody w push direction serwisu sync, mapujac status orderPRO na docelowy kod Allegro.
+    3. Zapewnic czytelny wynik dla kazdego rekordu (success/fail) i agregacje w odpowiedzi crona.
+    4. Zachowac istniejace standardy: prepared flow, brak stringowego SQL, brak "magic values" bez stalej.
+
+    Avoid:
+    - nie dodawac natywnych `alert()/confirm()` ani zmian w warstwie widoku w tym tasku,
+    - nie tlumic bledow API bez zapisu ich tresci do wyniku sync.
+  </action>
+  <verify>php -l src/Modules/Settings/AllegroApiClient.php && php -l src/Modules/Settings/AllegroStatusSyncService.php</verify>
+  <done>AC-1 satisfied: service moze fizycznie zaktualizowac status po stronie Allegro API</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Aktywacja opcji w UI + testy jednostkowe + dokumentacja</name>
+  <files>resources/views/settings/allegro.php, src/Modules/Settings/AllegroIntegrationController.php, resources/lang/pl.php, tests/Unit/AllegroStatusSyncServiceTest.php, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md</files>
+  <action>
+    1. Usunac blokade `disabled` z opcji `orderPRO -> Allegro` w formularzu ustawien Allegro i pozostawic poprawny zapis przez istniejacy endpoint `saveImportSettings`.
+    2. Uzuplenic komunikaty i opisy w tlumaczeniach PL (jezeli wymagane), aby nie sugerowaly "wkrotce".
+    3. Dodac testy jednostkowe dla krytycznych sciezek push:
+       - push sukces + increment `pushed`,
+       - brak reverse mapping + increment `skipped`,
+       - blad API + increment `failed` i brak przerwania batcha.
+    4. Zaktualizowac `DOCS/ARCHITECTURE.md` o dzialajacy kierunek `orderpro_to_allegro`.
+    5. Dopisac wpis do `DOCS/TECH_CHANGELOG.md` (co i dlaczego zostalo wdrozone).
+
+    Avoid:
+    - nie zmieniac schematu DB w tym planie,
+    - nie rozszerzac zakresu o nowe endpointy UI poza aktywacja istniejacej opcji.
+  </action>
+  <verify>php -l src/Modules/Settings/AllegroIntegrationController.php && php -l tests/Unit/AllegroStatusSyncServiceTest.php && C:/xampp/php/php.exe vendor/bin/phpunit tests/Unit/AllegroStatusSyncServiceTest.php</verify>
+  <done>AC-3 satisfied: opcja jest aktywna, testy i dokumentacja pokrywaja nowy kierunek</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- src/Modules/Settings/AllegroOrdersSyncService.php
+- src/Modules/Settings/AllegroOrderImportService.php
+- src/Modules/Orders/OrdersController.php
+- database/migrations/*
+
+## SCOPE LIMITS
+- Zakres dotyczy tylko synchronizacji statusow, bez zmian importu zamowien i bez zmian mapowania dostaw.
+- Brak przebudowy UI zakladki Allegro poza aktywacja istniejacej opcji kierunku.
+- Brak nowych cron job types i brak zmian interwalow harmonogramu.
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `php -l` przechodzi dla wszystkich zmienionych plikow PHP
+- [ ] Test jednostkowy `AllegroStatusSyncServiceTest` przechodzi lokalnie
+- [ ] Kierunek `orderpro_to_allegro` nie zwraca juz komunikatu "jeszcze nie wdrozony"
+- [ ] Wynik sync zawiera liczniki `pushed`, `skipped`, `failed`
+- [ ] UI pozwala zapisac kierunek `orderPRO -> Allegro`
+- [ ] `DOCS/ARCHITECTURE.md` i `DOCS/TECH_CHANGELOG.md` sa zaktualizowane
+</verification>
+
+<success_criteria>
+- Wszystkie taski zakonczone
+- Wszystkie kryteria akceptacji spelnione
+- Brak regresji w kierunku `allegro_to_orderpro`
+- Nowy kierunek dziala z poziomu crona i jest aktywowalny w UI
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/46-allegro-status-push/46-01-SUMMARY.md`
+</output>
--- a/.paul/phases/46-allegro-status-push/46-01-SUMMARY.md
+++ b/.paul/phases/46-allegro-status-push/46-01-SUMMARY.md
@@ -0,0 +1,132 @@
+---
+phase: 46-allegro-status-push
+plan: 01
+subsystem: api
+tags: [allegro, status-sync, cron, mappings]
+requires:
+  - phase: 45-shoppro-status-push
+    provides: orderPRO to external marketplace status push pattern
+provides:
+  - Allegro status push from orderPRO manual status changes
+  - Active orderPRO_to_allegro direction in integration settings
+  - Unit coverage for core push scenarios
+affects: [settings, cron, integrations]
+tech-stack:
+  added: []
+  patterns: [reverse status mapping, push cursor tracking, api retry on 401]
+key-files:
+  created:
+    - .paul/phases/46-allegro-status-push/46-01-SUMMARY.md
+    - tests/Unit/AllegroStatusSyncServiceTest.php
+  modified:
+    - src/Modules/Settings/AllegroStatusSyncService.php
+    - src/Modules/Settings/AllegroApiClient.php
+    - src/Modules/Settings/AllegroStatusMappingRepository.php
+    - src/Modules/Settings/AllegroOrderSyncStateRepository.php
+    - src/Modules/Cron/CronHandlerFactory.php
+    - resources/views/settings/allegro.php
+    - resources/lang/pl.php
+    - DOCS/ARCHITECTURE.md
+    - DOCS/TECH_CHANGELOG.md
+key-decisions:
+  - "Push only manual status changes (change_source=manual) to avoid sync loops."
+  - "Reuse integration_order_sync_state with last_status_pushed_at cursor for incremental push."
+  - "Retry once after token refresh on ALLEGRO_HTTP_401."
+patterns-established:
+  - "First-match-wins reverse mapping: orderpro_status_code -> allegro_status_code."
+  - "Per-order push result aggregation: pushed, skipped, failed."
+duration: ~4h
+started: 2026-03-28T12:20:50+01:00
+completed: 2026-03-28T13:20:00+01:00
+---
+
+# Phase 46 Plan 01: Allegro Status Push Summary
+
+orderPRO to Allegro status synchronization was implemented end-to-end and enabled in UI, with tests and documentation updates.
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~4h |
+| Started | 2026-03-28T12:20:50+01:00 |
+| Completed | 2026-03-28T13:20:00+01:00 |
+| Tasks | 3 completed |
+| Files modified | 10 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Cron pushes orderPRO manual status changes to Allegro | Pass | Implemented in AllegroStatusSyncService with API call, counters, and cursor updates. |
+| AC-2: Missing mapping does not stop processing | Pass | Unmapped statuses are counted as skipped; batch continues. |
+| AC-3: orderPRO -> Allegro direction active in UI | Pass | Disabled flag removed, option is selectable and persisted by existing settings flow. |
+
+## Verification Results
+
+| Command | Result |
+|--------|--------|
+| `php -l src/Modules/Settings/AllegroStatusSyncService.php` | PASS |
+| `php -l src/Modules/Settings/AllegroApiClient.php` | PASS |
+| `php -l src/Modules/Settings/AllegroStatusMappingRepository.php` | PASS |
+| `php -l src/Modules/Settings/AllegroOrderSyncStateRepository.php` | PASS |
+| `php -l src/Modules/Cron/CronHandlerFactory.php` | PASS |
+| `php -l tests/Unit/AllegroStatusSyncServiceTest.php` | PASS |
+| `C:/xampp/php/php.exe vendor/bin/phpunit --filter AllegroStatusSyncServiceTest --testdox` | PASS (4 tests, 39 assertions) |
+| `sonar-scanner` | PASS (analysis successful; Quality Gate failed due existing/new issues tracked in DOCS/todo.md) |
+
+## Accomplishments
+
+- Implemented real push path `orderpro_to_allegro` in sync service.
+- Added Allegro API fulfillment status update method and integrated it into cron flow.
+- Added reverse status mapping and push cursor support.
+- Enabled the direction in Allegro settings UI and adjusted PL hint text.
+- Added unit tests for success, skipped, failure, and 401 retry behavior.
+- Updated architecture and technical changelog docs.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Settings/AllegroStatusSyncService.php` | Modified | Added orderPRO->Allegro push execution and result aggregation. |
+| `src/Modules/Settings/AllegroApiClient.php` | Modified | Added PUT fulfillment status endpoint wrapper. |
+| `src/Modules/Settings/AllegroStatusMappingRepository.php` | Modified | Added reverse map builder for push direction. |
+| `src/Modules/Settings/AllegroOrderSyncStateRepository.php` | Modified | Added read/write support for `last_status_pushed_at`. |
+| `src/Modules/Cron/CronHandlerFactory.php` | Modified | Injected dependencies for new push logic and shared sync state repository. |
+| `resources/views/settings/allegro.php` | Modified | Enabled orderPRO->Allegro direction option. |
+| `resources/lang/pl.php` | Modified | Updated direction hint text (no "soon" wording). |
+| `tests/Unit/AllegroStatusSyncServiceTest.php` | Created | Added tests for key push flow behaviors. |
+| `DOCS/ARCHITECTURE.md` | Modified | Documented active push direction and API client method. |
+| `DOCS/TECH_CHANGELOG.md` | Modified | Logged technical change and rationale. |
+
+## Deviations from Plan
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Scope additions | 1 | Low |
+| Deferred | 1 | Low |
+
+- Scope addition: `src/Modules/Cron/CronHandlerFactory.php` was updated to wire dependencies for the new service behavior (not listed as a direct plan file, but required to activate runtime flow).
+- Plan file listed `src/Modules/Settings/AllegroIntegrationController.php` as a target, but no code change was needed there because existing save flow already persisted `allegro_status_sync_direction`.
+- Deferred: Sonar Quality Gate remediation intentionally postponed; full issue list captured in `DOCS/todo.md`.
+
+## Key Patterns and Decisions
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Manual-only push (`change_source=manual`) | Prevent import/sync feedback loops | Safe bidirectional architecture |
+| Cursor-based push (`last_status_pushed_at`) | Incremental processing and bounded batches | Better cron performance and idempotence |
+| Retry once on 401 after token refresh | Recover from expired access token | Improved operational resilience |
+
+## Next Phase Readiness
+
+Ready:
+- v1.8 milestone scope delivered for phase 46.
+- Operational status push path to Allegro can be validated in production cron logs.
+
+Concerns:
+- Sonar issues remain open and are tracked in `DOCS/todo.md`.
+
+Blockers:
+- None.
+