update

2026-04-07 22:39:16 +02:00
parent 8fa9ca6439
commit 40644eb362
31 changed files with 4972 additions and 71 deletions
--- a/.paul/phases/83-allegro-pull-status-mapping/83-01-PLAN.md
+++ b/.paul/phases/83-allegro-pull-status-mapping/83-01-PLAN.md
@@ -0,0 +1,186 @@
+---
+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>
--- a/.paul/phases/83-allegro-pull-status-mapping/83-01-SUMMARY.md
+++ b/.paul/phases/83-allegro-pull-status-mapping/83-01-SUMMARY.md
@@ -0,0 +1,153 @@
+---
+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*