shopPRO/docs/SHOP_ATTRIBUTE_REFACTOR_PLAN.md

Plan Refaktoryzacji - ShopAttribute (/admin/shop_attribute)

Data przygotowania: 2026-02-14 Tryb realizacji: Human In The Loop (HITL) Status: Zrealizowano kroki 0-6 (2026-02-14)

1. Cel i zakres

Celem jest pelna migracja modulu shop_attribute z legacy (admin/controls, admin/factory, admin/view, grid/gridEdit) na:

• Domain/* (repozytorium + logika zapisu),
• admin/Controllers/* (DI),
• nowe widoki oparte o components/table-list i components/form-edit,
• kanoniczny routing (list, edit, save, delete, values, values_save) z kompatybilnoscia aliasow legacy.

Zakres obejmuje takze przeglad i przepiecie zaleznosci w innych klasach (admin/front/shop), aby usunac twarde powiazanie ze starym modulem.

2. Stan obecny (baseline)

Legacy modułu

• autoload/admin/controls/class.ShopAttribute.php
• autoload/admin/factory/class.ShopAttribute.php
• autoload/admin/view/class.ShopAttribute.php
• admin/templates/shop-attribute/* (stare grid / gridEdit + AJAX attribute_value_tpl)

Zaleznosci poza modulem

• autoload/admin/controls/class.ShopProduct.php (lista atrybutow do kombinacji)
• admin/templates/shop-product/product-combination.php (nazwy atrybut/wartosc)
• autoload/admin/factory/class.ShopProduct.php (m.in. value_details, aktualizacja cen kombinacji)
• autoload/front/factory/class.ShopAttribute.php i autoload/shop/class.ProductAttribute.php (odczyt front/shop)
• templates/shop-product/_partial/product-attribute.php, autoload/front/factory/class.ShopOrder.php

Ryzyka znalezione w aktualnym UI wartosci

• domyslny jezyk w tytule jest hardcoded (pl),
• wybor domyslnej wartosci oparty o indeksy wierszy (podatne na bledy po usuwaniu),
• brak walidacji biznesowej (np. wymagane minimum 1 wartosc i 1 nazwa w jezyku domyslnym),
• UX edycji wartosci jest malo czytelny przy duzej liczbie pozycji.

3. Architektura docelowa

Nowe klasy

• autoload/Domain/Attribute/AttributeRepository.php
• autoload/admin/Controllers/ShopAttributeController.php

Nowe widoki

• admin/templates/shop-attribute/attributes-list.php (nowy table-list)
• admin/templates/shop-attribute/attribute-edit.php (nowy form-edit)
• admin/templates/shop-attribute/attribute-values-edit.php (nowy ekran wartosci)
• admin/templates/shop-attribute/attribute-values-custom-script.php (logika JS dla wartosci)
• admin/templates/shop-attribute/_partials/value-row.php (opcjonalny partial pojedynczego wiersza)

Routing

• kanoniczne:
  • /admin/shop_attribute/list/
  • /admin/shop_attribute/edit/id={id}
  • /admin/shop_attribute/save/
  • /admin/shop_attribute/delete/id={id}
  • /admin/shop_attribute/values/id={id}
  • /admin/shop_attribute/values_save/id={id}
• brak aliasow kompatybilnosci legacy (decyzja: URL-e niekanoniczne nie sa utrzymywane)

4. Plan realizacji HITL (krok po kroku)

Krok 0 - Freeze i test baseline

Zakres:

• uruchomienie testow referencyjnych (minimum smoke + wskazane pelne),
• zapisanie stanu wyjsciowego i listy plikow modulu.

Wyjscie:

• potwierdzony baseline testow przed zmianami.

Punkt akceptacji HITL:

• akceptacja startu implementacji po weryfikacji baseline.

Krok 1 - Domain Repository (bez zmian UI)

Zakres:

• utworzenie AttributeRepository z metodami admin:
  • listForAdmin(), findAttribute(), saveAttribute(), deleteAttribute(),
  • findValues(), saveValues(),
  • pomocnicze: getAttributeNameById(), getAttributeValueById(), getAttributesListForCombinations(), valueDetails().
• normalizacja danych i bezpieczne parsowanie inputow (switch, liczby, tablice ID).
• centralizacja invalidacji cache/temp po zapisach.

Wyjscie:

• gotowa warstwa domenowa pod kontroler DI.

Punkt akceptacji HITL:

• review API repozytorium i nazw metod przed podpieciem kontrolera.

Krok 2 - Kontroler DI i routing

Zakres:

• dodanie ShopAttributeController (akcje list/edit/save/delete/values/valuesSave),
• podpiecie do admin\Site::$newControllers,
• ustawienie kanonicznych URL bez aliasow legacy,
• aktualizacja linku menu do /admin/shop_attribute/list/.

Wyjscie:

• modul dziala przez nowy kontroler, bez usuwania legacy w tym kroku.

Punkt akceptacji HITL:

• potwierdzenie zgodnosci URL i backward compatibility.

Krok 3 - Migracja widokow (lista + formularz cechy)

Zakres:

• przepisanie listy na components/table-list,
• przepisanie formularza cechy na components/form-edit,
• utrzymanie obecnej funkcjonalnosci (status, typ, kolejnosc, nazwy per jezyk).

Wyjscie:

• brak zaleznosci od grid/gridEdit w tych ekranach.

Punkt akceptacji HITL:

• akceptacja UX i danych na liscie oraz formularzu cechy.

Krok 4 - Nowy panel edycji wartosci (UX)

Zakres:

• przebudowa values-edit na bardziej intuicyjny formularz:
  • jeden czytelny widok tabelaryczny (wiersz = wartosc),
  • stabilny identyfikator wiersza zamiast indeksu do wyboru wartosci domyslnej,
  • walidacja: co najmniej 1 wartosc, nazwa w jezyku domyslnym, jedna domyslna wartosc,
  • jasne komunikaty bledow i podsumowanie zmian.
• usuniecie zaleznosci od endpointu attribute_value_tpl (lub utrzymanie tylko jako alias fallback).

Wyjscie:

• nowy edytor wartosci odporny na bledy indeksowania i wygodniejszy dla operatora.

Punkt akceptacji HITL:

• decyzja biznesowa o finalnym UX (wariant A/B ponizej) i akceptacja wygladu.

Warianty UX do decyzji

• Wariant A (rekomendowany): osobny ekran values, ale w nowym ukladzie tabelarycznym + walidacje.
• Wariant B: integracja wartosci bezposrednio w attribute-edit (mniej klikniec, ale wieksza zlozonosc formularza).

Krok 5 - Przepiecie zaleznosci i usuniecie legacy

Zakres:

• przeszukanie i przepiecie wszystkich uzyc admin\factory\ShopAttribute w kodzie admina,
• aktualizacja zaleznosci w miejscach zwiazanych z kombinacjami produktu,
• usuniecie starych klas:
  • autoload/admin/controls/class.ShopAttribute.php
  • autoload/admin/view/class.ShopAttribute.php
  • autoload/admin/factory/class.ShopAttribute.php (po przepieciu wszystkich odwolan)
• cleanup starych szablonow nieuzywanych.

Wyjscie:

• brak runtime zaleznosci od legacy ShopAttribute.

Punkt akceptacji HITL:

• akceptacja listy usuwanych plikow i finalnego cleanupu.

Krok 6 - Testy + dokumentacja + release

Zakres:

• nowe testy:
  • tests/Unit/Domain/Attribute/AttributeRepositoryTest.php
  • tests/Unit/admin/Controllers/ShopAttributeControllerTest.php
• uruchomienie regresji (co najmniej testy modułowe + docelowo caly suite),
• aktualizacja dokumentacji:
  • docs/DATABASE_STRUCTURE.md (tabele atrybutow),
  • docs/PROJECT_STRUCTURE.md,
  • docs/REFACTORING_PLAN.md,
  • docs/CHANGELOG.md,
  • docs/TESTING.md.

Wyjscie:

• modul gotowy do release, z domknietym testowaniem i dokumentacja.

Punkt akceptacji HITL:

• finalna akceptacja pakietu zmian przed procedura releasowa.

5. Kryteria akceptacji

• shop_attribute dziala przez ShopAttributeController + AttributeRepository.
• Lista i formularze nie korzystaja z grid/gridEdit.
• Panel wartosci nie opiera domyslnej wartosci na nietrwalych indeksach.
• Stare klasy controls/view/factory modulu zostaja usuniete po przepieciu zaleznosci.
• Testy jednostkowe dla nowego repozytorium i kontrolera przechodza.
• Dokumentacja techniczna jest zaktualizowana.