orderPRO/.paul/phases/111-payment-transition-event/111-01-PLAN.md

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

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
111-payment-transition-event	01	execute	1		src/Modules/Orders/OrderImportRepository.php src/Modules/Settings/AllegroOrderImportService.php src/Modules/Settings/ShopproOrdersSyncService.php bin/backfill_payment_transition_111.php .paul/codebase/architecture.md .paul/codebase/tech_changelog.md	true	off

## Goal Re-import zamowienia (Allegro + shopPRO) wykrywa tranzycje platnosci 0/1 → 2 i emituje event `payment.status_changed`, dzieki czemu chain regul automatyzacji (regula #7 → akcja `update_order_status` na `w_realizacji`) odpala sie dla zamowien zaimportowanych przed potwierdzeniem platnosci. Backfill naprawia istniejace zamowienia, ktore utknely w `nieoplacone` mimo `payment_status=2`.

Purpose

Naprawa luki obserwowanej dla zamowienia #864 (Allegro): zamowienie zaimportowane 10s po zlozeniu, gdy Allegro jeszcze nie potwierdzilo platnosci (payment_status=0). Re-import 2 minuty pozniej zaktualizowal payment_status do 2, ale order.imported jest gated przez $wasCreated (commit 7eefd1a, Phase 98), wiec automatyzacja "Zmien status na w realizacji (allegro)" nigdy nie odpalila. Allegro nie ma odpowiednika ShopproPaymentStatusSyncService, wiec tranzycja platnosci znika cicho. ShopPRO ma identyczna luke w ShopproOrdersSyncService (flaga payment_transition jest wykrywana w repo, ale nie emituje eventu).

Output

• OrderImportRepository::upsertOrderAggregate zwraca payment_transition=true gdy poprzedni payment_status byl 0 lub 1 i nowy to 2 (rozszerzenie istniejacej logiki opartej tylko o status_code='nieoplacone')
• AllegroOrderImportService i ShopproOrdersSyncService emituja automationService->trigger('payment.status_changed', ...) na payment_transition
• CLI bin/backfill_payment_transition_111.php naprawia istniejace zamowienia z payment_status=2 && status_code='nieoplacone'
• Aktualizacja .paul/codebase/architecture.md (sekcja Order Lifecycle) i .paul/codebase/tech_changelog.md

- **Zakres** — Czy rozszerzyc tez na ShopproOrdersSyncService? → Odpowiedz: Allegro + shopPRO — spojnie obie sciezki re-importu emituja event. ShopproPaymentStatusSyncService osobno tez emituje, ale idempotencja (rule 7 jest idempotentna przy `update_order_status` — repeat call do tego samego status_code nie daje nowego status_history wpisu z `change_source='manual'` jesli status sie nie zmienia) zabezpiecza przed efektami duplikatu. - **Tranzycja** — Ktory przypadek wyzwala `payment.status_changed`? → Odpowiedz: Tylko 0/1 → 2. Wymaga rozszerzenia istniejacej logiki w OrderImportRepository (obecnie sprawdza `currentStatus='nieoplacone' && newPaymentStatus===2`) o porownanie poprzedniego payment_status. - **Backfill** — Naprawic istniejace zamowienia? → Odpowiedz: Tak, CLI script wzorem `bin/backfill_shipped_status_98.php` (Phase 98). Idempotentny, wzor: znajdz `payment_status=2 && status_code='nieoplacone'`, wymus update przez OrdersRepository::updateOrderStatus. - **Idempotencja** — Ochrona przed wielokrotnym emitowaniem? → Odpowiedz: Wystarcza istniejaca logika repo. Po pierwszej tranzycji status_code sie zmienia (przez akcje regul 7), wiec kolejny re-import ma `currentStatus='w_realizacji'` i `paymentTransition=false`. Nowa logika 0/1→2 oparta o porownanie payment_status tez bedzie self-resetting: po pierwszej tranzycji DB ma payment_status=2, kolejny re-import widzi old=2 i nowy=2, transition=false.

Project Context

@.paul/PROJECT.md @.paul/STATE.md @.paul/ROADMAP.md

Codebase Refs

@.paul/codebase/architecture.md @.paul/codebase/db_schema.md

Source Files

@src/Modules/Orders/OrderImportRepository.php @src/Modules/Settings/AllegroOrderImportService.php @src/Modules/Settings/ShopproOrdersSyncService.php @src/Modules/Automation/AutomationService.php @bin/backfill_shipped_status_98.php

Reference: Existing Pattern

• ShopproPaymentStatusSyncService.php:256 — $this->automation?->trigger('payment.status_changed', $orderId, [...]) — wzor invocation
• OrderImportRepository.php:41-50 — istniejaca logika paymentTransition (status-based, do rozszerzenia)
• bin/backfill_shipped_status_98.php — wzor jednorazowego CLI backfillu
• Regula #7 w DB (sprawdzona, payment_status=2, akcja update_order_status → w_realizacji, BEZ warunku integration_id) — odpali sie dla Allegro automatycznie po wyemitowaniu eventu

<acceptance_criteria>

AC-1: Repo wykrywa tranzycje 0/1 → 2

Given zamowienie istnieje w DB z payment_status=0 (lub 1) i status_code='nieoplacone'
When AllegroOrderImportService::importSingleOrder lub ShopproOrdersSyncService re-importuje to zamowienie z payment_status=2 w aggregate
Then OrderImportRepository::upsertOrderAggregate zwraca `payment_transition=true`
And status_code w bazie zostaje zaktualizowany z payloadu (nie zachowany jako nieoplacone)

Given zamowienie istnieje w DB z payment_status=2
When re-import wykona aggregate z payment_status=2
Then `payment_transition=false` (brak duplikatu eventu przy kolejnych re-importach)

Given zamowienie istnieje w DB z payment_status=0 i status_code='anulowane' (lub inny niz nieoplacone)
When re-import wykona aggregate z payment_status=2
Then `payment_transition=true` (wykrywanie wg payment_status, nie status_code)
And status_code zostaje chroniony zgodnie z istniejaca logika preservacji (Phase 62) — pole status_code nie jest nadpisywane jesli currentStatus != 'nieoplacone'

AC-2: Allegro i shopPRO re-import emituje payment.status_changed

Given OrderImportRepository zwrocilo `payment_transition=true` z `created=false`
When AllegroOrderImportService::importSingleOrder lub ShopproOrdersSyncService::importOneOrder kontynuuje
Then automationService->trigger('payment.status_changed', $orderId, $context) zostaje wywolane
And $context zawiera: integration_id, source ('allegro' lub 'shoppro'), new_payment_status='2', old_payment_status (numeric string z DB)
And automation_execution_logs ma wpis dla rule_id=7 (Zmien status na oplacone) ze status='success'
And status_code zamowienia w DB zmienia sie z 'nieoplacone' na 'w_realizacji' (przez chain reguly 7)

AC-3: Backfill naprawia historyczne dane

Given w DB istnieja zamowienia z payment_status=2 AND LOWER(status_code)='nieoplacone' AND source IN ('allegro', 'shoppro')
When operator uruchamia `php bin/backfill_payment_transition_111.php`
Then kazde takie zamowienie dostaje update status_code = 'w_realizacji' przez OrdersRepository::updateOrderStatus
And order_status_history dostaje wpis nieoplacone -> w_realizacji z change_source='import' i actor='Backfill 111'
And skrypt loguje na stdout liste zamowien (id, source, integration_id, internal_order_number)
And ponowne uruchomienie skryptu jest no-opem (idempotencja: po pierwszym przebiegu zadne zamowienie nie spelnia warunku)

AC-4: Brak regresji w istniejacym flow

Given pierwszy import zamowienia (created=true) z payment_status=2
When AllegroOrderImportService::importSingleOrder konczy
Then `order.imported` jest emitowane jak dotychczas (gate $wasCreated)
And `payment.status_changed` NIE jest emitowane przy created=true (transition liczy sie tylko przy update)

Given zamowienie shopPRO juz oplacone w DB (payment_status=2)
When osobny ShopproPaymentStatusSyncService cron wykryje brak zmian
Then nowy emit z importu nie powiela starego — istniejaca regula 7 idempotentnie zostawia status w_realizacji bez zmian (status_code juz jest w_realizacji, brak nowego status_history wpisu)

</acceptance_criteria>

Task 1: Rozszerz OrderImportRepository o detekcje tranzycji 0/1 → 2 src/Modules/Orders/OrderImportRepository.php 1. W `upsertOrderAggregate` (linie 33-81), w bloku `if (!$created)`: - Zamiast `getCurrentStatus($existingOrderId)`, wprowadz `getCurrentStatusAndPaymentStatus(int $orderId): array{status_code:string, payment_status:int}` ktora jednym zapytaniem czyta oba pola. - Wylicz `$paymentTransition = in_array($oldPaymentStatus, [0, 1], true) && $newPaymentStatus === 2;` - Zachowaj istniejaca logike preservacji status_code: `$statusOverwriteAllowed = ($currentStatus === 'nieoplacone' && $newPaymentStatus === 2);` — to (a nie paymentTransition) decyduje czy `$orderData['status_code']` zostaje nadpisany (Phase 62). - W `replacePayments`/`replaceShipments`/`replaceStatusHistory` warunek bedzie teraz `$paymentTransition || $statusOverwriteAllowed` — utrzymujemy obecne zachowanie shopPRO (replacePayments przy paymentTransition). 2. Wartosc zwracana: zachowaj `[order_id, created, payment_transition]` ale teraz `payment_transition` ma szersza semantyke (0/1→2 niezalznie od status_code). 3. Dodaj `private function getCurrentStatusAndPaymentStatus(int $orderId): array`. Stary `getCurrentStatus()` mozna usunac jesli nie uzywany w innym miejscu (sprawdzic grep).

Uwaga:
- NIE zmieniaj logiki `replaceStatusHistory($orderId, ...)` — historia tworzona tylko przy `$created` (zachowane w nowym warunku przy `$statusOverwriteAllowed`). Jesli payment_transition NIE rowna sie statusOverwriteAllowed, paymetTransition NIE wymusza nowego wpisu historii (chain reguly 7 wpisze go przez OrdersRepository::updateOrderStatus).

- `php -l src/Modules/Orders/OrderImportRepository.php` (lint OK) - Manualny test SQL: `SELECT payment_status, status_code FROM orders WHERE id = 864;` przed re-importem testowego (lokalna kopia) → 0/nieoplacone, po wymuszonym re-imporcie powinno byc 2/(zachowany lub w_realizacji). - Brak zmian w testach jednostkowych jesli nie istnieja dla tego repo (sprawdzic `tests/Unit/`). AC-1 spelnione: payment_transition oparte o porownanie payment_status, status_code chroniony zgodnie z dotychczasowa logika preservacji. Task 2: Emit payment.status_changed w Allegro + shopPRO import services src/Modules/Settings/AllegroOrderImportService.php, src/Modules/Settings/ShopproOrdersSyncService.php AllegroOrderImportService.php (po linii 99-106, po istniejacym blocku `order.imported`): ```php $wasPaymentTransition = !empty($saveResult['payment_transition']); if (!$wasCreated && $wasPaymentTransition && $this->automationService !== null) { $this->automationService->trigger('payment.status_changed', $savedOrderId, [ 'source' => IntegrationSources::ALLEGRO, 'integration_id' => (int) ($mapped['order']['integration_id'] ?? 0), 'old_payment_status' => '', // nieznane na poziomie service; repo nie eksponuje, nie kluczowe dla rule 7 (sprawdza tylko new_payment_status) 'new_payment_status' => (string) ($mapped['order']['payment_status'] ?? ''), ]); } ```

ShopproOrdersSyncService.php (po linii 273-280, po istniejacym blocku `order.imported`):
```php
$wasPaymentTransition = !empty($save['payment_transition']);
if (!$wasCreated && $wasPaymentTransition && $this->automationService !== null) {
    $this->automationService->trigger('payment.status_changed', $savedOrderId, [
        'source' => 'shoppro',
        'integration_id' => $integrationId,
        'old_payment_status' => '',
        'new_payment_status' => (string) ($aggregate['order']['payment_status'] ?? ''),
    ]);
}
```

Uwagi:
- `order.imported` musi pozostac gated przez `$wasCreated` — NIE zmieniaj tego (commit 7eefd1a).
- Emit `payment.status_changed` jest wykonywany TYLKO gdy `!$wasCreated` (re-import) — przy pierwszym imporcie payment_transition jest false (created=true → nie wchodzi do bloku detekcji).
- Sciezka `status_sync` (AllegroStatusSyncService → importSingleOrder('status_sync')) korzysta z tej samej metody, wiec automatycznie skorzysta z nowego emit.
- Reuse: dolacz brakujacy use `App\Core\Constants\IntegrationSources` jesli jeszcze nie ma (sprawdzic).

- `php -l src/Modules/Settings/AllegroOrderImportService.php` - `php -l src/Modules/Settings/ShopproOrdersSyncService.php` - Lokalny test: rezstart importu zamowienia testowego z payment_status=0 → ustaw payment.status w Allegro → kolejny status_sync → sprawdz `automation_execution_logs WHERE event_type='payment.status_changed' AND order_id=...` (powinien byc wpis dla rule_id=7) i `orders.status_code` powinno byc 'w_realizacji'. AC-2 spelnione: oba serwisy importu emituja `payment.status_changed` na payment_transition. AC-4 zachowane: order.imported nadal gated. Task 3: Backfill CLI dla istniejacych zamowien z luka platnosci bin/backfill_payment_transition_111.php Stworz nowy plik wzorem `bin/backfill_shipped_status_98.php`:

```php
<?php
declare(strict_types=1);

require __DIR__ . '/../bootstrap/app.php';

/** @var App\Core\Application $app */
$app = require __DIR__ . '/../bootstrap/app.php';

$pdo = $app->pdo();
$orders = $app->orders();

$statement = $pdo->prepare(
    "SELECT id, internal_order_number, source, integration_id
     FROM orders
     WHERE source IN ('allegro', 'shoppro')
       AND payment_status = 2
       AND LOWER(COALESCE(status_code, '')) = 'nieoplacone'"
);
$statement->execute();
$rows = $statement->fetchAll(PDO::FETCH_ASSOC) ?: [];

if ($rows === []) {
    echo "[backfill-111] Brak zamowien do naprawy.\n";
    exit(0);
}

echo "[backfill-111] Znaleziono " . count($rows) . " zamowien:\n";
foreach ($rows as $row) {
    $orderId = (int) $row['id'];
    $internalNumber = (string) $row['internal_order_number'];
    $source = (string) $row['source'];
    $integrationId = (int) $row['integration_id'];

    $updated = $orders->updateOrderStatus(
        $orderId,
        'w_realizacji',
        'import',
        'Backfill 111'
    );

    $marker = $updated ? 'OK' : 'SKIP';
    echo sprintf("  [%s] #%d %s (source=%s, integration=%d)\n", $marker, $orderId, $internalNumber, $source, $integrationId);
}

echo "[backfill-111] Zakonczono.\n";
```

Wymagania:
- Idempotentny: po updateOrderStatus zamowienie ma status_code='w_realizacji', wiec ponowne uruchomienie nie znajdzie nic.
- Bez recznego SQL — uzywaj OrdersRepository::updateOrderStatus (tworzy wpis w order_status_history + activity log).
- Bez parametrow CLI — operator uruchamia raz po deployu.
- Sprawdzic `bin/backfill_shipped_status_98.php` przed pisaniem — uzyc dokladnie tego samego patternu inicjalizacji (jak app jest dostepny: `require app.php` raz; jezeli phase 98 ma inny pattern, dopasowac).

- `php -l bin/backfill_payment_transition_111.php` - DRY-RUN przez SELECT preview: `SELECT id, internal_order_number, source, status_code, payment_status FROM orders WHERE source IN ('allegro','shoppro') AND payment_status=2 AND LOWER(COALESCE(status_code,''))='nieoplacone';` - Uruchomienie: `php bin/backfill_payment_transition_111.php` → log z liczba znalezionych + per-zamowienie [OK] - Drugi run: `[backfill-111] Brak zamowien do naprawy.` (idempotencja) - Spot-check w DB: `SELECT id, status_code FROM orders WHERE id IN (...)` → wszystkie `w_realizacji` - `SELECT * FROM order_status_history WHERE order_id IN (...) ORDER BY id DESC LIMIT 5` — powinny byc wpisy `nieoplacone → w_realizacji` z change_source='import' AC-3 spelnione: backfill naprawia historyczne dane idempotentnie. Task 4: Aktualizacja dokumentacji codebase (architecture + tech_changelog) .paul/codebase/architecture.md, .paul/codebase/tech_changelog.md `.paul/codebase/architecture.md`: - W sekcji "Order Lifecycle" rozszerz pkt 1 (Import) o: "Re-import: jezeli payment_status zmienia sie z 0/1 na 2, OrderImportRepository zwraca `payment_transition=true`, a service importu (AllegroOrderImportService, ShopproOrdersSyncService) emituje `payment.status_changed`. Chain regul automatyzacji (regula #7) wykonuje update_order_status → w_realizacji." - Dodaj w "Key Decisions" (lub w odpowiedniej sekcji) krotki bullet o phase 111.

`.paul/codebase/tech_changelog.md`:
- Dodaj wpis na gore (chronologicznie): `## 2026-05-05 — Phase 111: Payment Transition Event` z opisem co i dlaczego (zamowienie #864 case).

PROJECT.md (`Validated (Shipped)` lista) — UNIFY phase doda wpis po zakonczeniu, NIE w PLAN/APPLY.

Manualny przeglad obu plikow — sekcje istnieja, formatowanie spojne z reszta. Dokumentacja codebase zsynchronizowana z kodem.

DO NOT CHANGE

• AllegroOrderImportService.php:99 gate if ($wasCreated && ...) dla order.imported — Phase 98 decyzja
• ShopproPaymentStatusSyncService.php — istniejacy emit payment.status_changed zostaje (idempotentnie wspolistnieje)
• Regula automatyzacji #7 w DB — nie modyfikujemy warunkow ani akcji (akceptujemy ze obejmuje wszystkie integracje)
• Logika preservacji status_code w OrderImportRepository (Phase 62) — $statusOverwriteAllowed musi zachowac semantyke currentStatus='nieoplacone' && newPaymentStatus===2
• database/migrations/* — bez nowych migracji (idempotencja zalatwiona logika kodu, nie schema)

SCOPE LIMITS

• Bez zmian w AutomationService::evaluateOrderStatusCondition ani innych warunkach automatyzacji
• Bez modyfikacji UI panelu automatyzacji
• Bez nowych pol w tabeli orders (idempotencja przez logike, nie przez flage w DB)
• Bez zmian w AllegroStatusSyncService (korzysta z importSingleOrder, wiec dziedziczy fix automatycznie)
• Bez testow jednostkowych dla nowej logiki (na uzytkownika decyzja czy dopisywac w UNIFY; tests/ nie ma obecnie pokrycia OrderImportRepository)

Przed zamknieciem planu: - [ ] `php -l` przechodzi dla wszystkich zmienionych plikow - [ ] AC-1: zamowienie testowe Allegro z payment_status=0 + re-import z payment_status=2 → `automation_execution_logs` ma wpis rule_id=7 - [ ] AC-2: status_code zamowienia testowego zmienia sie 'nieoplacone' → 'w_realizacji' - [ ] AC-3: backfill znajduje + naprawia istniejace zamowienia (run #1 znajduje, run #2 = no-op) - [ ] AC-4: pierwszy import (created=true) NIE emituje `payment.status_changed` - [ ] Dokumentacja `.paul/codebase/architecture.md` + `.paul/codebase/tech_changelog.md` zaktualizowana

<success_criteria>

• Wszystkie 4 zadania ukonczone
• Wszystkie 4 AC zweryfikowane manualnie na lokalnej kopii DB lub na zamowieniu testowym
• php -l lint czysty
• Brak nowych warningow PHP w logach po deploy </success_criteria>

Po zakonczeniu UNIFY: `.paul/phases/111-payment-transition-event/111-01-SUMMARY.md`