WooCommerce¶

WooCommerce to silnik buyspace.pl (i przyszłych sklepów per kraj). Tu nie podpinamy „cudzego" marketplace przez OAuth — to własny sklep, którym zarządzasz przez REST API klucza, plus warstwę mu-pluginów po stronie WordPressa.

Status delivery¶

✅ Pełne — wystawianie pojedyncze i rodziny (variations), pobieranie ofert, push raportów, deploy CSS.

Funkcja	Status
Autoryzacja (REST API key, nie OAuth)	✅
Pobieranie ofert (`pull_from_woo`)	✅
Wystawianie pojedyncze (`push_simple`)	✅
Wystawianie rodzin (variations)	✅
`(cennik1 + cennik2) × współczynnik`	✅ flow serwerowy (TASK-290)
Auto-retry	⚪
Synchronizacja zgłoszeń	✅ co 10 min
Deploy CSS sklepu	✅
Naprawianie URLi domeny po zmianie hosta	✅ (`fix_domain_urls`)

Setup — podłączenie sklepu WooCommerce¶

WooCommerce to Twój sklep — zakładamy, że WordPress + WooCommerce są już zainstalowane. Patrz Sklepy dla architektury hostingowej.

Marketplace → Konfiguracja → WooCommerce → Dodaj sklep.
Wpisz:
Etykieta — np. „buyspace.pl",
Base URL — https://buyspace.pl/wp-json/wc/v3/,
Consumer Key + Consumer Secret — generujesz je w WordPressie pod WooCommerce → Settings → Advanced → REST API → Add key (uprawnienia: Read/Write).
Kliknij Test connection — panel sprawdzi GET /products?per_page=1 i pokaże ✅ jeśli REST jest dostępne.
Sklep jest gotowy do użycia.

Wymagany mu-plugin po stronie WordPressa¶

Panel używa kilku custom endpointów (np. dla atrybutów per family, dla deploy CSS), które nie są częścią standardowego WC REST API. Te endpointy są dostarczane przez mu-plugin w windmill/f/infra/wordpress/mu-plugins/. Mu-plugin instalujemy raz przy provisioning sklepu — patrz TASK-262 / mu-plugins.

Bez mu-pluginu działa basic flow

Standardowe wystawianie produktów (push_simple, pull_from_woo) działa bez mu-pluginu. Mu-plugin dodaje:

deploy CSS (zamiast zmieniać template),
fix domain URLs (gdy migracja sklepu między hostami),
taksonomie kompatybilne z atrybutami BL.

Wystawianie¶

Pojedynczy produkt¶

Marketplace → Oferty → WooCommerce, wybierz sklep.
Wybierz tag rodziny i SKU.
Kliknij Wystaw.
Panel:
dolicza cenę przez (cennik1 + cennik2) × współczynnik,
buduje payload Woo product (title, description, short_description, regular_price, sale_price, categories, attributes, images),
wysyła POST /products,
po sukcesie zapisuje remote_product_id = Woo product ID.

Rodzina (variations)¶

WooCommerce ma natywne wsparcie wariantów (variable product + variations):

Panel tworzy parent product (type=variable) z atrybutami rodziny zdefiniowanymi na poziomie produktu.
Dla każdego SKU tworzy variation (POST /products/{parent_id}/variations) z attributes, regular_price, stock.
Wszystkie variations współdzielą galerię zdjęć parenta + opis.

Stock i ceny¶

Stock czyta się z BaseLinkera. Jeśli chcesz zmienić stan — zmień w BL, a panel zaktualizuje przy najbliższym push.
Ceny liczone w panelu wg reguły. Woo nigdy nie liczy ich sam.
Sale prices (przeceny) — obecnie nieobsługiwane automatycznie. Wpisujesz ręcznie w WP-Admin lub przez bulk-edit (Woo natywne narzędzia).

Cenniki¶

Reguła	Status
`cennik1 × współczynnik`	✅
`(cennik1 + cennik2) × współczynnik`	✅ (TASK-290)
Per-sklep `merchant_shipping_class`	✅

Stany ofert¶

Status (panel)	Co znaczy w Woo
`pending`	`POST /products` wysłany, czekamy
`listed`	Woo `status=publish` + `stock_status=instock`
`failed`	Woo zwrócił 4xx (najczęściej brak SKU lub atrybutu)
`removed`	`status=draft` lub `status=trash`

Synchronizacja periodyczna¶

Zadanie	Częstotliwość
Pobieranie zgłoszeń klienta (`fetchers/issues`)	co 10 minut
Snapshot ofert (`pull_from_woo`)	uruchamiane z UI + cron
Push raport (`push_report`)	po każdej operacji push

WooCommerce nie ma OAuth, więc nie ma scheduled refresh tokenów. Klucz REST API jest stały, dopóki właściciel nie usunie go w WP-Admin.

Edge cases / known gotchas¶

Zombie parent przy null woo_product_id

Gdy push_simple poleci błędem na poziomie parent (np. brak slugu), panel zostawia parent w stanie pending z woo_product_id=null, a kolejne próby tworzą duplikaty. Naprawione: panel wykrywa zombie parent i czyści przed retryem (TASK-285).

Slug konflikty

WooCommerce wymaga unikalnego slug per produkt. Jeśli dwie rodziny mają zbliżone nazwy (np. „Bluza Husky" i „Bluza husky"), Woo wymusi suffix (bluza-husky-2). Akceptowalne, ale jeśli chcesz konkretnego slugu — wpisz go w mapowaniu rodziny.

Migracja sklepu między hostami

Po przeniesieniu sklepu (np. host-mom → host-dad failover) URLi w treści produktów zostają stare. Skrypt fix_domain_urls.ts przepisuje wszystkie linki w description, gallery, image_meta. Uruchamiany ręcznie z UI po failoverze.

Custom CSS przez deploy_css

Zamiast edytować WP theme, panel ma deploy_css.ts który podmienia plik CSS sklepu (buyspace-description.css) przez mu-plugin. Idealne do iteratywnego fine-tuningu wyglądu opisu produktu bez ryzyka popsucia themeu.

Troubleshooting¶

Objaw	Co zrobić
`401 Unauthorized`	Klucz REST API zrewokowany w WP-Admin. Wygeneruj nowy i wpisz w Konfiguracji.
`404 rest_route_not_found`	Mu-plugin nie zainstalowany lub WP nie ma `wc/v3` przepisanych permalinks. Patrz Sklepy.
`duplicate_sku`	Ten SKU już istnieje w Woo. Sprawdź czy `pull_from_woo` zsynchronizował się przed push.
Variation utworzony, ale nie widoczny w sklepie	WP cache. Wykonaj `wp cache flush` lub zaczekaj 5 min.
Ceny rozjechane między WP a panelem	`pull_from_woo` powinno zsynchronizować. Wykonaj Refresh now.

Dane techniczne (appendix dla developera)¶

Tabela stanu: marketplace_listings. remote_product_id = Woo product ID.
Główne skrypty: windmill/f/marketplace/woocommerce/push_simple.ts (prepare → push), pull_from_woo.ts, deploy_css.py, fix_domain_urls.py, ensure_woo_taxonomy.ts.
Mu-plugin (po stronie WP): windmill/f/infra/wordpress/mu-plugins/.
Scheduler: f/marketplace/woocommerce/fetchers/issues.schedule.yaml (10 min).