165 lines
7.8 KiB
Markdown
165 lines
7.8 KiB
Markdown
---
|
|
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>
|