update

2026-04-22 10:17:26 +02:00
parent 253a78e8c8
commit 21e3f4a41d
15 changed files with 993 additions and 22 deletions
--- a/.paul/phases/02-supplemental-feed-cl1/02-01-PLAN.md
+++ b/.paul/phases/02-supplemental-feed-cl1/02-01-PLAN.md
@@ -0,0 +1,164 @@
+---
+phase: 02-supplemental-feed-cl1
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - autoload/services/class.SupplementalFeed.php
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Dodać kolumnę `custom_label_1` do generowanego supplemental feeda TSV (np. `feeds/supplemental_9.tsv`), tak aby etykieta ta trafiała do Google Merchant Center razem z pozostałymi custom_labels.
+
+## Purpose
+Plan 01-01 (Phase 1) wprowadził kolumnę `custom_label_1` w tabeli `/products` i w bazie danych (migracja 028), ale `services\SupplementalFeed::generate_for_client()` nie został zaktualizowany — feed TSV nadal eksportuje wyłącznie `custom_label_3` i `custom_label_4`. Skutek: wartości `custom_label_1` ustawione w UI nie są propagowane do Merchant Center, co łamie sens wprowadzenia tej kolumny.
+
+## Output
+Zaktualizowany `autoload/services/class.SupplementalFeed.php` — feed `feeds/supplemental_{client_id}.tsv` zawiera kolumnę `custom_label_1` tuż po `google_product_category` (przed `custom_label_3`), z wartością pobraną z `products.custom_label_1`.
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Prior Work
+@.paul/phases/01-products-cl1-column/01-01-SUMMARY.md
+# Phase 1 dodał `products.custom_label_1` (migracja 028) i UI. Ten plan domyka lukę w feedzie TSV.
+
+## Source Files
+@autoload/services/class.SupplementalFeed.php
+@migrations/028_products_custom_label_1.sql
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Nagłówek TSV zawiera custom_label_1
+```gherkin
+Given klient o id = 9 ma wygenerowany feed przez SupplementalFeed::generate_for_client( 9 )
+When otworzę pierwszy wiersz pliku feeds/supplemental_9.tsv
+Then kolumny rozdzielone TAB to dokładnie: id, title, description, google_product_category, custom_label_1, custom_label_3, custom_label_4
+```
+
+## AC-2: Wartość custom_label_1 trafia do wierszy
+```gherkin
+Given produkt klienta 9 ma w DB products.custom_label_1 = "promo_spring"
+When wygeneruję feed przez SupplementalFeed::generate_for_client( 9 )
+Then wiersz odpowiadający temu produktowi w feeds/supplemental_9.tsv ma w 5. kolumnie wartość "promo_spring"
+```
+
+## AC-3: Pusty custom_label_1 nie wymusza eksportu produktu ani nie psuje pustej logiki
+```gherkin
+Given produkt ma wszystkie kolumny (title, description, google_product_category, custom_label_1, custom_label_3, custom_label_4) puste
+When wygeneruję feed
+Then ten produkt zostaje pominięty (nie pojawia się w TSV), zgodnie z dotychczasowym zachowaniem
+And produkty, które mają tylko custom_label_1 ustawione (reszta pusta), są eksportowane z custom_label_1 wypełnionym a pozostałymi kolumnami pustymi
+```
+
+## AC-4: Brak regresji dla custom_label_3 / custom_label_4 / bestseller
+```gherkin
+Given istniejąca logika refresh_bestseller_labels_for_client() nadal działa i ustawia products.custom_label_4
+When wygeneruję feed
+Then custom_label_4 nadal jest w 7. kolumnie TSV (po dodaniu custom_label_1 kolumna przesuwa się z 6 na 7)
+And custom_label_3 jest w 6. kolumnie TSV
+And zwracane statystyki (products_total, products_written, file, labels_updated) zachowują dotychczasową strukturę
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Dodaj custom_label_1 do SELECT, nagłówka, warunku pustki i wiersza TSV</name>
+  <files>autoload/services/class.SupplementalFeed.php</files>
+  <action>
+    W metodzie `generate_for_client( $client_id )`:
+
+    1. Rozszerz SELECT (ok. linia 166) o kolumnę `p.custom_label_1`:
+       ```sql
+       SELECT p.offer_id, p.title, p.description, p.google_product_category,
+              p.custom_label_1, p.custom_label_3, p.custom_label_4
+       ```
+
+    2. Rozszerz warunek WHERE o `p.custom_label_1 IS NOT NULL`:
+       ```sql
+       AND ( p.title IS NOT NULL
+             OR p.description IS NOT NULL
+             OR p.google_product_category IS NOT NULL
+             OR p.custom_label_1 IS NOT NULL
+             OR p.custom_label_3 IS NOT NULL
+             OR p.custom_label_4 IS NOT NULL )
+       ```
+
+    3. Nagłówek TSV (ok. linia 190) — zmień na:
+       `"id\ttitle\tdescription\tgoogle_product_category\tcustom_label_1\tcustom_label_3\tcustom_label_4\n"`
+       Kolejność: custom_label_1 PRZED custom_label_3 (zachowujemy naturalną numerację).
+
+    4. Pętla `foreach`:
+       - Dodaj `$custom_label_1 = trim( (string) ( $row['custom_label_1'] ?? '' ) );`
+       - Uwzględnij `$custom_label_1 === ''` w warunku pomijania produktu
+         (obok title/description/category/cl3/cl4).
+       - Dodaj `$custom_label_1` do tablicy przekazywanej do `implode( "\t", [...] )` — pozycja PRZED `$custom_label_3`.
+
+    Unikaj:
+    - zmiany kolejności pozostałych kolumn (tylko DODAJEMY cl_1 w naturalnym miejscu)
+    - dotykania logiki `refresh_bestseller_labels_for_client()` ani `is_below_exit_for_cooldown()` (poza tym planem)
+    - zmiany sanitize_for_tsv / normalize_feed_offer_id
+  </action>
+  <verify>
+    1. Lokalnie (lub po wgraniu na serwer) uruchom PHP:
+       `php -r "require 'index.php'; print_r( \services\SupplementalFeed::generate_for_client( 9 ) );"`
+       (albo przez UI /feeds: klik "Generuj" dla klienta 9)
+    2. `head -1 feeds/supplemental_9.tsv` → musi być:
+       `id\ttitle\tdescription\tgoogle_product_category\tcustom_label_1\tcustom_label_3\tcustom_label_4`
+    3. Wybierz z DB produkt z ustawionym `custom_label_1`:
+       `SELECT offer_id, custom_label_1 FROM products WHERE client_id = 9 AND custom_label_1 <> '' LIMIT 1;`
+       Znajdź ten `offer_id` w TSV — 5. kolumna musi zawierać wartość z DB.
+    4. Sanity check: liczba wierszy TSV ≈ poprzedniej generacji (plan nie powinien zmienić products_written poza przypadkami, gdzie TYLKO custom_label_1 jest wypełniony).
+  </verify>
+  <done>AC-1, AC-2, AC-3, AC-4 spełnione: feed dla klienta 9 zawiera custom_label_1 w nagłówku i wierszach, pozostałe kolumny bez regresji.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `refresh_bestseller_labels_for_client()`, `is_below_exit_for_cooldown()`, `get_client_bestseller_settings()` — logika bestsellera jest poza scope.
+- `sanitize_for_tsv()`, `normalize_feed_offer_id()` — bez zmian.
+- `migrations/028_products_custom_label_1.sql` — migracja już wdrożona w Phase 1.
+- `autoload/controls/class.Products.php`, `templates/products/main_view.php` — UI produktów jest poza scope.
+- Kolejność i nazwy pozostałych kolumn TSV (id, title, description, google_product_category, custom_label_3, custom_label_4) — tylko DODAJEMY custom_label_1 między `google_product_category` a `custom_label_3`.
+
+## SCOPE LIMITS
+- Plan dotyczy WYŁĄCZNIE pliku `autoload/services/class.SupplementalFeed.php`.
+- Nie dodajemy nowych etykiet (custom_label_0, 2) — to inne zadanie, jeśli kiedyś będzie.
+- Nie wymuszamy automatycznej regeneracji feedów dla wszystkich klientów; regeneracja zajdzie przy najbliższym naturalnym wywołaniu z UI /feeds lub crona (o ile istnieje).
+- Nie modyfikujemy formatu zwracanego przez `generate_for_client()` (klucze tablicy wynikowej pozostają: products_total, products_written, file, labels_updated).
+
+</boundaries>
+
+<verification>
+Przed zamknięciem planu:
+- [ ] `php -l autoload/services/class.SupplementalFeed.php` → No syntax errors
+- [ ] Generacja feedu dla klienta 9 kończy się bez wyjątku
+- [ ] Nagłówek TSV zawiera `custom_label_1` w 5. kolumnie
+- [ ] Przynajmniej jeden wiersz TSV ma wypełnione `custom_label_1` (produkt z ustawioną etykietą w DB)
+- [ ] Wszystkie AC spełnione
+</verification>
+
+<success_criteria>
+- Zmodyfikowany jeden plik: `autoload/services/class.SupplementalFeed.php`
+- Feed `feeds/supplemental_9.tsv` zawiera kolumnę `custom_label_1` z poprawnymi wartościami
+- Brak błędów PHP (lint + runtime)
+- Brak regresji w dotychczasowych kolumnach / statystykach zwrotnych
+</success_criteria>
+
+<output>
+Po ukończeniu utwórz `.paul/phases/02-supplemental-feed-cl1/02-01-SUMMARY.md`.
+</output>
--- a/.paul/phases/02-supplemental-feed-cl1/02-01-SUMMARY.md
+++ b/.paul/phases/02-supplemental-feed-cl1/02-01-SUMMARY.md
@@ -0,0 +1,111 @@
+---
+phase: 02-supplemental-feed-cl1
+plan: 01
+subsystem: feeds
+tags: [merchant-center, supplemental-feed, tsv, custom-label, google-ads]
+
+requires:
+  - phase: 01-products-cl1-column
+    provides: kolumna `products.custom_label_1` w DB (migracja 028), UI edycji w /products
+provides:
+  - Eksport `custom_label_1` do supplemental feed TSV (`feeds/supplemental_{client_id}.tsv`)
+  - Uzupełnienie łańcucha propagacji etykiety: UI → DB → feed → Google Merchant Center
+affects: [merchant-center, google-ads-labels]
+
+tech-stack:
+  added: []
+  patterns: []
+
+key-files:
+  created: []
+  modified:
+    - autoload/services/class.SupplementalFeed.php
+
+key-decisions:
+  - "Kolumna custom_label_1 w TSV umieszczona PRZED custom_label_3 (naturalna numeracja), a nie na końcu — łatwiejszy diff i zgodność z konwencją GMC"
+
+patterns-established: []
+
+duration: ~5min
+started: 2026-04-22T00:00:00Z
+completed: 2026-04-22T00:00:00Z
+---
+
+# Phase 2 Plan 01: Supplemental Feed CL1 Summary
+
+**Supplemental feed TSV eksportuje teraz `custom_label_1` jako 5. kolumnę, domykając propagację etykiety z UI /products do Merchant Center.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~5 min |
+| Started | 2026-04-22 |
+| Completed | 2026-04-22 |
+| Tasks | 1/1 |
+| Files modified | 1 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Nagłówek TSV zawiera custom_label_1 | Pass | Header: `id\ttitle\tdescription\tgoogle_product_category\tcustom_label_1\tcustom_label_3\tcustom_label_4` |
+| AC-2: Wartość custom_label_1 trafia do wierszy | Pass | Użytkownik zweryfikował na produkcji — plik `feeds/supplemental_9.tsv` otwarty w IDE z poprawną zawartością |
+| AC-3: Pusta logika rozszerzona o custom_label_1 | Pass | Warunek pomijania produktu uwzględnia `$custom_label_1 === ''` obok pozostałych; produkty z samym CL1 są eksportowane |
+| AC-4: Brak regresji CL3/CL4/bestseller | Pass | Kolejność kolumn przesunięta zgodnie z planem (CL3 → pos 6, CL4 → pos 7), logika `refresh_bestseller_labels_for_client()` nietknięta |
+
+## Accomplishments
+
+- Zamknięta luka propagacji: `products.custom_label_1` (Phase 1) → TSV feed → GMC
+- Użytkownik potwierdził działanie przez inspekcję `feeds/supplemental_9.tsv` na produkcji (po deployu FTP i regeneracji z UI /feeds)
+- Zero regresji w dotychczasowych kolumnach i w logice bestseller
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `autoload/services/class.SupplementalFeed.php` | Modified | Dodano `custom_label_1` do SELECT (+WHERE), nagłówka TSV, warunku pustki w foreach i tablicy `implode` zapisu wiersza (+6/-4 linie) |
+| `feeds/supplemental_9.tsv` | Regenerated (runtime artefakt) | Plik artefaktowy — regenerowany przez UI /feeds po deployu |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| CL1 przed CL3 w TSV (pos 5) zamiast na końcu | Naturalna numeracja, mniejsze ryzyko pomyłek przy czytaniu feedu, zgodność z porządkiem atrybutów GMC | Kolumny CL3/CL4 przesunęły się o 1 w prawo — udokumentowane w AC-4, nie łamie parsera GMC (feed jest z nagłówkiem) |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 0 | — |
+| Scope additions | 0 | — |
+| Deferred | 0 | — |
+
+**Total impact:** Brak odchyleń — plan wykonany 1:1.
+
+### Deferred Items
+
+Brak.
+
+## Issues Encountered
+
+Brak.
+
+## Next Phase Readiness
+
+**Ready:**
+- Łańcuch propagacji custom_label_1 kompletny (UI ↔ DB ↔ feed TSV ↔ GMC)
+- `SupplementalFeed::generate_for_client()` spójny z kolumnami DB dodanymi w Phase 1
+
+**Concerns:**
+- Jeśli kiedyś pojawi się `custom_label_0` / `custom_label_2` → trzeba dodać je analogicznie (obecnie pomijane, zgodnie ze scope)
+- Feed jest generowany ad-hoc z UI /feeds — brak automatycznej regeneracji po zmianie etykiety; do rozważenia cron lub hook po edycji produktu
+
+**Blockers:**
+- Brak
+
+---
+*Phase: 02-supplemental-feed-cl1, Plan: 01*
+*Completed: 2026-04-22*