ver. 0.302: REST API product variants, attributes dictionary, attribute filtering

- Add variant CRUD endpoints (variants, create_variant, update_variant, delete_variant) - Add dictionaries/attributes endpoint with multilingual names and values - Add attribute_* filter params for product list filtering by attribute values - Enrich product detail attributes with translated names (attribute_names, value_names) - Include variants array in product detail response for parent products - Add price_brutto validation on product create - Batch-load attribute/value translations (4 queries instead of N+1) - Add 43 new unit tests (730 total, 2066 assertions) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 14:42:52 +01:00
parent 38cc4f28c1
commit 6fdbe61916
18 changed files with 1721 additions and 22 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -152,6 +152,7 @@ Parametry filtrowania (opcjonalne):
 | `search` | string | Szukaj po nazwie, EAN lub SKU |
 | `status` | int (0/1) | Filtruj po statusie (1 = aktywny, 0 = nieaktywny) |
 | `promoted` | int (0/1) | Filtruj po promocji |
+| `attribute_{id}` | int | Filtruj po atrybucie — `attribute_1=3` oznacza atrybut 1 = wartosc 3 (wiele filtrow AND) |
 | `sort` | string | Sortuj po: id, name, price_brutto, status, promoted, quantity (domyslnie id) |
 | `sort_dir` | string | Kierunek: ASC lub DESC (domyslnie DESC) |
 | `page` | int | Numer strony (domyslnie 1) |
@@ -244,7 +245,33 @@ Odpowiedz:
    ],
    "categories": [1, 5],
    "attributes": [
-      {"attribute_id": 1, "value_id": 3}
+      {
+        "attribute_id": 1,
+        "attribute_type": 1,
+        "attribute_names": {"pl": "Kolor", "en": "Color"},
+        "value_id": 3,
+        "value_names": {"pl": "Czerwony", "en": "Red"}
+      }
+    ],
+    "variants": [
+      {
+        "id": 101,
+        "permutation_hash": "1-3|2-5",
+        "sku": "PROD-001-RED-L",
+        "ean": null,
+        "price_brutto": 109.99,
+        "price_brutto_promo": null,
+        "price_netto": 89.42,
+        "price_netto_promo": null,
+        "quantity": 5,
+        "stock_0_buy": 0,
+        "weight": 0.5,
+        "status": 1,
+        "attributes": [
+          {"attribute_id": 1, "attribute_names": {"pl": "Kolor"}, "value_id": 3, "value_names": {"pl": "Czerwony"}},
+          {"attribute_id": 2, "attribute_names": {"pl": "Rozmiar"}, "value_id": 5, "value_names": {"pl": "L"}}
+        ]
+      }
    ]
  }
 }
@@ -306,6 +333,104 @@ Partial update — wystarczy przeslac tylko zmienione pola. Pola nieprzeslane za

 Odpowiedz: pelne dane produktu (jak w `get`).

+### Warianty produktow
+
+#### Lista wariantow produktu
+```
+GET api.php?endpoint=products&action=variants&id={product_id}
+```
+
+Zwraca warianty produktu nadrzednego wraz z dostepnymi atrybutami.
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": {
+    "product_id": 1,
+    "available_attributes": [
+      {
+        "id": 1,
+        "type": 1,
+        "status": 1,
+        "names": {"pl": "Kolor", "en": "Color"},
+        "values": [
+          {"id": 3, "names": {"pl": "Czerwony", "en": "Red"}, "is_default": 0, "impact_on_the_price": null},
+          {"id": 4, "names": {"pl": "Niebieski", "en": "Blue"}, "is_default": 0, "impact_on_the_price": 10.0}
+        ]
+      }
+    ],
+    "variants": [
+      {
+        "id": 101,
+        "permutation_hash": "1-3",
+        "sku": "PROD-001-RED",
+        "ean": null,
+        "price_brutto": 109.99,
+        "price_brutto_promo": null,
+        "price_netto": 89.42,
+        "price_netto_promo": null,
+        "quantity": 5,
+        "stock_0_buy": 0,
+        "weight": 0.5,
+        "status": 1,
+        "attributes": [
+          {"attribute_id": 1, "attribute_names": {"pl": "Kolor"}, "value_id": 3, "value_names": {"pl": "Czerwony"}}
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### Tworzenie wariantu
+```
+POST api.php?endpoint=products&action=create_variant&id={product_id}
+Content-Type: application/json
+
+{
+  "attributes": {"1": 3, "2": 5},
+  "sku": "PROD-001-RED-L",
+  "ean": "5901234123458",
+  "price_brutto": 109.99,
+  "quantity": 5,
+  "weight": 0.5
+}
+```
+
+Wymagane: `attributes` (mapa attribute_id -> value_id, min. 1). Kombinacja atrybutow musi byc unikalna.
+
+Odpowiedz (HTTP 201): pelne dane wariantu.
+
+#### Aktualizacja wariantu
+```
+PUT api.php?endpoint=products&action=update_variant&id={variant_id}
+Content-Type: application/json
+
+{
+  "sku": "PROD-001-RED-XL",
+  "price_brutto": 119.99,
+  "quantity": 3
+}
+```
+
+Partial update — mozna zmienic: sku, ean, price_brutto, price_netto, price_brutto_promo, price_netto_promo, quantity, stock_0_buy, weight, status.
+
+Odpowiedz: pelne dane wariantu.
+
+#### Usuwanie wariantu
+```
+DELETE api.php?endpoint=products&action=delete_variant&id={variant_id}
+```
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": {"id": 101, "deleted": true}
+}
+```
+
 ### Slowniki

 #### Lista statusow zamowien
@@ -336,6 +461,32 @@ GET api.php?endpoint=dictionaries&action=transports
 GET api.php?endpoint=dictionaries&action=payment_methods
 ```

+#### Lista atrybutow
+```
+GET api.php?endpoint=dictionaries&action=attributes
+```
+
+Zwraca aktywne atrybuty z wartosciami i wielojezycznymi nazwami.
+
+Odpowiedz:
+```json
+{
+  "status": "ok",
+  "data": [
+    {
+      "id": 1,
+      "type": 1,
+      "status": 1,
+      "names": {"pl": "Kolor", "en": "Color"},
+      "values": [
+        {"id": 3, "names": {"pl": "Czerwony"}, "is_default": 0, "impact_on_the_price": null},
+        {"id": 4, "names": {"pl": "Niebieski"}, "is_default": 1, "impact_on_the_price": 10.0}
+      ]
+    }
+  ]
+}
+```
+
 ## Polling

 Aby pobierac tylko nowe/zmienione zamowienia, uzyj parametru `updated_since`:
@@ -362,5 +513,5 @@ UPDATE pp_settings SET value = 'twoj-klucz-api' WHERE param = 'api_key';
 - Router: `\api\ApiRouter` (`autoload/api/ApiRouter.php`)
 - Kontrolery: `autoload/api/Controllers/`
  - `OrdersApiController` — zamowienia (5 akcji)
-  - `ProductsApiController` — produkty (4 akcje: list, get, create, update)
-  - `DictionariesApiController` — slowniki (3 akcje)
+  - `ProductsApiController` — produkty (8 akcji: list, get, create, update, variants, create_variant, update_variant, delete_variant)
+  - `DictionariesApiController` — slowniki (4 akcje: statuses, transports, payment_methods, attributes)
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -4,6 +4,19 @@ Logi zmian z migracji na Domain-Driven Architecture. Najnowsze na gorze.

 ---

+## ver. 0.302 (2026-02-22) - REST API: warianty produktow, atrybuty, filtrowanie
+
+- **NEW**: API wariantow produktow — CRUD: `variants`, `create_variant`, `update_variant`, `delete_variant`
+- **NEW**: API slownik atrybutow — `dictionaries/attributes` z wielojezycznymi nazwami i wartosciami
+- **NEW**: Filtrowanie produktow po atrybutach w `products/list` — parametry `attribute_{id}={value_id}`
+- **NEW**: Wzbogacone atrybuty w `products/get` — nazwy atrybutow i wartosci z tlumaczeniami
+- **NEW**: Warianty w odpowiedzi `products/get` — lista wariantow z atrybutami dla produktow nadrzednych
+- **NEW**: Walidacja `price_brutto` przy tworzeniu produktu (musi byc nieujemna liczba)
+- **NEW**: Batch-loading atrybutow i wartosci (4 zapytania zamiast N+1) w `AttributeRepository::listForApi()`
+- **NEW**: 43 nowe testy jednostkowe (730 total, 2066 assertions)
+
+---
+
 ## ver. 0.301 (2026-02-22) - Mobile responsive: filtry tabel i szczegoly zamowienia

 - **NEW**: Filtry w tabelach admina domyslnie ukryte — przycisk toggle z ikona filtra, badge z liczba aktywnych filtrow
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -23,7 +23,7 @@ composer test              # standard
 ## Aktualny stan

 ```text
-OK (692 tests, 1988 assertions)
+OK (730 tests, 2066 assertions)
 ```

 Zweryfikowano: 2026-02-21 (ver. 0.300)
--- a/docs/UPDATE_INSTRUCTIONS.md
+++ b/docs/UPDATE_INSTRUCTIONS.md
@@ -101,13 +101,13 @@ Aktualizacje znajdują się w folderze `updates/0.XX/` gdzie XX oznacza dziesią

 **WAŻNE:** W archiwum ZIP NIE powinno być folderu z nazwą wersji. Struktura ZIP zaczyna się bezpośrednio od katalogów projektu (admin/, autoload/, itp.).

-## Status bieżącej aktualizacji (ver. 0.301)
+## Status bieżącej aktualizacji (ver. 0.302)

- Wersja udostępniona: `0.301` (data: 2026-02-22).
+- Wersja udostępniona: `0.302` (data: 2026-02-22).
 - Pliki publikacyjne:
-    - `updates/0.30/ver_0.301.zip`
+    - `updates/0.30/ver_0.302.zip`
 - Pliki metadanych aktualizacji:
    - `updates/changelog.php`
-    - `updates/versions.php` (`$current_ver = 301`)
+    - `updates/versions.php` (`$current_ver = 302`)
 - Weryfikacja testów przed publikacją:
-    - `OK (692 tests, 1988 assertions)`
+    - `OK (730 tests, 2066 assertions)`