# Plan Refaktoryzacji: shop_payment_method

Data utworzenia: 2026-02-14
Status: ZREALIZOWANY (Etapy 1-4 zakonczone: 2026-02-14)

## 1. Cel

Pelna migracja modulu `/admin/shop_payment_method/*` do obecnego standardu projektu:
- `Domain/*` dla logiki danych,
- `admin/Controllers/*` z DI dla routingu,
- widoki oparte o `components/table-list` i `components/form-edit`,
- usuniecie legacy klas/podpiecie zaleznosci.

## 2. Stan obecny (inwentaryzacja)

Aktualny modul jest legacy i opiera sie o `grid`:
- `autoload/admin/controls/class.ShopPaymentMethod.php`
- `autoload/admin/factory/class.ShopPaymentMethod.php`
- `autoload/admin/view/class.ShopPaymentMethod.php` (pusta)
- `admin/templates/shop-payment-method/view-list.php` (grid + inline edit)
- menu: `admin/templates/site/main-layout.php` -> `/admin/shop_payment_method/view_list/`

Zaleznosci wykryte poza modulem:
- `autoload/admin/controls/class.ShopTransport.php` korzysta z `admin\\factory\\ShopPaymentMethod::payments_list()`
- `autoload/front/factory/class.ShopPaymentMethod.php` ma bezposrednie zapytania do `pp_shop_payment_methods`
- `autoload/shop/class.PaymentMethod.php` ma bezposrednie zapytania do `pp_shop_payment_methods`
- `cron.php` korzysta z `front\\factory\\ShopPaymentMethod::get_apilo_payment_method_id()`

## 3. Zakres refaktoru

W zakresie:
1. Nowe repozytorium domenowe dla metod platnosci.
2. Nowy kontroler admin z DI i routingiem kanonicznym.
3. Nowe widoki listy i edycji (bez legacy `grid`).
4. Przepiecie zaleznosci (`ShopTransport`, `front\\factory\\ShopPaymentMethod`, `shop\\PaymentMethod`) na nowe API.
5. Cleanup legacy klas/plikow zwiazanych z modulem.
6. Testy jednostkowe + aktualizacja dokumentacji.

Poza zakresem (na ten etap):
1. Refaktoryzacja calego modulu `shop_transport` (zrobimy tylko przepiecie zaleznosci dot. payment methods).
2. Zmiany biznesowe w checkout poza zachowaniem obecnej logiki.

## 4. Architektura docelowa

Planowane nowe pliki:
- `autoload/Domain/PaymentMethod/PaymentMethodRepository.php`
- `autoload/admin/Controllers/ShopPaymentMethodController.php`
- `admin/templates/shop-payment-method/payment-methods-list.php`
- `admin/templates/shop-payment-method/payment-method-edit.php`

Planowane aktualizacje:
- `autoload/admin/class.Site.php` (rejestracja `ShopPaymentMethod` w DI routerze)
- `admin/templates/site/main-layout.php` (kanoniczny URL `/admin/shop_payment_method/list/`)
- `autoload/admin/controls/class.ShopTransport.php` (usuniecie zaleznosci od legacy factory)
- `autoload/front/factory/class.ShopPaymentMethod.php` (fasada delegujaca do Domain repo)
- `autoload/shop/class.PaymentMethod.php` (fasada delegujaca do Domain repo)

Planowane usuniecia:
- `autoload/admin/controls/class.ShopPaymentMethod.php`
- `autoload/admin/factory/class.ShopPaymentMethod.php`
- `autoload/admin/view/class.ShopPaymentMethod.php`
- `admin/templates/shop-payment-method/view-list.php`

## 5. Etapy realizacji (Human In The Loop)

### Etap 1: Domain + testy repozytorium
Zakres:
- utworzenie `PaymentMethodRepository` z metodami:
  - `listForAdmin(...)`
  - `find(int $id)`
  - `save(int $id, array $data)`
  - `allActive()`
  - `findActiveById(int $id)`
  - `isActive(int $id)`
  - `getApiloPaymentTypeId(int $id)`
  - `forTransport(int $transportId)`
- dodanie testu: `tests/Unit/Domain/PaymentMethod/PaymentMethodRepositoryTest.php`

Checkpoint:
- STOP i prosba o akceptacje po wdrozeniu etapu 1.

### Etap 2: Admin Controller + routing + nowe widoki
Zakres:
- nowy `ShopPaymentMethodController` (akcje: `list`, `edit`, `save`)
- migracja listy/edycji na `table-list` + `form-edit`
- podpiecie w `admin\\Site` (DI factory map)
- kompatybilnosc URL:
  - kanoniczne: `/admin/shop_payment_method/list|edit|save/`
  - aliasy legacy do decyzji po wdrozeniu (proponuje: tymczasowo wlaczyc)
- test kontrolera: `tests/Unit/admin/Controllers/ShopPaymentMethodControllerTest.php`

Checkpoint:
- STOP i prosba o akceptacje po wdrozeniu etapu 2.

### Etap 3: Przepiecie zaleznosci miedzymodulowych
Zakres:
- `ShopTransport` pobiera liste platnosci przez nowe repozytorium (bez legacy factory)
- `front\\factory\\ShopPaymentMethod` jako fasada do repozytorium domenowego
- `shop\\PaymentMethod` jako fasada do repozytorium domenowego
- zachowanie dotychczasowych podpisow metod (BC)

Checkpoint:
- STOP i prosba o akceptacje po wdrozeniu etapu 3.

### Etap 4: Cleanup + finalne testy + dokumentacja
Zakres:
- usuniecie legacy klas/plikow dla `shop_payment_method`
- uruchomienie testow:
  - najpierw targetowane testy PaymentMethod,
  - potem caly suite (`composer test` lub `./test.ps1`)
- aktualizacja dokumentacji:
  - `docs/DATABASE_STRUCTURE.md`
  - `docs/PROJECT_STRUCTURE.md`
  - `docs/REFACTORING_PLAN.md`
  - `docs/CHANGELOG.md`
  - `docs/TESTING.md`

Checkpoint:
- STOP i prosba o finalna akceptacje przed etapem release (zip/commit/push wg procedury KONIEC PRACY, jesli zlecisz).

## 6. Ryzyka i kontrola regresji

1. Ryzyko: utrata kompatybilnosci URL (`view_list`).
   Kontrola: tymczasowe aliasy lub redirect + test akcji.

2. Ryzyko: regresja checkout przy pobieraniu metod platnosci.
   Kontrola: zachowanie podpisow metod we `front\\factory\\ShopPaymentMethod` i `shop\\PaymentMethod`, testy repozytorium.

3. Ryzyko: `ShopTransport` przestanie pokazywac metody platnosci.
   Kontrola: jawne przepiecie zaleznosci i test manualny widoku edycji transportu.

## 7. Kryteria akceptacji

1. `/admin/shop_payment_method/list/` dziala na nowym kontrolerze i nowym widoku.
2. `/admin/shop_payment_method/edit/id={id}` i zapis dzialaja bez `grid`.
3. Brak zaleznosci od legacy `admin\\controls\\ShopPaymentMethod` i `admin\\factory\\ShopPaymentMethod`.
4. `ShopTransport`, frontend checkout i `cron.php` dzialaja na niezmienionych API publicznych.
5. Nowe testy przechodza, a pelny suite nie ma regresji.