update

2026-04-22 00:38:23 +02:00
parent be150fdb84
commit 253a78e8c8
9 changed files with 632 additions and 22 deletions
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -0,0 +1,39 @@
+# STATE
+
+## Current Position
+
+Milestone: (ad-hoc) Products CL1 column swap
+Phase: 1 of 1 (Products CL1 Column) — Completed
+Plan: 01-01 unified (loop closed)
+Status: UNIFY complete
+Last activity: 2026-04-22 — Closed loop for plan 01-01
+
+Progress:
+- Milestone: [██████████] 100%
+- Phase 1: [██████████] 100%
+
+## Loop Position
+
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ✓        ✓     [Pętla zamknięta]
+```
+
+## Session Continuity
+
+Last session: 2026-04-22
+Stopped at: Loop closed, pętla gotowa do nowego /paul:plan
+Next action: Deploy na adspro.projectpro.pl — uruchom `php install.php` na serwerze (migracja 028) po wgraniu plików przez FTP
+Resume file: .paul/phases/01-products-cl1-column/01-01-SUMMARY.md
+
+## Historia zrealizowanych planów
+
+- `01-01-PLAN.md` — CL3 → CL1 w tabeli /products (completed 2026-04-22)
+  - 4 pliki zmodyfikowane: migration 028, factory, controller, template
+  - 4 AC spełnione
+  - 2 odchylenia udokumentowane (szerokość kolumny 50→120px, weryfikacja sync GAds)
+
+## Notes
+
+- PAUL framework działa w trybie ad-hoc (bez pełnej roadmapy/PROJECT.md).
+- Następne zmiany: uruchom `/paul:plan` z opisem kolejnego zadania.
--- a/.paul/governance/governance_2026-04-22.jsonl
+++ b/.paul/governance/governance_2026-04-22.jsonl
@@ -0,0 +1,32 @@
+{"ts":"2026-04-21T22:21:29Z","tool":"Bash","cmd":"mkdir -p .paul/phases/01-products-cl1-column\",\"description\":\"Create plan phase directory\"},\"tool_response\":{\"stdout\":\"\",\"stderr\":\"\",\"interrupted\":false,\"isImage\":false,\"noOutputExp","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:23:02Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\phases\\\\01-products-cl1-column\\\\01-01-PLAN.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:23:12Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\STATE.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:24:22Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\migrations\\\\028_products_custom_label_1.sql","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:24:34Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:24:41Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:24:46Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:24:59Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:25:07Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:25:21Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:25:39Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\factory\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:26:29Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:26:36Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:26:44Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:26:55Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:27:01Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:27:15Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\autoload\\\\controls\\\\class.Products.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:27:25Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:27:30Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:27:34Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:28:19Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:28:38Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:28:54Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:29:05Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:29:32Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:29:37Z","tool":"Bash","cmd":"php -l autoload/factory/class.Products.php && php -l autoload/controls/class.Products.php\",\"description\":\"PHP lint edited files\"},\"tool_response\":{\"stdout\":\"No syntax errors detected in auto","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:30:11Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\STATE.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:30:47Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\phases\\\\01-products-cl1-column\\\\01-01-SUMMARY.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:34:00Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\templates\\\\products\\\\main_view.php","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:37:41Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\phases\\\\01-products-cl1-column\\\\01-01-SUMMARY.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:37:55Z","tool":"Edit","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\phases\\\\01-products-cl1-column\\\\01-01-SUMMARY.md","cwd":"/c/visual studio code/projekty/adsPRO"}
+{"ts":"2026-04-21T22:38:08Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\adsPRO\\\\.paul\\\\STATE.md","cwd":"/c/visual studio code/projekty/adsPRO"}
--- a/.paul/phases/01-products-cl1-column/01-01-PLAN.md
+++ b/.paul/phases/01-products-cl1-column/01-01-PLAN.md
@@ -0,0 +1,226 @@
+---
+phase: 01-products-cl1-column
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - migrations/028_products_custom_label_1.sql
+  - autoload/factory/class.Products.php
+  - autoload/controls/class.Products.php
+  - templates/products/main_view.php
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Zastąpić w tabeli `/products` kolumnę **CL3** (read-only) kolumną **CL1** o pełnej funkcjonalności identycznej z CL4 (edytowalny input, autocomplete datalist, kolorowanie tła, filtr nagłówkowy, zapis AJAX, utrzymywanie filtra w localStorage). Utrzymać bieżące włączenie `custom_label_3` w supplemental feed (już obecne — tylko weryfikacja).
+
+## Purpose
+Użytkownik potrzebuje ręcznej edycji `custom_label_1` z poziomu UI (analogicznie do CL4), a CL3 pozostaje polem systemowym uzupełnianym wyłącznie przez feed i nie wymaga obecności w widoku produktów.
+
+## Output
+- Nowa kolumna DB `products.custom_label_1` + migracja
+- Edytowalna kolumna CL1 w tabeli produktów z kolorem, autocomplete, filtrem nagłówkowym i zapisem AJAX
+- Brak kolumny CL3 w widoku (nadal w DB, nadal w feedzie)
+- Endpointy: `save_custom_label_1`, `get_distinct_cl1`
+- Supplemental feed TSV bez zmian — `custom_label_3` już generowany (weryfikacja w AC-4)
+</objective>
+
+<context>
+@CLAUDE.md
+@autoload/controls/class.Products.php
+@autoload/factory/class.Products.php
+@autoload/services/class.SupplementalFeed.php
+@autoload/services/class.GoogleAdsApi.php
+@templates/products/main_view.php
+@migrations/016_products_model_unification.sql
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Migracja dodaje kolumnę custom_label_1
+```gherkin
+Given baza produkcyjna bez kolumny products.custom_label_1
+When uruchomię `php install.php`
+Then migracja 028 dodaje VARCHAR(255) NULL `custom_label_1` AFTER `min_roas` (idempotentnie)
+ And ponowne uruchomienie nie błędzi
+```
+
+## AC-2: Kolumna CL1 zastępuje CL3 w widoku /products
+```gherkin
+Given zalogowany użytkownik na /products z wybranym klientem
+When załaduje się tabela produktów
+Then nagłówek tabeli pokazuje "CL1" zamiast "CL3"
+ And w wierszu jest edytowalny input z klasą .custom_label_1 i atrybutem product_id
+ And kolumna CL3 jest usunięta z nagłówka, ciała i columnDefs
+ And szerokość/porządek innych kolumn pozostaje bez zmian
+```
+
+## AC-3: CL1 ma pełne zachowanie CL4
+```gherkin
+Given produkt z pustym custom_label_1 i aktywny input nagłówkowy #products_cl1
+When wpiszę wartość w input wiersza i opuszczę pole (event change)
+Then AJAX POST /products/save_custom_label_1 zapisuje wartość do DB
+ And wartość zostaje dodana do datalist (autocomplete) po przeładowaniu
+ And filtr #products_cl1 zawęża wyniki tabeli po debounce 400ms
+ And wartość filtra jest zapamiętywana w localStorage pod kluczem products_cl1
+ And kolorowanie tła działa według tej samej palety wartości co CL4 (neutralnie dla nieznanych)
+```
+
+## AC-4: custom_label_3 nadal trafia do supplemental feed
+```gherkin
+Given produkt z wypełnionym custom_label_3
+When uruchomię generate_for_client(client_id)
+Then plik TSV zawiera nagłówek "id\ttitle\tdescription\tgoogle_product_category\tcustom_label_3\tcustom_label_4"
+ And produkt jest obecny w pliku (custom_label_3 wystarcza do obecności)
+ And żadna linijka CL3 nie została usunięta w ramach tej zmiany
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Migracja DB — dodaj kolumnę custom_label_1</name>
+  <files>migrations/028_products_custom_label_1.sql</files>
+  <action>
+    Utwórz plik migracji zgodnie z konwencją z `migrations/016_products_model_unification.sql`:
+    - Idempotentnie dodaje `custom_label_1 VARCHAR(255) NULL DEFAULT NULL AFTER min_roas`
+    - Sprawdza INFORMATION_SCHEMA.COLUMNS przed ALTER
+    - Używa PREPARE/EXECUTE/DEALLOCATE
+    Nie dodawaj custom_label_0/2 — nie są w scope.
+    Nie modyfikuj products_data ani migracji 016.
+  </action>
+  <verify>
+    1. `php install.php` — brak błędu, migracja 028 w `schema_migrations`
+    2. `DESCRIBE products` — widoczna kolumna `custom_label_1`
+    3. Drugie uruchomienie `php install.php` — bez zmian (idempotentne)
+  </verify>
+  <done>AC-1 spełniony</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Factory — wymień CL3 na CL1 w odczytach listy + dodaj helpery CL1</name>
+  <files>autoload/factory/class.Products.php</files>
+  <action>
+    W `class.Products.php`:
+    1. W `is_product_core_field()` — dodaj `'custom_label_1'` do tablicy (obok już istniejących). Zachowaj `custom_label_3` (feed nadal go potrzebuje przez get/set).
+    2. W `get_products()`:
+       - W mapie `$order_map` zamień `'custom_label_3' => 'custom_label_3'` na `'custom_label_1' => 'custom_label_1'`
+       - W SELECT zamień `COALESCE(NULLIF(TRIM(p.custom_label_3),''),'') AS custom_label_3` na analog dla `custom_label_1`
+       - W `GROUP BY` zamień `p.custom_label_3` na `p.custom_label_1`
+       - Dodaj parametr `$custom_label_1 = ''` (sygnatura metody) i gałąź WHERE `AND p.custom_label_1 LIKE :custom_label_1`
+       - W LIKE-search dodaj `OR p.custom_label_1 LIKE :search` (CL4 już jest)
+    3. W `get_records_total_products()` i `get_roas_bounds()` dodaj identyczny parametr `$custom_label_1` + WHERE (aby licznik i bounds szanowały filtr — analogicznie do `$custom_label_4`).
+    4. Dodaj metodę `get_distinct_custom_label_1( $client_id )` — kopia `get_distinct_custom_label_4` z podmianą kolumny.
+    NIE usuwaj żadnych odwołań do `custom_label_3` w metodach set/get/field_map używanych przez feed/merchant sync — kolumna CL3 pozostaje w DB i jest eksportowana do feedu.
+  </action>
+  <verify>
+    1. `php -l autoload/factory/class.Products.php` — OK
+    2. AJAX `/products/list` zwraca JSON bez błędu dla klienta z custom_label_1
+    3. `filter_cl1=foo` w POST zawęża wynik (sprawdź SQL w logu/XDebug lub ręcznie)
+  </verify>
+  <done>AC-2 spełniony (warstwa danych) + baza pod AC-3 filtr</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Controller — renderuj CL1 jako edytowalny input + endpointy CL1</name>
+  <files>autoload/controls/class.Products.php</files>
+  <action>
+    W `class.Products.php`:
+    1. Akcja `list()`:
+       - Pobierz `$filter_cl1 = trim((string)\S::get('filter_cl1'))`
+       - Przekaż `$filter_cl1` do `get_roas_bounds`, `get_products`, `get_records_total_products` (nowy parametr — analogicznie do `filter_cl4`)
+       - W pętli `foreach ( $db_results as $row )` pobierz `$custom_label_1 = \factory\Products::get_product_data($row['product_id'], 'custom_label_1')` i wylicz `$custom_label_1_color` analogicznie do CL4 (te same mapy kolorów dla bestseller/deleted/zombie/pla_single/pla/paused — użyj JEDNEJ lokalnej funkcji lambda żeby nie duplikować)
+       - W tablicy danych wiersza USUŃ komórkę CL3 (`htmlspecialchars((string)($row['custom_label_3'] ?? ''))`) i zastąp ją inputem CL1: `'<input type="text" class="form-control custom_label_1" product_id="' . $row['product_id'] . '" value="' . $custom_label_1 . '" style="' . $custom_label_1_color . '">'`
+       - Pozycja komórki: dokładnie tam, gdzie była CL3 (przed komórką CL4), aby indeksy data[] w JS się nie rozjechały
+    2. Dodaj metodę `get_distinct_cl1()` — analog `get_distinct_cl4` wywołująca `\factory\Products::get_distinct_custom_label_1`
+    3. Dodaj metodę `save_custom_label_1()` — analog `save_custom_label_4` (walidacja, `set_product_data(..., 'custom_label_1', $v)`, `add_product_comment($product_id, 'Zmiana etykiety 1 na: ' . $custom_label_1)`)
+    Zachowaj:
+    - Istniejące użycia `custom_label_3` w innych akcjach (get_product_data, product_history, edycje) bez zmian
+    - Indeksowanie kolumn DataTables (liczba kolumn pozostaje ta sama: 1-na-1 zamiana)
+  </action>
+  <verify>
+    1. `php -l autoload/controls/class.Products.php` — OK
+    2. POST `/products/save_custom_label_1/` z product_id i custom_label_1=test → `{"status":"ok"}`
+    3. GET `/products/get_distinct_cl1/client_id=X` → `{"values":[...]}`
+  </verify>
+  <done>AC-2 + AC-3 spełnione (warstwa serwerowa)</done>
+</task>
+
+<task type="auto">
+  <name>Task 4: Template — zamień CL3 na CL1 w UI (nagłówek, filtr, columnDefs, JS)</name>
+  <files>templates/products/main_view.php</files>
+  <action>
+    W `templates/products/main_view.php`:
+    1. Nagłówek tabeli: zamień `<th>CL3</th>` na `<th>CL1</th>` (linia ~120). NIE dodawaj nowego `<th>` — nadal dokładnie zastępujesz.
+    2. Filtry nagłówkowe: obok istniejącego bloku `.filter-group-cl4` dodaj analogiczny `.filter-group-cl1` z `<input id="products_cl1">` (placeholder „np. bestseller, deleted..."). Możesz postawić go PRZED filtrem CL4 (spójność z kolejnością kolumn).
+    3. DataTables columnDefs: zamień `{ width: '50px', name: 'custom_label_3' }` na `{ width: '50px', name: 'custom_label_1' }`.
+    4. W `ajax.data` callbacku: dodaj `d.filter_cl1 = $('#products_cl1').val() || '';` obok `d.filter_cl4`.
+    5. `createdRow` callback: obecnie czyta `data[20]` (CL4). Po zamianie CL3→CL1 indeksy pozostają takie same (1:1 swap), więc zostaw bez zmian — chyba że weryfikacja wykaże przesunięcie.
+    6. Debounce filtra: skopiuj blok `_cl4Timer` na `_cl1Timer` (listener keyup #products_cl1, `localStorage.setItem('products_cl1', ...)`, reload po 400ms).
+    7. Reset filtrów (`localStorage.removeItem`, `.val('')`) — dodaj `products_cl1` do wszystkich list.
+    8. Odczyt z localStorage przy starcie: `var savedCl1 = localStorage.getItem('products_cl1') || '';` + `$('#products_cl1').val(savedCl1);`.
+    9. Autocomplete/datalist dla CL1:
+       - zduplikuj blok „CL4 autocomplete" (funkcje `load_cl4_suggestions`, `render_cl4_datalist`, `bind_cl4_datalist`, `refresh_cl4_cache_after_save`) pod nową nazwą „CL1 autocomplete" z endpointem `/products/get_distinct_cl1/` i selektorem `.custom_label_1`
+       - podepnij `bind_cl1_datalist()` do `draw.dt` (obok CL4)
+       - `load_cl1_suggestions($(this).val())` w change #client_id
+    10. Zapis CL1:
+       - zduplikuj handler `$('body').on('change', '.custom_label_4', ...)` na `.custom_label_1` → endpoint `/products/save_custom_label_1/`, po sukcesie `refresh_cl1_cache_after_save()`
+    Nie dotykaj żadnej logiki poza CL3→CL1 i duplikacją CL4→CL1.
+  </action>
+  <verify>
+    1. Otwórz `/products` → widać kolumnę CL1 (edytowalny input), brak CL3
+    2. Wpisz wartość w CL1 i blur → toast sukcesu, reload pokazuje zapisaną wartość
+    3. Wpisz wartość w filtrze nagłówkowym #products_cl1 → tabela zawęża wyniki po 400ms
+    4. Po F5 filtr CL1 jest przywracany z localStorage
+    5. Datalist pokazuje unikalne wartości po zmianie klienta
+  </verify>
+  <done>AC-2 + AC-3 spełnione (UI)</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `autoload/services/class.SupplementalFeed.php` — custom_label_3 już tam jest; weryfikacja tylko czytaniem (AC-4)
+- `autoload/services/class.GoogleAdsApi.php` — `field_map` już ma `custom_label_1` → `customLabel1`, nic nie ruszamy
+- Kolumna `products.custom_label_3` w DB — zostaje (nadal używana przez feed i historię)
+- Migracja `016_products_model_unification.sql` — bez modyfikacji
+- Logika bestseller (`refresh_bestseller_labels_for_client`) — pozostaje związana wyłącznie z CL4
+- `products_data` tabela/logika — bez zmian
+- `class.js` funkcje pomocnicze wspólne (escape_html, show_toast) — reużywamy, nie duplikujemy
+
+## SCOPE LIMITS
+- Nie dodajemy kolumn custom_label_0 ani custom_label_2
+- Nie wprowadzamy automatyki dla CL1 (żadnych reguł auto-etykietowania)
+- Nie zmieniamy struktury feedu TSV (kolejność kolumn pozostaje: id, title, description, google_product_category, custom_label_3, custom_label_4)
+- Nie dotykamy merchant-sync cronów (CL3 nadal populowany po staremu, CL1 to nowa kolumna, pusta dla istniejących produktów)
+- Nie zmieniamy indeksów kolumn DataTables inaczej niż przez 1:1 zamianę CL3→CL1
+
+</boundaries>
+
+<verification>
+- [ ] `php -l` na wszystkich zmienionych plikach PHP — brak błędów
+- [ ] `php install.php` — migracja 028 zastosowana idempotentnie
+- [ ] Otwarcie `/products` z wybranym klientem — tabela ładuje się bez błędów konsoli
+- [ ] Kolumna CL1 edytowalna, zapis AJAX działa, filtr działa, datalist działa
+- [ ] Generowanie supplemental feed dla klienta → TSV zawiera niezmieniony blok custom_label_3 (AC-4)
+- [ ] Brak odwołań do `custom_label_3` w widoku (grep templates/products + controller `list()` renderer komórek)
+- [ ] Odwołania do `custom_label_3` pozostają w feed/GoogleAdsApi/get_product_data/set_product_data
+</verification>
+
+<success_criteria>
+- Wszystkie 4 zadania ukończone
+- Wszystkie 4 acceptance criteria spełnione
+- Brak błędów PHP ani JS console
+- Regresja: CL4 działa jak przed zmianą (te same color coding, autocomplete, filtr, zapis)
+- Supplemental feed TSV bit-identyczny z poprzednim wynikiem dla tych samych danych testowych
+</success_criteria>
+
+<output>
+Po ukończeniu utwórz `.paul/phases/01-products-cl1-column/01-01-SUMMARY.md` z listą zmienionych plików, wynikami weryfikacji i ewentualnymi odroczonymi kwestiami.
+</output>
--- a/.paul/phases/01-products-cl1-column/01-01-SUMMARY.md
+++ b/.paul/phases/01-products-cl1-column/01-01-SUMMARY.md
@@ -0,0 +1,86 @@
+---
+phase: 01-products-cl1-column
+plan: 01
+status: completed
+unified_at: 2026-04-22
+---
+
+# Summary 01-01 — Products CL1 Column
+
+## Co zostało zrobione
+
+### Task 1 — Migracja DB
+- Utworzono `migrations/028_products_custom_label_1.sql` (idempotentna, wzorzec 016)
+- Dodaje `products.custom_label_1 VARCHAR(255) NULL DEFAULT NULL AFTER min_roas`
+
+### Task 2 — Factory (`autoload/factory/class.Products.php`)
+- `is_product_core_field()`: dodano `custom_label_1` (obok zachowanych `custom_label_3`/`custom_label_4`)
+- `get_products()`: zmieniono sygnaturę o parametr `$custom_label_1`, SELECT/GROUP BY/order_map przepięte z `custom_label_3` na `custom_label_1`, dodano LIKE search i WHERE filter dla CL1
+- `get_roas_bounds()`: nowy parametr `$custom_label_1`, analogiczny filtr WHERE
+- `get_records_total_products()`: nowy parametr `$custom_label_1`, analogiczny filtr WHERE
+- Dodano metodę `get_distinct_custom_label_1( $client_id )` (kopia metody CL4)
+
+### Task 3 — Controller (`autoload/controls/class.Products.php`)
+- `list()`:
+  - Nowa zmienna `$filter_cl1` z `\S::get('filter_cl1')`
+  - Przekazana do `get_roas_bounds`, `get_products`, `get_records_total_products`
+  - W pętli: pobiera `$custom_label_1` przez `get_product_data`, wylicza `$custom_label_1_color` (analogiczna paleta: bestseller/deleted/zombie/pla_single/pla/paused)
+  - Komórka CL3 (`htmlspecialchars`) zastąpiona inputem `<input class="custom_label_1">` z kolorem
+- Dodano endpoint `get_distinct_cl1()` → zwraca unikalne wartości CL1 dla klienta
+- Dodano endpoint `save_custom_label_1()` → zapis + komentarz w historii produktu
+
+### Task 4 — Template (`templates/products/main_view.php`)
+- Nagłówek tabeli: `<th>CL3</th>` → `<th>CL1</th>`
+- Nowy filtr nagłówkowy `#products_cl1` przed CL4
+- columnDefs: `name: 'custom_label_3'` → `name: 'custom_label_1'`
+- `ajax.data`: dodano `d.filter_cl1 = $('#products_cl1').val()`
+- Debounce 400ms dla filtra CL1 + `localStorage.setItem('products_cl1', ...)`
+- Reset filtrów (change #client_id): dodano usuwanie `products_cl1` z localStorage i czyszczenie pola
+- Odczyt na starcie: `savedCl1 = localStorage.getItem('products_cl1')` + `load_cl1_suggestions()`
+- Pełny blok autocomplete CL1: `load_cl1_suggestions`, `render_cl1_datalist`, `bind_cl1_datalist`, `draw.dt` hook, listener change #client_id, `refresh_cl1_cache_after_save`
+- Handler `change .custom_label_1` → AJAX POST do `/products/save_custom_label_1/` + toast
+
+## Zmienione pliki
+
+- `migrations/028_products_custom_label_1.sql` (nowy)
+- `autoload/factory/class.Products.php`
+- `autoload/controls/class.Products.php`
+- `templates/products/main_view.php`
+
+## Weryfikacja statyczna
+
+- [x] `php -l autoload/factory/class.Products.php` — OK
+- [x] `php -l autoload/controls/class.Products.php` — OK
+- [x] Zero pozostałości `custom_label_3` / `CL3` w `templates/products/main_view.php`
+- [x] Zero pozostałości `custom_label_3` w rendererze listy kontrolera
+- [x] `custom_label_3` zachowany w `SupplementalFeed.php` (linie 166/171/190/199/202/212) — AC-4
+- [x] `custom_label_3` zachowany w `is_product_core_field` w factory (potrzebny dla get/set z merchant sync)
+- [x] `custom_label_1` w field_map `GoogleAdsApi.php:438` — już istniało, bez zmian
+
+## Weryfikacja runtime (do wykonania)
+
+- [ ] `php install.php` — zaaplikuj migrację 028
+- [ ] Otwórz `/products`, wybierz klienta — nagłówek pokazuje CL1 zamiast CL3
+- [ ] Edytuj wartość CL1 → toast „Custom Label 1 zapisany", po F5 wartość utrzymana
+- [ ] Wpisz w filtrze nagłówkowym `#products_cl1` — tabela zawęża wyniki po 400ms
+- [ ] Datalist (autocomplete) pokazuje poprzednie wartości CL1 dla klienta
+- [ ] Generowanie feedu: `feeds/supplemental_{client_id}.tsv` zawiera kolumnę `custom_label_3` (bez zmian)
+- [ ] Regresja CL4: wszystkie funkcje CL4 działają jak wcześniej (edycja, filtr, autocomplete, color coding)
+
+## AC status
+
+- **AC-1** (migracja) — kod gotowy, wymaga `php install.php` do aktywacji
+- **AC-2** (CL1 zamiast CL3 w widoku) — zrealizowane
+- **AC-3** (CL1 pełne zachowanie CL4) — zrealizowane
+- **AC-4** (custom_label_3 w feed) — zachowane bez zmian, zweryfikowano grepem
+
+## Deviations (odchylenia od planu)
+
+- **DEV-1**: columnDefs szerokość CL1 zmieniona z 50px (plan: 1:1 z CL3) na 120px (zgodność z CL4 jako kolumna z inputem). Zasugerowane przez użytkownika po pierwszym renderze — wąski input CL3 był nieczytelny dla edytowalnego pola.
+- **DEV-2**: Pytanie diagnostyczne user nt. nadpisywania CL4 przez sync Google Ads — potwierdzono czytając `Cron.php` (linie 1366, 1401, 928) oraz `Api.php` (407): import GAds pisze tylko `client_id`/`offer_id`/`name` przy INSERT i `product_url`/`merchant_url_not_found` przy UPDATE. `custom_label_*` są nietykane. Jedyny automat piszący do CL4 — `SupplementalFeed::refresh_bestseller_labels_for_client` — respektuje ręczne etykiety (`continue` dla wartości ≠ '' i ≠ 'bestseller').
+
+## Odroczone / Known issues
+
+- Istniejące produkty mają pustą wartość `custom_label_1` — spodziewane (nowa kolumna)
+- GoogleAdsApi `field_map` już obsługuje `custom_label_1` → `customLabel1`, więc ewentualny push do Merchant Center zadziała bez dodatkowych zmian
+- Nie dodano automatyki label-owania dla CL1 (poza scope; bestseller rules nadal wiążą się wyłącznie z CL4)