update

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

@@ -0,0 +1,184 @@
+---
+phase: 09-unit-pricing
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - migrations/YYYY-MM-DD_add_unit_pricing.sql
+  - api.php
+  - feeds/
+  - docs/api-public-product-management.md
+autonomous: true
+delegation: off
+---
+
+<objective>
+## 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.
+</objective>
+
+<context>
+<clarifications>
+- **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\...`.
+</clarifications>
+
+## 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.
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Schemat danych wspiera unit pricing
+```gherkin
+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
+```gherkin
+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
+```gherkin
+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
+```gherkin
+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)
+```gherkin
+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>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Dodaj migracje i reguly danych dla unit pricing</name>
+  <files>migrations/YYYY-MM-DD_add_unit_pricing.sql</files>
+  <action>
+    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.
+  </action>
+  <verify>Sprawdzenie SQL migracji oraz uruchomienie na srodowisku testowym bez bledow.</verify>
+  <done>AC-1 spelnione: schemat bazy obsluguje unit pricing i brakujace wartosci.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rozszerz api.php o endpointy set/get/(opcjonalnie) missing z walidacja</name>
+  <files>api.php</files>
+  <action>
+    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_*`.
+  </action>
+  <verify>Testy wywolan curl dla happy-path i error-path (format/jednostka) + kontrola zapisow w DB.</verify>
+  <done>AC-2 i AC-3 spelnione; AC-5 spelnione jesli endpoint missing zostal wlaczony.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Zaktualizuj feed i dokumentacje publiczna API</name>
+  <files>feeds/, docs/api-public-product-management.md</files>
+  <action>
+    W generatorze feedu dodaj emisje:
+    - `<g:unit_pricing_measure>`,
+    - `<g:unit_pricing_base_measure>`,
+    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.
+  </action>
+  <verify>Podglad wygenerowanego XML dla produktu z i bez unit pricing + review docs pod katem zgodnosci parametrow i odpowiedzi.</verify>
+  <done>AC-4 spelnione oraz dokumentacja odzwierciedla rzeczywiste endpointy.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## 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).
+
+</boundaries>
+
+<verification>
+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.
+</verification>
+
+<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>
+
+<output>
+After completion, create `.paul/phases/09-unit-pricing/09-01-SUMMARY.md`
+</output>
+