177 lines
7.1 KiB
Markdown
177 lines
7.1 KiB
Markdown
# 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.
|