ver. 0.269: ShopPaymentMethod refactor + Apilo keepalive

docs/SHOP_PAYMENT_METHOD_REFACTOR_PLAN.md

@@ -0,0 +1,138 @@
+# 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.