# 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.