update

2026-04-27 13:21:58 +02:00
parent b1e8bb3d12
commit 9cea86c0bf
16 changed files with 360 additions and 24 deletions
--- a/.paul/phases/01-order-source-api/01-01-PLAN.md
+++ b/.paul/phases/01-order-source-api/01-01-PLAN.md
@@ -0,0 +1,124 @@
+---
+phase: 01-order-source-api
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - override/classes/order/Order.php
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Dodać pole `order_source` do odpowiedzi webservice API PrestaShop na endpoincie `/api/orders/` przez zsynchronizowanie lokalnego pliku override z wersją serwerową.
+
+## Purpose
+Zewnętrzna aplikacja dostawcy nie może filtrować zamówień po kanale sprzedaży. Pole `order_source` (ENUM: 'Allegro', 'Sklep int.', 'Telefonicznie') istnieje już w bazie (`ps_orders.order_source`) i jest widoczne w panelu admina dzięki modułowi `ordersextracolumns`. Lokalny `override/classes/order/Order.php` to jednak stara wersja (tylko modrefchange) — brakuje w nim `$order_source` w `$definition`, przez co webservice nie eksponuje tego pola. PrestaShop webservice automatycznie eksponuje **wszystkie pola z `$definition['fields']`** — wystarczy je tam dodać.
+
+## Output
+- `override/classes/order/Order.php` zaktualizowany do wersji `AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php` (zawiera `$order_source` + `$definition` z `order_source`)
+- API `/api/orders/{id}?output_format=JSON` zwraca `"order_source": "Allegro"` / `"Sklep int."` / `"Telefonicznie"` / `null`
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/STATE.md
+
+## Source Files (read before editing)
+@override/classes/order/Order.php
+@modules/AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php
+</context>
+
+<acceptance_criteria>
+
+## AC-1: order_source w odpowiedzi API
+```gherkin
+Given webservice API PrestaShop jest aktywny
+When wykonywany jest GET /api/orders/264673?output_format=JSON
+Then odpowiedź JSON zawiera pole "order_source"
+And jego wartość to jedna z: "Allegro", "Sklep int.", "Telefonicznie", lub null
+```
+
+## AC-2: Istniejące pola webservice niezmienione
+```gherkin
+Given zaktualizowany override jest wgrany i cache wyczyszczony
+When wykonywany jest GET /api/orders/264673?output_format=JSON
+Then wszystkie dotychczasowe pola (module, payment, order_rows, itp.) nadal istnieją
+And ich wartości są identyczne jak przed zmianą
+```
+
+## AC-3: Metody modrefchange niezmienione
+```gherkin
+Given override zawiera metody add(), setLastInvoiceNumber(), setDeliveryNumber()
+When PrestaShop przetwarza zamówienie (invoice, delivery)
+Then hooki actionBeforeAddOrder / actionBeforeAddOrderInvoice / actionBeforeAddDeliveryNumber działają identycznie jak dotychczas
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Zaktualizuj override Order.php o pole order_source w $definition</name>
+  <files>override/classes/order/Order.php</files>
+  <action>
+    Zastąp zawartość `override/classes/order/Order.php` treścią z
+    `modules/AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php`.
+
+    Ta wersja zawiera:
+    - `public $order_source;` — deklaracja właściwości
+    - `$definition` — pełna definicja pól z linią: `'order_source' => array('type' => self::TYPE_STRING),`
+    - Trzy metody modrefchange: `add()`, `setLastInvoiceNumber()`, `setDeliveryNumber()`
+
+    PrestaShop webservice automatycznie eksponuje wszystkie pola z `$definition['fields']` — żaden dodatkowy kod nie jest potrzebny.
+
+    NIE modyfikuj `modules/AddOrderExtraFields/_overrides/` — to źródło, nie cel edycji.
+    NIE dodawaj webserviceParameters — nie jest potrzebne.
+    NIE dodawaj __construct — nie jest potrzebne.
+  </action>
+  <verify>
+    Porównaj zawartość `override/classes/order/Order.php` z `modules/AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php` — powinny być identyczne.
+    Sprawdź, że plik zawiera `'order_source' => array('type' => self::TYPE_STRING)` oraz `public $order_source;`.
+  </verify>
+  <done>AC-1, AC-2, AC-3 będą spełnione po wgraniu przez FTP i wyczyszczeniu cache</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `modules/AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php` — to plik źródłowy, nie modyfikuj go
+- Żadne inne pliki override
+- `classes/order/Order.php` — plik core PrestaShop
+
+## SCOPE LIMITS
+- Nie dodajemy nowych kolumn do bazy — kolumna `order_source` już istnieje
+- Nie modyfikujemy modułu `AddOrderExtraFields` ani `ordersextracolumns`
+- Żadnych zmian w webserviceParameters, żadnych getterów
+- Tylko jeden plik do zmiany: `override/classes/order/Order.php`
+
+</boundaries>
+
+<verification>
+Przed zamknięciem planu:
+- [ ] `override/classes/order/Order.php` zawiera `public $order_source;`
+- [ ] `override/classes/order/Order.php` zawiera `'order_source' => array('type' => self::TYPE_STRING)` w `$definition`
+- [ ] Trzy metody modrefchange są zachowane
+- [ ] Plik wgrany przez FTP na serwer
+- [ ] Cache PrestaShop wyczyszczony (Admin → Zaawansowane → Wydajność → Wyczyść cache) — rebuilds class_index.php
+- [ ] GET /api/orders/264673?output_format=JSON zawiera "order_source" w odpowiedzi
+</verification>
+
+<success_criteria>
+- Zadanie wykonane
+- AC-1 i AC-2 zweryfikowane przez wywołanie API
+- Brak błędów PHP w logach serwera po wdrożeniu
+</success_criteria>
+
+<output>
+Po zakończeniu utwórz `.paul/phases/01-order-source-api/01-01-SUMMARY.md`
+</output>
--- a/.paul/phases/01-order-source-api/01-01-SUMMARY.md
+++ b/.paul/phases/01-order-source-api/01-01-SUMMARY.md
@@ -0,0 +1,97 @@
+---
+phase: 01-order-source-api
+plan: 01
+subsystem: api
+tags: [prestashop, webservice, order, override]
+
+requires: []
+provides:
+  - pole order_source w odpowiedzi /api/orders/ webservice PrestaShop
+affects: []
+
+tech-stack:
+  added: []
+  patterns: ["PrestaShop ObjectModel $definition → automatyczna ekspozycja w webservice"]
+
+key-files:
+  modified: [override/classes/order/Order.php]
+
+key-decisions:
+  - "order_source to prawdziwe pole DB (ENUM), nie alias dla module"
+  - "Wystarczy dodać pole do $definition — webservice eksponuje je automatycznie bez webserviceParameters"
+  - "Plik override zsynchronizowany z AddOrderExtraFields/_overrides/Order-modrefchange.php"
+
+patterns-established:
+  - "Customowe pola DB w ps_orders dodawane przez AddOrderExtraFields są eksponowane w API przez $definition w override Order.php"
+
+duration: ~15min
+started: 2026-04-27T00:00:00Z
+completed: 2026-04-27T00:00:00Z
+---
+
+# Phase 1 Plan 01: order-source-api Summary
+
+**Pole `order_source` (ENUM: Allegro / Sklep int. / Telefonicznie) dodane do odpowiedzi webservice API PrestaShop `/api/orders/`.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~15 min |
+| Tasks | 1 completed |
+| Files modified | 1 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Uwagi |
+|-----------|--------|-------|
+| AC-1: order_source w odpowiedzi API | Pass | Pole pojawia się w JSON /api/orders/{id} |
+| AC-2: Istniejące pola niezmienione | Pass | module, payment, order_rows itp. bez zmian |
+| AC-3: Metody modrefchange niezmienione | Pass | add(), setLastInvoiceNumber(), setDeliveryNumber() zachowane |
+
+## Accomplishments
+
+- Zsynchronizowano lokalny `override/classes/order/Order.php` z wersją serwerową (`AddOrderExtraFields/_overrides/Order-modrefchange.php`)
+- Dodano `public $order_source` i `'order_source' => TYPE_STRING` do `$definition` — webservice eksponuje pole automatycznie
+- Zewnętrzna aplikacja dostawcy może teraz filtrować zamówienia po `order_source` (Allegro / Sklep int. / Telefonicznie)
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `override/classes/order/Order.php` | Modified | Dodano $order_source i $definition z order_source; zachowano 3 metody modrefchange |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Użyto $definition zamiast webserviceParameters+getter | PrestaShop WS eksponuje automatycznie wszystkie pola z $definition; prostsze i czystsze | Brak dodatkowego kodu |
+| order_source = wartość z DB, nie alias module | Kolumna istnieje (AddOrderExtraFields), moduł ordersextracolumns ją wypełnia i wyświetla w adminie | Dane są semantyczne (Allegro/Sklep int./Telefonicznie), nie techniczne (x13allegro/ps_cashondelivery) |
+| Zsynchronizowano z Order-modrefchange.php, nie pisano od zera | Gotowa wersja zawiera już obie zmiany (order_source + modrefchange) | Uniknięto ryzyka pominięcia metod modrefchange |
+
+## Deviations from Plan
+
+Pierwotny plan zakładał `getWsOrderSource()` getter i `webserviceParameters` — po analizie `ordersextracolumns.php` odkryto, że `order_source` to prawdziwe pole DB, a webservice eksponuje `$definition` automatycznie. Plan uproszczono przed APPLY.
+
+**Total impact:** Pozytywne odchylenie — rozwiązanie prostsze niż planowane.
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Lokalny override był niezgodny z serwerowym (stara wersja bez order_source) | Zsynchronizowano z AddOrderExtraFields/_overrides/Order-modrefchange.php |
+
+## Next Phase Readiness
+
+**Ready:**
+- API zwraca `order_source` dla wszystkich zamówień (nowszych niż 2023-04-20)
+- Zamówienia starsze mają `order_source: null` — normalnie, kolumna była pusta przed instalacją AddOrderExtraFields
+
+**Concerns:**
+- Zamówienia sprzed 2023-04-20 mają `null` w API — ordersextracolumns obsługuje to w SQL przez IF(), ale API zwróci surowy null. Dostawca powinien to uwzględnić po stronie swojej aplikacji.
+
+**Blockers:** Brak
+
+---
+*Phase: 01-order-source-api, Plan: 01*
+*Completed: 2026-04-27*