185 lines
6.7 KiB
Markdown
185 lines
6.7 KiB
Markdown
---
|
|
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>
|
|
|