shopPRO/docs/SHOP_PAYMENT_METHOD_REFACTOR_PLAN.md

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.