update

.paul/phases/63-order-item-personalization/63-01-PLAN.md

@@ -0,0 +1,164 @@
+---
+phase: 63-order-item-personalization
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - database/migrations/20260401_000063_add_personalization_to_order_items.sql
+  - src/Modules/Settings/ShopproOrderMapper.php
+  - src/Modules/Orders/OrderImportRepository.php
+  - resources/views/orders/show.php
+  - resources/scss/orders/_show.scss
+autonomous: true
+---
+
+<objective>
+## Goal
+Pobieranie danych personalizacji produktów z shopPRO i wyświetlanie ich w szczegółach zamówienia orderPRO.
+
+## Purpose
+Sprzedawcy widzą personalizacje klientów (np. tekst grawerunku, link Spotify, dedykacja) bezpośrednio w orderPRO bez konieczności logowania do shopPRO. Kluczowe dla realizacji zamówień z personalizowanymi produktami.
+
+## Output
+- Migracja DB: kolumna `personalization` w `order_items`
+- Mapper: ekstrakcja `custom_fields` z odpowiedzi shopPRO API
+- UI: wyświetlanie personalizacji pod nazwą produktu w widoku zamówienia
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Modules/Settings/ShopproOrderMapper.php — mapItems() linia 527, mapuje produkty z API shopPRO
+@src/Modules/Orders/OrderImportRepository.php — replaceItems() wstawia pozycje do DB
+@resources/views/orders/show.php — widok szczegółów zamówienia, sekcja produktów
+@database/migrations/20260302_000018_create_orders_tables_and_schedule.sql — schemat order_items
+</context>
+
+<skills>
+No specialized flows configured.
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: Personalizacja zapisana w bazie danych
+```gherkin
+Given zamówienie z shopPRO zawiera produkty z custom_fields
+When import zamówienia się wykonuje (cron lub ręczny)
+Then kolumna personalization w order_items zawiera dane personalizacji jako czysty tekst (bez HTML)
+```
+
+## AC-2: Personalizacja wyświetlana w szczegółach zamówienia
+```gherkin
+Given zamówienie w orderPRO ma pozycje z wypełnioną personalizacją
+When użytkownik otwiera szczegóły zamówienia (/orders/{id})
+Then pod nazwą produktu wyświetla się sekcja personalizacji z etykietami i wartościami
+```
+
+## AC-3: Brak personalizacji nie powoduje błędów
+```gherkin
+Given zamówienie z shopPRO zawiera produkty BEZ custom_fields (puste lub null)
+When import się wykonuje i użytkownik otwiera szczegóły
+Then kolumna personalization jest NULL i w UI nie pojawia się sekcja personalizacji
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Migracja DB + mapping personalizacji</name>
+  <files>database/migrations/20260401_000063_add_personalization_to_order_items.sql, src/Modules/Settings/ShopproOrderMapper.php, src/Modules/Orders/OrderImportRepository.php</files>
+  <action>
+    1. Utworzyć migrację dodającą kolumnę `personalization TEXT NULL` do tabeli `order_items` (po kolumnie `payload_json`).
+
+    2. W `ShopproOrderMapper::mapItems()` (linia 561-580):
+       - Wyciągnąć `custom_fields` z `$row` za pomocą `$this->readPath($row, ['custom_fields'])`
+       - Przekonwertować HTML na czysty tekst: zamienić `<br>` na `\n`, usunąć tagi HTML (`strip_tags`), `html_entity_decode`, `trim`
+       - Zapisać jako klucz `personalization` w tablicy wynikowej (obok `payload_json`)
+       - Jeśli wynik jest pustym stringiem, ustawić `null`
+
+    3. W `OrderImportRepository::replaceItems()`:
+       - Dodać kolumnę `personalization` do INSERT query
+       - Bindować wartość z tablicy item
+
+    Avoid: Nie zmieniać formatu `payload_json` — surowe dane API muszą zostać nienaruszone.
+    Avoid: Nie parsować HTML do JSON — czysty tekst z zachowanymi newlines jest wystarczający.
+  </action>
+  <verify>
+    - Migracja wykonuje się bez błędów: `php database/migrate.php`
+    - Po re-imporcie zamówienia z shopPRO kolumna `personalization` zawiera tekst
+    - Zamówienia bez personalizacji mają NULL w kolumnie
+  </verify>
+  <done>AC-1 i AC-3 satisfied: personalizacja zapisywana w DB, brak personalizacji = NULL</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Wyświetlanie personalizacji w widoku zamówienia</name>
+  <files>resources/views/orders/show.php, resources/scss/orders/_show.scss</files>
+  <action>
+    1. W `resources/views/orders/show.php`, w sekcji renderującej produkty zamówienia:
+       - Pod nazwą produktu (`original_name`) dodać blok warunkowy: jeśli `$item['personalization']` nie jest puste
+       - Wyświetlić personalizację w `<div class="item-personalization">` z ikoną lub etykietą "Personalizacja:"
+       - Każda linia personalizacji (split po `\n`) jako osobna linia w UI
+       - Escape HTML: użyć `e()` helpera na każdej linii
+
+    2. W SCSS dodać style:
+       - `.item-personalization` — mały font (0.85em), kolor muted, lekki padding-top
+       - Etykiety (tekst przed `:`) mogą być pogrubione via CSS lub pozostawione jako plain text
+       - Kompaktowy układ, bez nadmiernych marginesów
+
+    Avoid: Nie renderować surowego HTML z custom_fields — zawsze escape.
+    Avoid: Nie dodawać nowych zależności JS — to statyczny tekst.
+  </action>
+  <verify>
+    - Otworzyć zamówienie z personalizacją w przeglądarce — personalizacja widoczna pod nazwą produktu
+    - Otworzyć zamówienie bez personalizacji — brak dodatkowej sekcji
+    - Sprawdzić XSS: wpisać `<script>alert(1)</script>` w custom_fields shopPRO — powinno być escaped
+  </verify>
+  <done>AC-2 satisfied: personalizacja wyświetlana w UI pod nazwą produktu</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- shopPRO codebase (API już zwraca custom_fields — zero zmian po stronie shopPRO)
+- payload_json format i zawartość w order_items
+- Istniejące kolumny i indeksy order_items
+- Logika importu zamówień poza mapowaniem items (OrderImportRepository::upsertOrderAggregate flow)
+
+## SCOPE LIMITS
+- Tylko personalizacja z shopPRO (nie Allegro, nie Erli)
+- Tylko widok szczegółów zamówienia — bez zmian na liście zamówień
+- Bez edycji personalizacji w orderPRO — read-only display
+- Bez parsowania personalizacji do struktury klucz-wartość (JSON) — plain text wystarczy
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] Migracja wykonuje się bez błędów
+- [ ] SCSS kompiluje się bez błędów
+- [ ] Zamówienie z personalizacją — dane widoczne w UI
+- [ ] Zamówienie bez personalizacji — brak sekcji w UI
+- [ ] Brak regresji w istniejącym wyświetlaniu produktów
+- [ ] XSS escape działa poprawnie
+- [ ] Aktualizacja DOCS/DB_SCHEMA.md i DOCS/ARCHITECTURE.md
+</verification>
+
+<success_criteria>
+- Wszystkie taski zakończone
+- Wszystkie weryfikacje przechodzą
+- Brak błędów PHP/SCSS
+- Personalizacja widoczna w UI dla produktów z custom_fields
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/63-order-item-personalization/63-01-SUMMARY.md`
+</output>