shopPRO/.paul/phases/18-google-feed-permutation-url-fix/18-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
18-google-feed-permutation-url-fix	01	execute	1		autoload/Domain/Product/ProductRepository.php autoload/Shared/Helpers/Helpers.php autoload/front/LayoutEngine.php templates/shop-product/_partial/product-attribute.php tests/Unit/Domain/Product/ProductRepositoryTest.php tests/Unit/Shared/Helpers/HelpersTest.php	true	off

## Goal Naprawić linki produktów z permutacją atrybutów w feedzie Google: zamienić separator `/` na `_` między parami `attr-val`, dopasować routing `pp_routes`, konwersję `_` → `|` w warstwie front oraz preselekcję wartości atrybutów na podstawie `permutation_hash` z URL.

Purpose

URL z formatu /slug/20-170/21-175 nie matchował się w pp_routes (wzorzec [0-9-]+ nie obejmuje /), więc Google Merchant Center prowadził klientów na stronę główną zamiast na produkt z wybraną kombinacją atrybutów. Strata ruchu komercyjnego z feedu.

Output

• 4 pliki silnika z nowym separatorem _
• Unit testy: regex routingu (Helpers) + generator linku (ProductRepository::appendCombinationToXml)
• SUMMARY z listą akcji post-deploy do wykonania ręcznie na produkcji

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md @.paul/codebase/architecture.md

Source Files

@autoload/Domain/Product/ProductRepository.php @autoload/Shared/Helpers/Helpers.php @autoload/front/LayoutEngine.php @templates/shop-product/_partial/product-attribute.php

- **Testy** — Czy dodać unit testy dla zmian? → Odpowiedź: Tak — pełne pokrycie (Helpers regex + ProductRepository::appendCombinationToXml) - **Post-deploy** — Czy wykonać regenerację routes/cache/feedu w ramach fazy? → Odpowiedź: Nic — tylko kod; akcje produkcyjne udokumentowane w SUMMARY - **Redirect 301** — Czy dodać redirecty ze starych URL-i? → Odpowiedź: Nie — Google sam zaktualizuje linki z feedu - **Skills** — /feature-dev required w SPECIAL-FLOWS? → Odpowiedź: Override — pomiń (hotfix z konkretną instrukcją, jak w fazach 15/16/17)

<acceptance_criteria>

AC-1: Generator linku w feedzie używa _

Given produkt z permutacją atrybutów (permutation_hash = "20-170|21-175")
When wywołany jest ProductRepository::appendCombinationToXml dla feedu Google
Then wygenerowany URL zawiera segment `20-170_21-175` (jeden segment, separator `_`)
And nie zawiera `/` między parami atrybutów
And dotyczy obu gałęzi (z seo_link i fallback p-id-name)

AC-2: Routing pp_routes matchuje URL z _

Given wzorzec routingu wygenerowany przez Helpers dla produktu z permutacją
When URI to `slug-produktu/20-170_21-175`
Then regex `[0-9_-]+` dopasowuje cały segment permutacji
And `permutation_hash` w wynikowych GET to `20-170_21-175`
And dotyczy obu wariantów (z seo_link i fallback p-id-name)

AC-3: Front konwertuje _ z URL na | przed zapytaniem do bazy

Given GET['permutation_hash'] = "20-170_21-175"
When LayoutEngine renderuje blok PRODUKT
Then ProductRepository::findCached otrzymuje argument "20-170|21-175"
And gdy GET['permutation_hash'] nie istnieje, findCached otrzymuje null

AC-4: Partial atrybutu preselectuje wartość z URL

Given URL produktu z permutation_hash zawierającym parę dla bieżącego atrybutu
When renderuje się templates/shop-product/_partial/product-attribute.php
Then aktywna (checked) jest wartość z URL, nie z is_default
And gdy atrybut nie występuje w hashu, zachowane jest stare zachowanie (is_default)
And blok <script> z fradio_label_click() emitowany jest dla wartości z URL

AC-5: Pełna suita testów zielona

Given wprowadzone zmiany w 4 plikach + 2 nowe/zaktualizowane testy
When uruchomiony jest ./test.ps1
Then wszystkie testy przechodzą (>=836 — 834 obecnych + ≥2 nowe)
And brak warningów PHP

</acceptance_criteria>

Task 1: Zmiana separatora w generatorze feedu i routingu autoload/Domain/Product/ProductRepository.php, autoload/Shared/Helpers/Helpers.php, autoload/front/LayoutEngine.php 1. **autoload/Domain/Product/ProductRepository.php** — w `appendCombinationToXml` (~linie 2372 i 2374): - Zamienić `str_replace('|', '/', $combination['permutation_hash'])` na `str_replace('|', '_', $combination['permutation_hash'])` - Dotyczy OBU gałęzi (seo_link i fallback `p-id-name`) - Najpierw przeczytać metodę i potwierdzić obie wystąpienia przed edycją

2. **autoload/Shared/Helpers/Helpers.php** — w generatorze tras (~linie 694 i 699):
   - Rozszerzyć regex z `'^' . ... . '/([0-9-]+)$'` na `'^' . ... . '/([0-9_-]+)$'`
   - Dotyczy OBU wariantów (seo_link i fallback `p-id-name`)

3. **autoload/front/LayoutEngine.php** — w bloku `// PRODUKT` (~linia 196):
   - Wyciągnąć `permutation_hash` do zmiennej z konwersją `_` → `|`:
     ```php
     $permutation_hash = isset($_GET['permutation_hash']) ? str_replace('_', '|', $_GET['permutation_hash']) : null;
     ```
   - Przekazać `$permutation_hash` do `findCached()` zamiast inline `$_GET['permutation_hash'] ?? null`

Avoid:
- Zmian w `findCached()` lub `permutation_hash` w bazie — separator w DB pozostaje `|`
- Modyfikacji innych metod ProductRepository
- PHP 8.0+ syntaxu (`match`, named args)

- `grep -n "str_replace.*'|'.*'/'" autoload/Domain/Product/ProductRepository.php` — brak wyników (0 wystąpień) - `grep -n "str_replace.*'|'.*'_'" autoload/Domain/Product/ProductRepository.php` — 2 wystąpienia - `grep -n "\[0-9_-\]+" autoload/Shared/Helpers/Helpers.php` — 2 wystąpienia - `grep -n "\[0-9-\]+\\\$" autoload/Shared/Helpers/Helpers.php` — brak (stary wzorzec usunięty z generatora produktów z permutacją) - `grep -n "permutation_hash" autoload/front/LayoutEngine.php` — zmienna wyciągnięta przed `findCached` AC-1, AC-2, AC-3 spełnione Task 2: Preselekcja atrybutu z permutation_hash w partialu templates/shop-product/_partial/product-attribute.php Najpierw przeczytać cały plik partiala (mały, ~kilkadziesiąt linii) i zlokalizować pętlę `foreach` po `values` oraz miejsca używające `$value['is_default']`.

Na początku partiala (przed pętlą po values) dodać:
```php
$forced_value_id = null;
if ( isset( $_GET['permutation_hash'] ) && $_GET['permutation_hash'] !== '' )
{
  $pairs = explode( '|', str_replace( '_', '|', $_GET['permutation_hash'] ) );
  foreach ( $pairs as $pair )
  {
    $parts = explode( '-', $pair );
    if ( count( $parts ) == 2 && (int)$parts[0] === (int)$this -> attribute['id'] )
    {
      $forced_value_id = (int)$parts[1];
      break;
    }
  }
}
```

W pętli foreach po values, przed użyciem flagi `is_default`, policzyć:
```php
$is_active = $forced_value_id !== null
  ? ( (int)$value['id'] === $forced_value_id )
  : (bool)$value['is_default'];
```

Zastąpić WSZYSTKIE użycia `$value['is_default']` w kontekście aktywności (checked, fradio_label_click) zmienną `$is_active`. Nie ruszać `is_default` jeśli używane gdzie indziej semantycznie (np. atrybut metadata).

Avoid:
- Modyfikacji `templates_user/` (potwierdzono: nie istnieje w tym repo)
- Zmian struktury HTML / klas CSS
- PHP 8.0+ syntaxu

- `grep -n "forced_value_id" templates/shop-product/_partial/product-attribute.php` — co najmniej 4 wystąpienia (deklaracja, set, użycie w `$is_active`, użycie w `$is_active`) - `grep -n "is_active" templates/shop-product/_partial/product-attribute.php` — co najmniej 2 wystąpienia (deklaracja + użycie w checked/script) - Manualnie potwierdzić: `checked="checked"` używa `$is_active`, `fradio_label_click(...)` script gate'owany przez `$is_active` AC-4 spełnione Task 3: Unit testy dla regex routingu i generatora linku tests/Unit/Shared/Helpers/HelpersTest.php, tests/Unit/Domain/Product/ProductRepositoryTest.php Najpierw sprawdzić strukturę istniejących testów (szczególnie czy `HelpersTest.php` istnieje — jeśli nie, utworzyć z bootstrapem zgodnym z innymi testami w `tests/Unit/Shared/`).

1. **Helpers — test regex routingu z `_`:**
   - Wywołać generator tras dla produktu z permutacją (jeśli metoda jest publiczna; w przeciwnym razie test integracyjny z mockiem `$mdb` zwracającym permutacje produktu)
   - Zweryfikować że wygenerowany pattern zawiera `[0-9_-]+` zamiast `[0-9-]+`
   - Test: `preg_match` na patternie z URI `slug/20-170_21-175` zwraca true i wyciąga `20-170_21-175` jako capture group
   - Test negatywny: pattern NIE matchuje `slug/20-170/21-175` (stary format ze slashem — chcemy 404, nie przypadkowy match)

2. **ProductRepository::appendCombinationToXml — test separatora `_`:**
   - Może być nieosiągalna metoda private/protected. Strategia A (preferowana): jeśli private, użyć ReflectionMethod do wywołania na instancji z mockiem `$mdb`. Strategia B: jeśli zbyt skomplikowane, dodać minimalny test który wywołuje publiczną metodę feedu z mockiem i sprawdza wygenerowany XML.
   - Mock combination z `permutation_hash = '20-170|21-175'`, `seo_link = 'jakas-fraza'`
   - Asercja: w wygenerowanym XML link zawiera `jakas-fraza/20-170_21-175`, NIE zawiera `20-170/21-175`
   - Drugi test: gałąź fallback (brak `seo_link`) — link `p-{id}-{name}/20-170_21-175`

Trzymać się konwencji: AAA, mock Medoo (`$this->createMock(\medoo::class)`), namespace tests jak w istniejących plikach. Brak PHP 8.0+ syntaxu. Nazwy metod z `test` prefiksem.

- `./test.ps1 tests/Unit/Shared/Helpers/HelpersTest.php` — przechodzi - `./test.ps1 tests/Unit/Domain/Product/ProductRepositoryTest.php` — przechodzi (wszystkie testy, łącznie z nowymi) - `./test.ps1` — pełna suita zielona, count >= 836 AC-5 spełnione (testy zielone, ≥2 nowe testy pokrywające AC-1 i AC-2)

DO NOT CHANGE

• Format permutation_hash w bazie (kolumna pp_shop_product_combinations.permutation_hash pozostaje z separatorem |)
• Sygnatura ProductRepository::findCached() — przyjmuje hash z |
• Inne metody ProductRepository / inne kontrolery / inne partiale
• Plików templates_user/ (nie istnieje w tym repo, akcja po stronie klientów)
• Schemat bazy danych
• .htaccess w roocie (redirecty 301 wykluczone z scope)

SCOPE LIMITS

• Tylko 4 pliki silnika + 2 pliki testów (lista w files_modified)
• Brak automatycznej regeneracji pp_routes — udokumentowane w SUMMARY jako akcja deploy
• Brak czyszczenia cache pp_routes:all w fazie — akcja deploy
• Brak regeneracji google-feed.xml w fazie — akcja deploy
• Brak redirectów 301 ze starych URL-i

- [ ] `./test.ps1` — pełna suita zielona (≥836 testów) - [ ] Brak `str_replace('|', '/', ...)` w ProductRepository (grep) - [ ] `[0-9_-]+` w obu wzorcach Helpers (grep) - [ ] `permutation_hash` wyciągnięte do zmiennej w LayoutEngine z konwersją `_`→`|` - [ ] Partial używa `$is_active` (forced_value_id || is_default) zamiast surowego `is_default` - [ ] Wszystkie 5 AC spełnione

<success_criteria>

• 4 pliki silnika zmienione zgodnie z instrukcją
• 2 nowe / zaktualizowane testy: routing regex + generator XML linku
• Pełna suita testów zielona
• Brak regresji w istniejących testach (834 → ≥836)
• SUMMARY zawiera dokładną listę akcji post-deploy (regen pp_routes, clear cache, regen feedu, resubmit GMC) </success_criteria>

After completion, create `.paul/phases/18-google-feed-permutation-url-fix/18-01-SUMMARY.md` containing: - Co zmienione (lista plików + diff highlights) - Akcje post-deploy do wykonania ręcznie na produkcji (kolejność: regen pp_routes → clear cache pp_routes:all → regen google-feed.xml → resubmit GMC) - Test count delta - Decyzje (override /feature-dev, brak redirectów 301)