adsPRO/.paul/phases/09-unit-pricing/09-01-PLAN.md

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

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
09-unit-pricing	01	execute	1		migrations/YYYY-MM-DD_add_unit_pricing.sql api.php feeds/ docs/api-public-product-management.md	true	off

## Goal Wdrozyc w adsPRO obsluge `unit_pricing_measure` oraz `unit_pricing_base_measure` dla produktow i feedu GMC.

Purpose

Uzupelnienie danych unit pricing poprawia jakosc feedu Merchant Center i eliminuje warningi missing_potentially_required_attribute dla kategorii beauty/cosmetics.

Output

Migracja DB, nowe endpointy API, aktualizacja generatora feedu i dokumentacji publicznej API.

- **Doprecyzowanie** - Brak pytan doprecyzowujacych; `docs/unit-price.md` definiuje zakres, walidacje i AC. -> Odpowiedz: plan obejmuje tylko zmiany po stronie adsPRO, bez implementacji zewnetrznych skryptow agenta z `D:\google ads\...`.

Project Context

@.paul/STATE.md @docs/unit-price.md

Source Files

@api.php @migrations/ @feeds/ @docs/api-public-product-management.md

Notes

• .paul/PROJECT.md i .paul/ROADMAP.md nie istnieja w tym projekcie.
• .paul/codebase/architecture.md i .paul/codebase/db_schema.md nie istnieja; kontekst architektury opieramy o docs/unit-price.md i aktualny kod.
• .paul/SPECIAL-FLOWS.md nie istnieje, wiec sekcja skills jest pominieta.

<acceptance_criteria>

AC-1: Schemat danych wspiera unit pricing

Given baza danych adsPRO przed migracja nie ma kolumn unit pricing
When migracja unit pricing zostanie uruchomiona
Then tabela products zawiera kolumny unit_pricing_measure, unit_pricing_base_measure, unit_pricing_changed_at
And mozliwe jest wydajne filtrowanie produktow bez unit_pricing

AC-2: API zapisuje i odczytuje unit pricing z walidacja

Given poprawne dane api_key, client_id i offer_id
When wywolam action=product_unit_pricing_set z poprawnym formatem i zgodna jednostka
Then API zapisuje measure, base_measure i unit_pricing_changed_at oraz dodaje wpis do products_comments
And zwraca HTTP 200 z zapisanymi wartosciami

AC-3: API odrzuca bledne dane unit pricing

Given request action=product_unit_pricing_set z niepoprawnym formatem albo rozna jednostka measure/base
When API przetwarza request
Then zwraca HTTP 422 z czytelnym komunikatem bledu
And nie zapisuje niepoprawnych danych w products

AC-4: Feed GMC publikuje pola tylko gdy kompletne

Given produkt ma uzupelnione unit_pricing_measure i unit_pricing_base_measure
When generator feedu tworzy XML
Then feed zawiera tagi g:unit_pricing_measure i g:unit_pricing_base_measure
And gdy ktorekolwiek pole jest puste, oba tagi sa pomijane

AC-5: Dostepny listing brakujacych unit pricing (zakres opcjonalny)

Given action=products_get_missing_unit_pricing jest wlaczony
When wywolam endpoint z client_id i opcjonalnym filtrem kategorii
Then API zwraca liste produktow bez unit_pricing posortowana po clicks

</acceptance_criteria>

Task 1: Dodaj migracje i reguly danych dla unit pricing migrations/YYYY-MM-DD_add_unit_pricing.sql Przygotuj migracje rozszerzajaca `products` o pola: - `unit_pricing_measure` (VARCHAR 64, NULL), - `unit_pricing_base_measure` (VARCHAR 64, NULL), - `unit_pricing_changed_at` (DATETIME, NULL). Dodaj indeks wspierajacy filtrowanie brakow unit pricing. Nie zmieniaj innych tabel ani istniejacych kluczy. Sprawdzenie SQL migracji oraz uruchomienie na srodowisku testowym bez bledow. AC-1 spelnione: schemat bazy obsluguje unit pricing i brakujace wartosci. Task 2: Rozszerz api.php o endpointy set/get/(opcjonalnie) missing z walidacja api.php Dodaj nowe akcje: - `product_unit_pricing_set`, - `product_unit_pricing_get`, - `products_get_missing_unit_pricing` (opcjonalnie, jesli nie koliduje z zakresem czasu). Dla `set` wdroz: - walidacje regex dla measure/base, - walidacje zgodnosci jednostek, - aktualizacje `unit_pricing_changed_at = NOW()`, - wpis do `products_comments`, - odpowiedzi 422 dla bledow walidacji. Utrzymaj styl analogiczny do endpointow `product_custom_label_*`. Testy wywolan curl dla happy-path i error-path (format/jednostka) + kontrola zapisow w DB. AC-2 i AC-3 spelnione; AC-5 spelnione jesli endpoint missing zostal wlaczony. Task 3: Zaktualizuj feed i dokumentacje publiczna API feeds/, docs/api-public-product-management.md W generatorze feedu dodaj emisje: - ``, - ``, tylko gdy oba pola sa niepuste. Uaktualnij dokumentacje API o sekcje: - `product_unit_pricing_set`, - `product_unit_pricing_get`, - `products_get_missing_unit_pricing` (jesli wdrozone). Nie wdrazaj skryptow agenta z zewnetrznego repo (`D:\google ads\...`) w ramach tego planu. Podglad wygenerowanego XML dla produktu z i bez unit pricing + review docs pod katem zgodnosci parametrow i odpowiedzi. AC-4 spelnione oraz dokumentacja odzwierciedla rzeczywiste endpointy.

DO NOT CHANGE

• Logika modułu AI poza adsPRO (D:\google ads\scripts\actions\...).
• Niezwiazane endpointy API i istniejace akcje product_custom_label_*.
• Warstwa UI/widokow niezwiązana z feedem i API unit pricing.

SCOPE LIMITS

• Ten plan obejmuje backend adsPRO: DB, API, feed, dokumentacje.
• Pilotaż 5 SKU i backfill wszystkich klientow jest poza tym planem (etap po wdrozeniu).

Before declaring plan complete: - [ ] Migracja SQL wykonuje sie poprawnie na srodowisku testowym. - [ ] `product_unit_pricing_set` przechodzi test happy-path i zapisuje komentarz + timestamp. - [ ] `product_unit_pricing_set` zwraca 422 dla blednego formatu i niezgodnych jednostek. - [ ] `product_unit_pricing_get` zwraca aktualne wartosci dla produktu. - [ ] (Jesli wdrozone) `products_get_missing_unit_pricing` zwraca liste z filtrowaniem i sortowaniem. - [ ] Feed XML zawiera tagi unit pricing tylko przy kompletnych danych. - [ ] Dokumentacja API jest zaktualizowana. - [ ] All acceptance criteria met.

<success_criteria>

• Dane unit pricing sa trwale przechowywane w products.
• API wspiera bezpieczny zapis/odczyt z walidacja i obsluga bledow.
• Feed GMC publikuje unit pricing zgodnie z wymaganiami Google.
• Dokumentacja publiczna pozwala uzyc nowych endpointow bez domyslow. </success_criteria>

After completion, create `.paul/phases/09-unit-pricing/09-01-SUMMARY.md`