---
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>