refactor(01-tech-debt): extract AllegroTokenManager and StringHelper

Phase 1 complete (2/2 plans): - Plan 01-01: Extract AllegroTokenManager — OAuth token logic centralized from 4 classes into dedicated manager class - Plan 01-02: Extract StringHelper — nullableString/normalizeDateTime/ normalizeColorHex extracted from 15+ classes into App\Core\Support\StringHelper; removed 19 duplicate private methods Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-12 23:36:06 +01:00
parent 4c3daf69b7
commit f8db8c0162
26 changed files with 1374 additions and 547 deletions
--- a/.paul/phases/01-tech-debt/01-02-PLAN.md
+++ b/.paul/phases/01-tech-debt/01-02-PLAN.md
@@ -0,0 +1,270 @@
+---
+phase: 01-tech-debt
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Core/Support/StringHelper.php
+  - src/Modules/Settings/AllegroOrderImportService.php
+  - src/Modules/Settings/AllegroOrdersSyncService.php
+  - src/Modules/Settings/AllegroOrderSyncStateRepository.php
+  - src/Modules/Settings/AllegroIntegrationRepository.php
+  - src/Modules/Settings/AllegroStatusMappingRepository.php
+  - src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php
+  - src/Modules/Settings/CompanySettingsRepository.php
+  - src/Modules/Settings/InpostIntegrationRepository.php
+  - src/Modules/Settings/IntegrationsRepository.php
+  - src/Modules/Settings/ShopproIntegrationsRepository.php
+  - src/Modules/Settings/ShopproOrdersSyncService.php
+  - src/Modules/Settings/ShopproPaymentStatusSyncService.php
+  - src/Modules/Orders/OrdersController.php
+  - src/Modules/Orders/OrdersRepository.php
+  - src/Modules/Settings/SettingsController.php
+  - .paul/codebase/CONCERNS.md
+autonomous: true
+---
+
+<objective>
+## Cel
+Ekstrakcja zduplikowanych prywatnych metod pomocniczych (`nullableString()`, `normalizeDateTime()`, `normalizeColorHex()`) z 15+ klas do jednej klasy `StringHelper` w `src/Core/Support/`. Zamiana wszystkich wywołań prywatnych metod na wywołania statyczne.
+
+## Uzasadnienie
+Te same metody są copy-paste w 12+ klasach. Narusza to regułę projektu przeciwko duplikowaniu kodu (CLAUDE.md) oraz zasadę SRP. Ryzyko rozbieżności jeśli jedna kopia zostanie zmieniona a inne nie.
+
+## Wynik
+- Nowy plik `src/Core/Support/StringHelper.php` z 3 metodami statycznymi
+- 15 plików — usunięte prywatne metody, zamienione wywołania na `StringHelper::*`
+- Wpis o tym błędzie usunięty z `.paul/codebase/CONCERNS.md`
+</objective>
+
+<context>
+## Kontekst projektu
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Istniejące pliki w Core/Support
+Już istnieją: `src/Core/Support/Env.php`, `Flash.php`, `Logger.php`, `Session.php` — wzorzec dla `StringHelper.php`.
+
+## Wzorzec implementacji helperów
+`nullableString()` — trim + zwróć null jeśli pusty string:
+```php
+private function nullableString(string $value): ?string
+{
+    $trimmed = trim($value);
+    return $trimmed === '' ? null : $trimmed;
+}
+```
+
+`normalizeDateTime()` — trim, walidacja, formatowanie do `Y-m-d H:i:s`:
+```php
+private function normalizeDateTime(string $value): ?string
+{
+    $trimmed = trim($value);
+    if ($trimmed === '') { return null; }
+    try {
+        return (new DateTimeImmutable($trimmed))->format('Y-m-d H:i:s');
+    } catch (\Exception $e) { return null; }
+}
+```
+
+`normalizeColorHex()` — walidacja regex `#RRGGBB`, fallback `#64748b`:
+```php
+private function normalizeColorHex(string $value): string
+{
+    $trimmed = trim($value);
+    if (preg_match('/^#[0-9a-fA-F]{6}$/', $trimmed) === 1) {
+        return strtolower($trimmed);
+    }
+    return '#64748b';
+}
+```
+</context>
+
+<skills>
+## Wymagane Skille (z SPECIAL-FLOWS.md)
+
+| Skill | Priorytet | Kiedy wywołać | Załadowany? |
+|-------|-----------|---------------|-------------|
+| /feature-dev | required | Przed implementacją | ○ |
+| /code-review | required | Po implementacji, przed UNIFY | ○ |
+
+**BLOKUJĄCE:** Wymagane skille MUSZĄ być załadowane przed uruchomieniem APPLY.
+
+## Lista do odhaczenia
+- [ ] /feature-dev załadowany
+- [ ] /code-review załadowany (przed UNIFY)
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: StringHelper istnieje i zawiera wszystkie 3 metody
+```gherkin
+Given plik src/Core/Support/StringHelper.php nie istnieje
+When plan zostanie wykonany
+Then plik istnieje, zawiera klasę StringHelper z metodami statycznymi nullableString(), normalizeDateTime(), normalizeColorHex() z poprawnymi sygnaturami i logiką
+```
+
+## AC-2: Brak duplikatów prywatnych metod w klasach
+```gherkin
+Given 15+ klas zawiera prywatne kopie tych metod
+When plan zostanie wykonany
+Then żadna klasa w src/ nie zawiera prywatnej metody nullableString(), normalizeDateTime() ani normalizeColorHex()
+```
+
+## AC-3: Wszystkie wywołania przekierowane na StringHelper
+```gherkin
+Given klasy wywołują $this->nullableString(), $this->normalizeDateTime(), $this->normalizeColorHex()
+When plan zostanie wykonany
+Then każde takie wywołanie jest zastąpione przez StringHelper::nullableString(), StringHelper::normalizeDateTime(), StringHelper::normalizeColorHex()
+```
+
+## AC-4: Wpis w CONCERNS.md usunięty
+```gherkin
+Given sekcja "[HIGH] Duplicated nullableString()..." istnieje w .paul/codebase/CONCERNS.md
+When plan zostanie wykonany
+Then ta sekcja jest usunięta z pliku CONCERNS.md
+```
+
+## AC-5: Brak błędów składniowych PHP
+```gherkin
+Given zmodyfikowane pliki PHP
+When uruchomimy php -l na każdym zmodyfikowanym pliku
+Then każdy plik zwraca "No syntax errors detected"
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Zadanie 1: Utwórz StringHelper z 3 metodami statycznymi</name>
+  <files>src/Core/Support/StringHelper.php</files>
+  <action>
+    Utwórz nowy plik `src/Core/Support/StringHelper.php` z namespace `App\Core\Support`.
+    Klasa `StringHelper` (final) z 3 publicznymi metodami statycznymi:
+
+    1. `nullableString(string $value): ?string`
+       - trim($value), jeśli '' → return null, inaczej return trimmed
+
+    2. `normalizeDateTime(string $value): ?string`
+       - trim($value), jeśli '' → return null
+       - try { return (new DateTimeImmutable($trimmed))->format('Y-m-d H:i:s'); }
+       - catch (\Exception) { return null; }
+       - WAŻNE: użyj `use DateTimeImmutable;` w importach
+
+    3. `normalizeColorHex(string $value): string`
+       - trim($value), jeśli pasuje do `/^#[0-9a-fA-F]{6}$/` → return strtolower($trimmed)
+       - fallback: return '#64748b'
+
+    Styl: `declare(strict_types=1)`, PascalCase dla klasy, brak konstruktora.
+  </action>
+  <verify>php -l "src/Core/Support/StringHelper.php" zwraca "No syntax errors detected"</verify>
+  <done>AC-1 spełnione: StringHelper.php istnieje z 3 metodami statycznymi</done>
+</task>
+
+<task type="auto">
+  <name>Zadanie 2: Zamień prywatne metody na StringHelper we wszystkich 15 plikach</name>
+  <files>
+    src/Modules/Settings/AllegroOrderImportService.php,
+    src/Modules/Settings/AllegroOrdersSyncService.php,
+    src/Modules/Settings/AllegroOrderSyncStateRepository.php,
+    src/Modules/Settings/AllegroIntegrationRepository.php,
+    src/Modules/Settings/AllegroStatusMappingRepository.php,
+    src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php,
+    src/Modules/Settings/CompanySettingsRepository.php,
+    src/Modules/Settings/InpostIntegrationRepository.php,
+    src/Modules/Settings/IntegrationsRepository.php,
+    src/Modules/Settings/ShopproIntegrationsRepository.php,
+    src/Modules/Settings/ShopproOrdersSyncService.php,
+    src/Modules/Settings/ShopproPaymentStatusSyncService.php,
+    src/Modules/Orders/OrdersController.php,
+    src/Modules/Orders/OrdersRepository.php,
+    src/Modules/Settings/SettingsController.php
+  </files>
+  <action>
+    Dla każdego pliku z listy:
+
+    1. Dodaj `use App\Core\Support\StringHelper;` do sekcji importów (po istniejących `use` statements)
+       - Tylko jeśli plik rzeczywiście używa co najmniej jednej z tych metod
+       - Zachowaj alfabetyczną kolejność lub dodaj na końcu bloku use
+
+    2. Zamień wywołania:
+       - `$this->nullableString(` → `StringHelper::nullableString(`
+       - `$this->normalizeDateTime(` → `StringHelper::normalizeDateTime(`
+       - `$this->normalizeColorHex(` → `StringHelper::normalizeColorHex(`
+
+    3. Usuń prywatną metodę z klasy:
+       - Całą definicję `private function nullableString(...)` jeśli istnieje w pliku
+       - Całą definicję `private function normalizeDateTime(...)` jeśli istnieje
+       - Całą definicję `private function normalizeColorHex(...)` jeśli istnieje
+
+    UWAGA: AllegroOrderImportService.php ma zarówno nullableString() jak i normalizeDateTime() — usuń obie.
+    UWAGA: ShopproOrdersSyncService.php ma zarówno nullableString() jak i normalizeDateTime() — usuń obie.
+    UWAGA: ShopproPaymentStatusSyncService.php ma zarówno nullableString() jak i normalizeDateTime() — usuń obie.
+
+    NIE zmieniaj żadnej innej logiki. Tylko zamiana wywołań i usunięcie duplikatów.
+  </action>
+  <verify>
+    php -l na każdym z 15 zmodyfikowanych plików — brak błędów składniowych.
+    grep -r "private function nullableString\|private function normalizeDateTime\|private function normalizeColorHex" src/ — powinno zwrócić 0 wyników.
+  </verify>
+  <done>AC-2 i AC-3 spełnione: brak duplikatów, wszystkie wywołania na StringHelper::</done>
+</task>
+
+<task type="auto">
+  <name>Zadanie 3: Usuń wpis o błędzie z CONCERNS.md</name>
+  <files>.paul/codebase/CONCERNS.md</files>
+  <action>
+    Usuń sekcję `### [HIGH] Duplicated nullableString() / normalizeDateTime() / normalizeColorHex() Helpers — 15+ copies` wraz z całą jej treścią (od linii `### [HIGH] Duplicated...` do następnej linii `---`).
+
+    Usuń także poziomą linię `---` oddzielającą tę sekcję od następnej (zostaw jeden separator między Tech Debt a kolejną sekcją jeśli to potrzebne dla czytelności).
+
+    NIE modyfikuj żadnych innych wpisów w CONCERNS.md.
+  </action>
+  <verify>Otwórz CONCERNS.md — wpis o nullableString nie istnieje. Plik jest poprawnym Markdownem.</verify>
+  <done>AC-4 spełnione: wpis usunięty z CONCERNS.md</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- Logika biznesowa wewnątrz helperów — przepisz 1:1 do StringHelper, nie zmieniaj zachowania
+- Żadne inne metody w modyfikowanych klasach
+- Inne sekcje w CONCERNS.md
+- Testy, migracje, widoki, zasoby statyczne
+
+## SCOPE LIMITS
+- Tylko 3 metody: nullableString, normalizeDateTime, normalizeColorHex
+- Nie refaktoryzuj innych prywatnych helperów przy okazji
+- Nie przenoś plików ani nie zmieniaj namespace'ów innych klas
+- Nie dodawaj nowych zależności (composer)
+
+</boundaries>
+
+<verification>
+Przed zamknięciem planu sprawdź:
+- [ ] php -l src/Core/Support/StringHelper.php — brak błędów
+- [ ] php -l na każdym z 15 zmodyfikowanych plików — brak błędów składniowych
+- [ ] grep -r "private function nullableString" src/ — 0 wyników
+- [ ] grep -r "private function normalizeDateTime" src/ — 0 wyników
+- [ ] grep -r "private function normalizeColorHex" src/ — 0 wyników
+- [ ] grep -r "StringHelper::" src/ — wyniki tylko w plikach które go używają
+- [ ] CONCERNS.md — wpis [HIGH] Duplicated helpers nie istnieje
+- [ ] Wszystkie kryteria akceptacji spełnione
+</verification>
+
+<success_criteria>
+- StringHelper.php utworzony z 3 poprawnymi metodami statycznymi
+- 0 prywatnych kopii tych metod pozostało w src/
+- Wszystkie wywołania przekierowane na StringHelper::
+- CONCERNS.md zaktualizowany — wpis usunięty
+- Brak błędów składniowych PHP w zmodyfikowanych plikach
+</success_criteria>
+
+<output>
+Po zakończeniu utwórz `.paul/phases/01-tech-debt/01-02-SUMMARY.md`
+</output>