orderPRO/.paul/phases/83-allegro-pull-status-mapping/83-01-PLAN.md

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

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
83-allegro-pull-status-mapping	01	execute	1		database/migrations/20260407_000083_allegro_pull_status_mappings.sql src/Modules/Settings/AllegroPullStatusMappingRepository.php src/Modules/Settings/AllegroOrderImportService.php src/Modules/Settings/AllegroIntegrationsController.php src/Modules/Cron/CronHandlerFactory.php resources/views/settings/allegro.php resources/lang/pl.php routes/web.php	true	off

## Goal Dodac dedykowana tabele pull mappings dla statusow Allegro i uzyc jej przy imporcie zamowien — analogicznie do Phase 75 (shopPRO pull status mapping). Zamowienia z Allegro nie beda juz importowane z surowymi statusami (np. "new") gdy brakuje mapowania.

Purpose

Obecnie AllegroOrderImportService szuka mapowania w tabeli allegro_order_status_mappings ktora ma UNIQUE na orderpro_status_code (kierunek push). Gdy status Allegro (np. "new") nie ma mapowania, surowy status trafia do external_status_id. To ten sam bug co w shopPRO naprawiony w Phase 75.

Output

• Nowa tabela allegro_order_status_pull_mappings
• Nowa klasa AllegroPullStatusMappingRepository
• Import Allegro uzywa pull mappings zamiast reverse-lookup
• UI w Ustawienia > Allegro > Statusy ma sekcje push i pull

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md

Prior Work

@.paul/phases/75-pull-status-mapping/75-01-SUMMARY.md — wzorzec pull mapping dla shopPRO (analogiczny pattern)

Source Files

@src/Modules/Settings/AllegroOrderImportService.php — linie 135-139: obecny lookup statusu @src/Modules/Settings/AllegroStatusMappingRepository.php — findMappedOrderproStatusCode() i buildOrderproToAllegroMap() @src/Modules/Settings/AllegroIntegrationsController.php — zarzadzanie mapowaniem statusow @src/Modules/Settings/ShopproPullStatusMappingRepository.php — wzorzec do nasledowania @src/Modules/Orders/OrderImportRepository.php — upsertOrderAggregate() z ochrona statusu @database/migrations/20260407_000079_pull_status_mappings.sql — wzorzec migracji shopPRO @resources/views/settings/allegro.php — widok ustawien Allegro

<acceptance_criteria>

AC-1: Nowa tabela pull mappings

Given baza danych z istniejaca tabela allegro_order_status_mappings
When migracja 000083 zostanie wykonana
Then istnieje tabela allegro_order_status_pull_mappings z kolumnami: id, allegro_status_code, orderpro_status_code, created_at, updated_at
  And UNIQUE constraint na allegro_status_code (jeden status orderPRO per status Allegro)
  And tabela jest pre-populated z istniejacych mappingow (reverse z push table)

AC-2: Import uzywa pull mappings

Given zamowienie Allegro ze statusem "new" i istniejace mapowanie pull: new -> nowe
When AllegroOrderImportService importuje zamowienie
Then external_status_id = "nowe" (zmapowany status orderPRO)
  And surowy status "new" jest zachowany w preferences_json.allegro_status_raw

AC-3: Fallback dla niezmapowanych statusow

Given zamowienie Allegro ze statusem nieznanym (brak w pull mappings)
When AllegroOrderImportService importuje zamowienie
Then external_status_id = surowy status Allegro (fallback)
  And status jest auto-discovered w tabeli pull (z NULL orderpro_status_code)

AC-4: Sekcja pull mapping w UI

Given uzytkownik otwiera Ustawienia > Allegro > Statusy
When strona sie zaladuje
Then widoczne sa dwie sekcje: "Wysylka statusow" (push: orderPRO->Allegro) i "Mapowanie przy imporcie" (pull: Allegro->orderPRO)
  And kazda sekcja ma wlasny formularz zapisu

</acceptance_criteria>

Task 1: Migracja DB + AllegroPullStatusMappingRepository database/migrations/20260407_000083_allegro_pull_status_mappings.sql, src/Modules/Settings/AllegroPullStatusMappingRepository.php 1. Utworzyc migracje SQL: - CREATE TABLE allegro_order_status_pull_mappings (id INT AUTO_INCREMENT PK, allegro_status_code VARCHAR(100) NOT NULL, orderpro_status_code VARCHAR(100) DEFAULT NULL, created_at DATETIME, updated_at DATETIME) - UNIQUE KEY na allegro_status_code - INSERT ... SELECT z allegro_order_status_mappings (reverse: allegro_status_code -> orderpro_status_code) — pre-populate 2. Utworzyc AllegroPullStatusMappingRepository analogicznie do ShopproPullStatusMappingRepository: - findMappedStatusCode(string $allegroStatusCode): ?string — lookup pull mapping - upsertDiscoveredStatus(string $allegroStatusCode): void — auto-discover nowych statusow - getAll(): array — pobranie wszystkich mappingow - save(array $mappings): void — zapis z UI Wzorzec: ShopproPullStatusMappingRepository (bez integration_id — Allegro nie uzywa multi-integration) Avoid: nie dodawac integration_id — tabela Allegro mappings jest globalna (nie per-integration) Migracja SQL parsuje sie poprawnie; klasa kompiluje sie bez bledow skladni PHP AC-1 satisfied: tabela istnieje z UNIQUE na allegro_status_code, pre-populated Task 2: Import Allegro uzywa pull mappings src/Modules/Settings/AllegroOrderImportService.php, src/Modules/Cron/CronHandlerFactory.php 1. W AllegroOrderImportService dodac zaleznosc AllegroPullStatusMappingRepository (konstruktor) 2. W mapCheckoutFormPayload() zamienic lookup: - PRZED: $mappedOrderproStatus = $this->statusMappings->findMappedOrderproStatusCode($rawAllegroStatus) - PO: $mappedOrderproStatus = $this->pullStatusMappings->findMappedStatusCode($rawAllegroStatus) - Jesli null: $this->pullStatusMappings->upsertDiscoveredStatus($rawAllegroStatus) — auto-discover - Fallback: surowy status Allegro (jak dotychczas) 3. W CronHandlerFactory wstrzyknac AllegroPullStatusMappingRepository i przekazac do AllegroOrderImportService Avoid: nie usuwac starego findMappedOrderproStatusCode() — jest uzywany do push mappings Import zamowienia Allegro mapuje status przez pull table; nowy nieznany status jest auto-discovered AC-2, AC-3 satisfied: import uzywa pull mappings z fallbackiem i auto-discovery Task 3: UI pull mapping w Ustawienia > Allegro src/Modules/Settings/AllegroIntegrationsController.php, resources/views/settings/allegro.php, resources/lang/pl.php, routes/web.php 1. W AllegroIntegrationsController: - Dodac zaleznosc AllegroPullStatusMappingRepository - Dodac metode savePullStatusMappings() — analogicznie do shopPRO - W metodzie renderujacej ustawienia statusow: przekazac pull mappings do widoku 2. W allegro.php widoku statusow: - Rozdzielic na dwie sekcje: "Wysylka statusow" (push, istniejacy formularz) i "Mapowanie przy imporcie" (pull, nowy formularz) - Pull sekcja: tabela z allegro_status_code (readonly) i dropdown orderpro_status_code - Osobny przycisk "Zapisz" per sekcja 3. W routes/web.php: dodac POST route dla save-pull 4. W resources/lang/pl.php: dodac klucze tlumaczen (allegro.pull.*) Wzorzec: dokladnie jak w Phase 75 dla shopPRO — dwie sekcje z jasnymi etykietami kierunku Strona Ustawienia > Allegro > Statusy renderuje dwie sekcje; zapis pull mappings dziala AC-4 satisfied: UI ma sekcje push i pull z osobnymi formularzami

DO NOT CHANGE

• src/Modules/Settings/AllegroStatusMappingRepository.php — push mapping repository zostaje bez zmian (buildOrderproToAllegroMap() uzywany przez push sync)
• src/Modules/Orders/OrderImportRepository.php — logika ochrony statusu przy re-imporcie zostaje bez zmian
• database/migrations/20260304_000025_create_allegro_order_status_mappings_table.sql — istniejaca tabela push bez zmian
• allegro_order_status_mappings table — dane push mappings nienaruszone

SCOPE LIMITS

• Nie dodawac integration_id do tabeli Allegro (Allegro jest single-tenant, inaczej niz shopPRO)
• Nie modyfikowac logiki push sync (AllegroStatusPushService / cron)
• Nie dodawac status protection na re-import Allegro (to osobny temat jesli potrzebny)

Before declaring plan complete: - [ ] Migracja SQL wykonana na remote DB - [ ] Import zamowienia Allegro ze statusem "new" mapuje na odpowiedni status orderPRO - [ ] Nowy nieznany status Allegro jest auto-discovered w tabeli pull - [ ] UI Ustawienia > Allegro > Statusy: dwie sekcje push/pull - [ ] Zapis pull mappings z UI dziala - [ ] Push sync (orderPRO->Allegro) niezmodyfikowany i dziala - [ ] Brak bledow PHP / brak bledow JS na stronie ustawien

<success_criteria>

• Wszystkie taski wykonane
• Wszystkie verification checks pass
• Zamowienia Allegro importuja sie ze zmapowanym statusem orderPRO
• Istniejace push mappings nienaruszone </success_criteria>

After completion, create `.paul/phases/83-allegro-pull-status-mapping/83-01-SUMMARY.md`