---
phase: 83-allegro-pull-status-mapping
plan: 01
subsystem: settings, orders
tags: [status-mapping, allegro, pull, import]

requires:
  - phase: 74-reverse-status-mapping
    provides: push mapping with UNIQUE on orderpro_status_code
  - phase: 75-pull-status-mapping
    provides: pull mapping pattern for shopPRO (replicated for Allegro)
provides:
  - dedicated pull status mapping table for Allegro (allegro_order_status_pull_mappings)
  - pull mapping UI section in Allegro integration settings
  - auto-discovery of new Allegro statuses during import
affects: [allegro-import, status-sync, automation]

tech-stack:
  added: []
  patterns: [separate push/pull mapping tables for Allegro, auto-discovery in pull table]

key-files:
  created:
    - database/migrations/20260407_000083_allegro_pull_status_mappings.sql
    - src/Modules/Settings/AllegroPullStatusMappingRepository.php
  modified:
    - src/Modules/Settings/AllegroOrderImportService.php
    - src/Modules/Settings/AllegroStatusMappingController.php
    - src/Modules/Settings/AllegroIntegrationController.php
    - src/Modules/Settings/AllegroStatusDiscoveryService.php
    - src/Modules/Cron/CronHandlerFactory.php
    - routes/web.php
    - resources/views/settings/allegro.php
    - resources/lang/pl.php

key-decisions:
  - "No integration_id in Allegro pull table — Allegro is single-tenant unlike shopPRO"
  - "Nullable orderpro_status_code in pull table — allows auto-discovered unmapped statuses"
  - "Discovery service writes to both push and pull tables"
  - "Fallback to push table lookup when pull repo not injected (backward compat)"

patterns-established:
  - "Pull mapping for Allegro: UNIQUE on allegro_status_code — one orderPRO status per Allegro code"
  - "Auto-discovery: upsertDiscoveredStatus() on import AND on manual sync"

duration: ~30min
started: 2026-04-07T18:00:00Z
completed: 2026-04-07T18:30:00Z
---

# Phase 83 Plan 01: Allegro Pull Status Mapping — Summary

**Dedykowana tabela pull mappings dla Allegro z auto-discovery statusow i UI push/pull w ustawieniach**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~30min |
| Tasks | 3 planned, 3 completed |
| Files created | 2 |
| Files modified | 8 |
| DB migration | Executed on remote |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Nowa tabela pull mappings | Pass | Tabela utworzona z UNIQUE na allegro_status_code, 4 rows pre-populated z push table |
| AC-2: Import uzywa pull mappings | Pass | AllegroOrderImportService uzywa pullStatusMappings->findMappedStatusCode() |
| AC-3: Fallback dla niezmapowanych statusow | Pass | Auto-discovery via upsertDiscoveredStatus(), fallback na surowy status |
| AC-4: Sekcja pull mapping w UI | Pass | Dwie sekcje: push (orderPRO->Allegro) i pull (Allegro->orderPRO) |

## Accomplishments

- Nowa tabela `allegro_order_status_pull_mappings` z UNIQUE na `allegro_status_code` — eliminuje bug importu z niezmapowanym statusem
- UI w Ustawienia > Allegro > Statusy ma dwie sekcje: push ("Wysylka statusow") i pull ("Mapowanie przy imporcie")
- Auto-discovery statusow Allegro zarowno przy imporcie zamowien jak i przy recznym "Pobierz statusy z Allegro"
- Naprawiono 3 zamowienia (#223, #225, #233) z niezmapowanym statusem `new` → `nieoplacone`
- Dodano 6 brakujacych statusow Allegro do pull table (new, ready_for_processing, ready_for_shipment, delivered, returned, bought)

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `database/migrations/20260407_000083_allegro_pull_status_mappings.sql` | Created | Nowa tabela + pre-populate z push mappings |
| `src/Modules/Settings/AllegroPullStatusMappingRepository.php` | Created | Repository CRUD+lookup dla pull mappings |
| `src/Modules/Settings/AllegroOrderImportService.php` | Modified | Pull mapping lookup zamiast push reverse-lookup |
| `src/Modules/Settings/AllegroStatusMappingController.php` | Modified | Nowa metoda savePullStatusMappings() |
| `src/Modules/Settings/AllegroIntegrationController.php` | Modified | Pull repo dependency + dane pull do widoku |
| `src/Modules/Settings/AllegroStatusDiscoveryService.php` | Modified | Discovery zapisuje do obu tabel (push+pull) |
| `src/Modules/Cron/CronHandlerFactory.php` | Modified | Wstrzykniecie AllegroPullStatusMappingRepository |
| `routes/web.php` | Modified | Nowa route POST .../statuses/save-pull + DI |
| `resources/views/settings/allegro.php` | Modified | Sekcja pull mapping w tabce Statusy |
| `resources/lang/pl.php` | Modified | Klucze pull_title, pull_description, saved_pull |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Brak integration_id w tabeli Allegro | Allegro jest single-tenant (jeden zestaw credentials) | Prostsza tabela niz shopPRO |
| orderpro_status_code nullable w pull | Auto-discovered statusy nie maja jeszcze mapowania | User mapuje w UI po discovery |
| Discovery service pisze do obu tabel | "Pobierz statusy z Allegro" musi zasilac pull table | Spojne zachowanie push+pull |
| Dodanie 6 statusow Allegro recznie do pull | Discovery nie lapie krotkotrwalych statusow (np. new) | Pelna paleta statusow od razu |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Scope additions | 2 | Istotne usprawnienia |
| Auto-fixed | 1 | Naprawa danych zamowien |

**Total impact:** Rozszerzenie o discovery service + naprawa danych — kluczowe dla kompletnosci

### Scope Addition: AllegroStatusDiscoveryService

- **Requested by:** User during testing ("nie ma statusu new po Pobierz statusy")
- **Issue:** Discovery service zapisywal tylko do push table, nie do pull
- **Fix:** Dodanie pullStatusMappings dependency + upsertDiscoveredStatus w petli discovery
- **Files:** `AllegroStatusDiscoveryService.php`, `routes/web.php`

### Scope Addition: Reczne dodanie statusow Allegro

- **Requested by:** User
- **Issue:** Discovery nie lapie krotkotrwalych statusow (new, bought, ready_for_processing)
- **Fix:** INSERT 6 brakujacych statusow do pull table
- **Impact:** User od razu moze zmapowac wszystkie statusy

### Auto-fixed: Zamowienia z niezmapowanym statusem

- **Found during:** Investigation
- **Issue:** 3 zamowienia (#223, #225, #233) mialy surowy status `new` zamiast zmapowanego
- **Fix:** UPDATE orders SET external_status_id = 'nieoplacone' WHERE external_status_id = 'new' AND source = 'allegro'

## Next Phase Readiness

**Ready:**
- Pull mapping w pelni funkcjonalne i konfigurowalne
- Nowe importy z Allegro beda automatycznie mapowac statusy
- Discovery zasilaja obie tabele (push+pull)

**Concerns:**
- Brak ochrony statusu przy re-imporcie Allegro (analogicznie do Phase 75 dla shopPRO) — jesli potrzebne, osobna faza
- Niektore statusy Allegro moga nie miec mapowania — user musi je ustawic w UI

**Blockers:**
- None — kod wymaga deploy na serwer (FTP)

---
*Phase: 83-allegro-pull-status-mapping, Plan: 01*
*Completed: 2026-04-07*