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

---
phase: 83-allegro-pull-status-mapping
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - 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
autonomous: true
delegation: off
---

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

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

<acceptance_criteria>

## AC-1: Nowa tabela pull mappings
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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>

<tasks>

<task type="auto">
  <name>Task 1: Migracja DB + AllegroPullStatusMappingRepository</name>
  <files>database/migrations/20260407_000083_allegro_pull_status_mappings.sql, src/Modules/Settings/AllegroPullStatusMappingRepository.php</files>
  <action>
    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)
  </action>
  <verify>Migracja SQL parsuje sie poprawnie; klasa kompiluje sie bez bledow skladni PHP</verify>
  <done>AC-1 satisfied: tabela istnieje z UNIQUE na allegro_status_code, pre-populated</done>
</task>

<task type="auto">
  <name>Task 2: Import Allegro uzywa pull mappings</name>
  <files>src/Modules/Settings/AllegroOrderImportService.php, src/Modules/Cron/CronHandlerFactory.php</files>
  <action>
    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
  </action>
  <verify>Import zamowienia Allegro mapuje status przez pull table; nowy nieznany status jest auto-discovered</verify>
  <done>AC-2, AC-3 satisfied: import uzywa pull mappings z fallbackiem i auto-discovery</done>
</task>

<task type="auto">
  <name>Task 3: UI pull mapping w Ustawienia > Allegro</name>
  <files>src/Modules/Settings/AllegroIntegrationsController.php, resources/views/settings/allegro.php, resources/lang/pl.php, routes/web.php</files>
  <action>
    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
  </action>
  <verify>Strona Ustawienia > Allegro > Statusy renderuje dwie sekcje; zapis pull mappings dziala</verify>
  <done>AC-4 satisfied: UI ma sekcje push i pull z osobnymi formularzami</done>
</task>

</tasks>

<boundaries>

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

</boundaries>

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

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

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