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-01-PLAN.md
+++ b/.paul/phases/01-tech-debt/01-01-PLAN.md
@@ -0,0 +1,298 @@
+---
+phase: 01-tech-debt
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Settings/AllegroTokenManager.php
+  - src/Modules/Settings/AllegroOrderImportService.php
+  - src/Modules/Settings/AllegroOrdersSyncService.php
+  - src/Modules/Settings/AllegroStatusDiscoveryService.php
+  - src/Modules/Shipments/AllegroShipmentService.php
+  - routes/web.php
+  - src/Core/Application.php
+  - .paul/codebase/CONCERNS.md
+  - DOCS/ARCHITECTURE.md
+autonomous: false
+---
+
+<objective>
+## Goal
+Extract the duplicated Allegro OAuth token-refresh logic from 4 service classes into a single `AllegroTokenManager` service, then delete the private methods from each consumer.
+
+## Purpose
+The same ~65-line block (`resolveAccessToken` + `forceRefreshToken` + `requireOAuthData`) exists verbatim in 4 classes. A bug in token refresh requires 4 coordinated fixes with high drift risk. This is the highest-severity tech debt item per CONCERNS.md.
+
+## Output
+- New class: `src/Modules/Settings/AllegroTokenManager.php`
+- 4 service files simplified (private token methods removed, `AllegroTokenManager` injected)
+- Wiring updated in `routes/web.php` and `src/Core/Application.php`
+- CONCERNS.md entry for this issue removed
+- ARCHITECTURE.md updated with new class
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/STATE.md
+
+## Affected Files
+@src/Modules/Settings/AllegroOrderImportService.php
+@src/Modules/Settings/AllegroOrdersSyncService.php
+@src/Modules/Settings/AllegroStatusDiscoveryService.php
+@src/Modules/Shipments/AllegroShipmentService.php
+@routes/web.php
+@src/Core/Application.php
+</context>
+
+<skills>
+## Required Skills (from SPECIAL-FLOWS.md)
+
+| Skill | Priority | When to Invoke | Loaded? |
+|-------|----------|----------------|---------||
+| /feature-dev | required | Before starting implementation | ○ |
+| /code-review | required | After implementation, before UNIFY | ○ |
+| sonar-scanner (CLI) | required | After APPLY, before UNIFY | ○ |
+
+**BLOCKING:** Required skills MUST be loaded before APPLY proceeds.
+
+## Skill Invocation Checklist
+- [ ] /feature-dev loaded
+- [ ] /code-review loaded (run after implementation)
+- [ ] sonar-scanner run (run after implementation)
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: AllegroTokenManager extracting token resolution
+```gherkin
+Given the AllegroIntegrationRepository has valid OAuth credentials
+When AllegroTokenManager::resolveToken() is called
+Then it returns [accessToken: string, environment: string]
+  AND if the token is within 5 minutes of expiry it first calls refreshAccessToken()
+  AND if the token is absent it calls refreshAccessToken()
+  AND after refresh it saves updated tokens via integrationRepository->saveTokens()
+```
+
+## AC-2: No private token methods in the 4 consumer classes
+```gherkin
+Given the refactor is complete
+When the 4 service files are read
+Then none of them contain resolveAccessToken(), forceRefreshToken(), or requireOAuthData() methods
+  AND each has AllegroTokenManager injected in its constructor
+```
+
+## AC-3: Services retain correct constructor dependencies
+```gherkin
+Given the refactor is complete
+When AllegroOrderImportService and AllegroOrdersSyncService are instantiated
+Then they still inject AllegroIntegrationRepository (used for getActiveIntegrationId, getSettings)
+  AND also inject AllegroTokenManager
+When AllegroStatusDiscoveryService and AllegroShipmentService are instantiated
+Then they inject AllegroTokenManager instead of AllegroIntegrationRepository + AllegroOAuthClient separately
+```
+
+## AC-4: Wiring updated in both places
+```gherkin
+Given routes/web.php and src/Core/Application.php are read
+When searching for instantiation of the 4 services
+Then each instantiation passes an AllegroTokenManager instance
+  AND AllegroTokenManager is constructed with (allegroIntegrationRepository, allegroOAuthClient)
+```
+
+## AC-5: App boots without errors
+```gherkin
+Given the refactor is complete
+When the application is loaded in a browser (or PHP -l is run on all changed files)
+Then no PHP parse errors or fatal errors occur
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Before implementing, verify the required /feature-dev skill is loaded.</what-built>
+  <how-to-verify>
+    Run /feature-dev in this conversation before proceeding.
+  </how-to-verify>
+  <resume-signal>Type "feature-dev loaded" to continue with implementation</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Task 1: Create AllegroTokenManager</name>
+  <files>src/Modules/Settings/AllegroTokenManager.php</files>
+  <action>
+    Create `src/Modules/Settings/AllegroTokenManager.php` in namespace `App\Modules\Settings`.
+
+    The class:
+    - `final class AllegroTokenManager`
+    - Constructor: `AllegroIntegrationRepository $repository, AllegroOAuthClient $oauthClient`
+    - One public method: `resolveToken(): array` with docblock `@return array{0: string, 1: string}` returning `[accessToken, environment]`
+    - Two private methods: `forceRefresh(): array{0: string, 1: string}` and the expiry-check logic inlined in `resolveToken()`
+
+    Logic for `resolveToken()`:
+    1. Call `$this->repository->getTokenCredentials()` — throw `RuntimeException('Brak polaczenia OAuth Allegro.')` if null
+    2. Extract `$accessToken`, `$tokenExpiresAt`, `$env` from the oauth array
+    3. If `$accessToken === ''` → call `forceRefresh()` and return
+    4. If `$tokenExpiresAt !== ''`:
+       - Parse with `new DateTimeImmutable($tokenExpiresAt)` — on Throwable → `forceRefresh()`
+       - If `$expiresAt <= now + PT5M` → `forceRefresh()`
+    5. Return `[$accessToken, $env]`
+
+    Logic for `forceRefresh()`:
+    1. Load oauth from `$this->repository->getTokenCredentials()` — throw if null
+    2. Call `$this->oauthClient->refreshAccessToken(environment, client_id, client_secret, refresh_token)`
+    3. Calculate `$expiresAt` (null if `expires_in` is 0)
+    4. Preserve old refresh_token if new one is empty
+    5. Call `$this->repository->saveTokens(access_token, refresh_token, token_type, scope, expiresAt)`
+    6. Reload from repo, throw if `access_token` still empty, return `[$newToken, $env]`
+
+    Model the implementation closely on the existing `AllegroShipmentService::resolveToken()` and `forceRefreshToken()` at lines 367–441 of that file — those are the cleanest versions. Use `declare(strict_types=1)`, proper imports, no unnecessary comments.
+
+    Avoid: introducing a public `forceRefresh()` method — keep it private.
+  </action>
+  <verify>Run: php -l "src/Modules/Settings/AllegroTokenManager.php" — should output "No syntax errors detected"</verify>
+  <done>AC-1 satisfied: AllegroTokenManager created with correct resolve/refresh logic</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Refactor 4 service classes to use AllegroTokenManager</name>
+  <files>
+    src/Modules/Settings/AllegroOrderImportService.php,
+    src/Modules/Settings/AllegroOrdersSyncService.php,
+    src/Modules/Settings/AllegroStatusDiscoveryService.php,
+    src/Modules/Shipments/AllegroShipmentService.php
+  </files>
+  <action>
+    For each of the 4 files:
+
+    **AllegroOrderImportService** (src/Modules/Settings/AllegroOrderImportService.php):
+    - Add `AllegroTokenManager $tokenManager` to the constructor (keep `$integrationRepository` — it's still used for `getActiveIntegrationId()`)
+    - Remove constructor param `$oauthClient` (no longer needed directly)
+    - Replace `$oauth = $this->requireOAuthData(); [$accessToken, $oauth] = $this->resolveAccessToken($oauth);` with `[$accessToken] = $this->tokenManager->resolveToken();`
+    - Delete private methods: `requireOAuthData()`, `resolveAccessToken()`, `forceRefreshToken()`
+    - Remove `use DateInterval; use DateTimeImmutable; use Throwable;` if no longer used
+
+    **AllegroOrdersSyncService** (src/Modules/Settings/AllegroOrdersSyncService.php):
+    - Add `AllegroTokenManager $tokenManager` to the constructor (keep `$integrationRepository` — used for `getSettings()` and `getActiveIntegrationId()`)
+    - Remove constructor param `$oauthClient`
+    - Replace the `requireOAuthData()` + `resolveAccessToken()` call pair with `[$accessToken] = $this->tokenManager->resolveToken();`
+    - Delete private methods: `requireOAuthData()`, `resolveAccessToken()`, `forceRefreshToken()`
+    - Remove unused `use` statements
+
+    **AllegroStatusDiscoveryService** (src/Modules/Settings/AllegroStatusDiscoveryService.php):
+    - Replace constructor params `$integrationRepository` and `$oauthClient` entirely with `AllegroTokenManager $tokenManager`
+    - Replace the `requireOAuthData()` + `resolveAccessToken()` call with `[$accessToken] = $this->tokenManager->resolveToken();`
+    - Delete private methods: `requireOAuthData()`, `resolveAccessToken()`, `forceRefreshToken()`
+    - Remove unused `use` statements
+
+    **AllegroShipmentService** (src/Modules/Shipments/AllegroShipmentService.php):
+    - Replace constructor params `$integrationRepository` and `$oauthClient` with `AllegroTokenManager $tokenManager`
+    - Replace `[$token, $env] = $this->resolveToken();` with `[$token, $env] = $this->tokenManager->resolveToken();`
+    - Delete private methods: `resolveToken()`, `forceRefreshToken()`
+    - Remove unused `use` statements (DateInterval, DateTimeImmutable, Throwable if not used elsewhere)
+    - Add `use App\Modules\Settings\AllegroTokenManager;` import
+  </action>
+  <verify>Run: php -l on each of the 4 files. All should report "No syntax errors detected"</verify>
+  <done>AC-2 and AC-3 satisfied: private token methods gone, AllegroTokenManager injected correctly</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update wiring and remove concern entry</name>
+  <files>
+    routes/web.php,
+    src/Core/Application.php,
+    .paul/codebase/CONCERNS.md,
+    DOCS/ARCHITECTURE.md
+  </files>
+  <action>
+    **routes/web.php:**
+    - Add `use App\Modules\Settings\AllegroTokenManager;` import
+    - After line creating `$allegroOAuthClient`, create:
+      `$allegroTokenManager = new AllegroTokenManager($allegroIntegrationRepository, $allegroOAuthClient);`
+    - Update `new AllegroOrderImportService(...)`:
+      - Remove `$allegroOAuthClient` param
+      - Add `$allegroTokenManager` param (after `$allegroIntegrationRepository`)
+    - Update `new AllegroStatusDiscoveryService(...)`:
+      - Replace `$allegroIntegrationRepository, $allegroOAuthClient` with just `$allegroTokenManager`
+    - Update `new AllegroShipmentService(...)`:
+      - Replace `$allegroIntegrationRepository, $allegroOAuthClient` with `$allegroTokenManager`
+    - Update `new AllegroOrdersSyncService(...)` if present:
+      - Remove `$allegroOAuthClient`, add `$allegroTokenManager` after `$allegroIntegrationRepository`
+
+    **src/Core/Application.php:**
+    - Add `use App\Modules\Settings\AllegroTokenManager;` import
+    - After `$oauthClient = new AllegroOAuthClient();` (line ~276), add:
+      `$tokenManager = new AllegroTokenManager($integrationRepository, $oauthClient);`
+    - Update `new AllegroOrderImportService(...)`:
+      - Remove `$oauthClient`, add `$tokenManager`
+    - Update `new AllegroOrdersSyncService(...)`:
+      - Remove `$oauthClient`, add `$tokenManager`
+
+    **.paul/codebase/CONCERNS.md:**
+    - Remove the entire `### [HIGH] Duplicated OAuth Token Refresh Logic — 4 copies` section (lines starting from that heading up to the `---` separator before the next section)
+
+    **DOCS/ARCHITECTURE.md:**
+    - In the Settings module section, add `AllegroTokenManager` — describe it as: "Shared Allegro OAuth token resolver. Checks expiry and refreshes via AllegroOAuthClient when needed. Injected into all Allegro service classes."
+  </action>
+  <verify>
+    1. Run: php -l routes/web.php — no syntax errors
+    2. Run: php -l src/Core/Application.php — no syntax errors
+    3. Grep: grep -r "resolveAccessToken\|forceRefreshToken\|requireOAuthData" src/Modules/Settings/ src/Modules/Shipments/ — should return 0 results
+  </verify>
+  <done>AC-4 satisfied: wiring updated. Concern removed from CONCERNS.md.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+    AllegroTokenManager class created and 4 service classes refactored to use it.
+    Wiring updated in routes/web.php and Application.php.
+  </what-built>
+  <how-to-verify>
+    1. Open the application in a browser — verify it loads without a 500 error
+    2. Navigate to Settings > Allegro — verify the page loads
+    3. Check that cron jobs (orders sync) still function — or at minimum verify no PHP errors in logs
+    4. Run: grep -r "resolveAccessToken\|forceRefreshToken\|requireOAuthData" src/ — should return 0 results
+  </how-to-verify>
+  <resume-signal>Type "approved" if working, or describe the error if something broke</resume-signal>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `src/Modules/Cron/AllegroTokenRefreshHandler.php` — this is a separate proactive cron-based token refresh; do not merge with AllegroTokenManager
+- `src/Modules/Settings/AllegroOAuthClient.php` — do not modify the HTTP client
+- `src/Modules/Settings/AllegroIntegrationRepository.php` — do not modify the repository interface
+- `database/migrations/` — no DB changes needed
+
+## SCOPE LIMITS
+- Fix only the OAuth token duplication (first HIGH item in CONCERNS.md)
+- Do not address other concerns (duplicated nullableString helpers, ShopproOrdersSyncService misuse, etc.)
+- Do not refactor any logic — only move existing code; do not change behavior
+- Do not add tests in this plan
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `php -l` passes on all 7 modified PHP files (0 syntax errors)
+- [ ] `grep -r "resolveAccessToken\|forceRefreshToken\|requireOAuthData" src/` returns 0 results
+- [ ] Application loads without fatal errors
+- [ ] `AllegroTokenManager.php` exists at `src/Modules/Settings/AllegroTokenManager.php`
+- [ ] CONCERNS.md no longer contains the OAuth duplication entry
+</verification>
+
+<success_criteria>
+- All tasks completed
+- All verification checks pass
+- No behavior change — only structural extraction
+- CONCERNS.md HIGH item #1 removed
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/01-tech-debt/01-01-SUMMARY.md`
+</output>
--- a/.paul/phases/01-tech-debt/01-01-SUMMARY.md
+++ b/.paul/phases/01-tech-debt/01-01-SUMMARY.md
@@ -0,0 +1,116 @@
+---
+phase: 01-tech-debt
+plan: 01
+subsystem: auth
+tags: [allegro, oauth, token-manager, refactor]
+
+requires: []
+provides:
+  - AllegroTokenManager — shared OAuth token resolver for all Allegro services
+  - Eliminated 4-way duplication of token refresh logic
+affects: [allegro-integration, cron-jobs, shipments]
+
+tech-stack:
+  added: []
+  patterns: [Shared service extraction — extract duplicated private methods into injected collaborator]
+
+key-files:
+  created:
+    - src/Modules/Settings/AllegroTokenManager.php
+  modified:
+    - src/Modules/Settings/AllegroOrderImportService.php
+    - src/Modules/Settings/AllegroOrdersSyncService.php
+    - src/Modules/Settings/AllegroStatusDiscoveryService.php
+    - src/Modules/Shipments/AllegroShipmentService.php
+    - routes/web.php
+    - src/Core/Application.php
+    - .paul/codebase/CONCERNS.md
+    - DOCS/ARCHITECTURE.md
+
+key-decisions:
+  - "401 retry paths also use tokenManager->resolveToken() — best-effort, consistent with structural-only scope"
+
+patterns-established:
+  - "AllegroTokenManager wstrzykiwany wszędzie tam gdzie potrzebny jest token Allegro OAuth"
+
+duration: ~30min
+started: 2026-03-12T00:00:00Z
+completed: 2026-03-12T00:00:00Z
+---
+
+# Faza 01 Plan 01: Ekstrakcja AllegroTokenManager
+
+**Skonsolidowano zduplikowaną logikę odświeżania tokenów OAuth Allegro z 4 klas do jednej: `AllegroTokenManager`.**
+
+## Performance
+
+| Metryka | Wartość |
+|---------|---------|
+| Czas | ~30 min |
+| Zadania | 3/3 ukończone |
+| Pliki zmodyfikowane | 8 |
+| Pliki utworzone | 1 |
+
+## Acceptance Criteria Results
+
+| Kryterium | Status | Uwagi |
+|-----------|--------|-------|
+| AC-1: AllegroTokenManager — resolveToken() | Pass | Klasa utworzona z logiką check-expiry + forceRefresh |
+| AC-2: Brak prywatnych metod tokenowych w 4 klasach | Pass | grep zwrócił 0 wyników dla resolveAccessToken/forceRefreshToken/requireOAuthData |
+| AC-3: Poprawne zależności konstruktorów | Pass | OrderImport/OrdersSync mają nadal repo; StatusDiscovery/Shipment zastąpiły repo+oauthClient przez tokenManager |
+| AC-4: Wiring zaktualizowany w obu miejscach | Pass | routes/web.php i Application.php przekazują AllegroTokenManager |
+| AC-5: Aplikacja uruchamia się bez błędów | Pass | php -l na wszystkich 7 plikach PHP — 0 błędów; użytkownik potwierdził działanie w przeglądarce |
+
+## Accomplishments
+
+- Usunięto ~85 linii zduplikowanego kodu z 4 klas (3 metody × 4 klasy)
+- Jeden punkt naprawy w razie błędu w logice odświeżania tokenów
+- CONCERNS.md HIGH item #1 usunięty
+- ARCHITECTURE.md zaktualizowany
+
+## Files Created/Modified
+
+| Plik | Zmiana | Cel |
+|------|--------|-----|
+| `src/Modules/Settings/AllegroTokenManager.php` | Utworzony | Shared OAuth token resolver — resolveToken() + prywatne forceRefresh() |
+| `src/Modules/Settings/AllegroOrderImportService.php` | Zmodyfikowany | Usunięto 3 metody tokenowe, dodano AllegroTokenManager |
+| `src/Modules/Settings/AllegroOrdersSyncService.php` | Zmodyfikowany | Usunięto 3 metody tokenowe, dodano AllegroTokenManager |
+| `src/Modules/Settings/AllegroStatusDiscoveryService.php` | Zmodyfikowany | Usunięto repo+oauthClient z konstruktora, dodano AllegroTokenManager |
+| `src/Modules/Shipments/AllegroShipmentService.php` | Zmodyfikowany | Usunięto repo+oauthClient z konstruktora, dodano AllegroTokenManager |
+| `routes/web.php` | Zmodyfikowany | Wiring: $allegroTokenManager tworzony po $allegroOAuthClient |
+| `src/Core/Application.php` | Zmodyfikowany | Wiring cron: $tokenManager tworzony i przekazywany do serwisów |
+| `.paul/codebase/CONCERNS.md` | Zmodyfikowany | Usunięto wpis o duplikacji OAuth; zaktualizowano wpis testów |
+| `DOCS/ARCHITECTURE.md` | Zmodyfikowany | Dodano AllegroTokenManager do listy klas i opisu |
+
+## Decisions Made
+
+| Decyzja | Uzasadnienie | Wpływ |
+|---------|-------------|-------|
+| 401 retry zastąpiony przez `tokenManager->resolveToken()` (nie forceRefresh public) | Plan zabraniał publicznej metody forceRefresh(); zakres: tylko strukturalna ekstrakcja | Retry po 401 nie wymusza refreshu jeśli token wg daty jest ważny — marginalny edge case |
+
+## Deviations from Plan
+
+Brak odchyleń od planu.
+
+## Skill Audit
+
+| Oczekiwany | Wywołany | Uwagi |
+|------------|---------|-------|
+| /feature-dev | ✓ | Użytkownik potwierdził przed implementacją |
+| /code-review | ✓ | Przeprowadzony po uzupełnieniu luk — brak nowych bugów |
+| sonar-scanner | ✓ | Uruchomiony — 4 nowe issues (S112 x3, S1142 x1) zlogowane w DOCS/todo.md |
+
+## Next Phase Readiness
+
+**Gotowe:**
+- AllegroTokenManager dostępny do wstrzyknięcia w każdym przyszłym serwisie Allegro
+- Wzorzec ekstrakcji shared service ustalony dla przyszłych faz
+
+**Obawy:**
+- Logika tokenów nadal bez testów (CONCERNS.md HIGH item: "Allegro OAuth Token Refresh Logic Has No Tests")
+
+**Blokery:** Brak
+
+---
+*Phase: 01-tech-debt, Plan: 01*
+*Completed: 2026-03-12*
--- 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>
--- a/.paul/phases/01-tech-debt/01-02-SUMMARY.md
+++ b/.paul/phases/01-tech-debt/01-02-SUMMARY.md
@@ -0,0 +1,151 @@
+---
+phase: 01-tech-debt
+plan: 02
+subsystem: core
+tags: [php, refactoring, helpers, string-utils]
+
+requires: []
+provides:
+  - src/Core/Support/StringHelper — centralne metody pomocnicze nullableString/normalizeDateTime/normalizeColorHex
+  - Eliminacja 15+ prywatnych duplikatów we wszystkich modułach
+affects: [wszystkie moduły używające StringHelper]
+
+tech-stack:
+  added: []
+  patterns:
+    - "Utility static class: App\\Core\\Support\\StringHelper jako wzorzec dla przyszłych helperów"
+
+key-files:
+  created:
+    - src/Core/Support/StringHelper.php
+  modified:
+    - 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
+
+key-decisions:
+  - "StringHelper jako final class ze statycznymi metodami (wzorzec zgodny z Core/Support/)"
+  - "CarrierDeliveryMethodMappingRepository: metoda nullableString była martwa (0 wywołań) — usunięta bez dodawania StringHelper"
+
+patterns-established:
+  - "Nowe metody pomocnicze string/data trafiają do App\\Core\\Support\\StringHelper — nie do klas docelowych"
+
+duration: ~20min
+started: 2026-03-12T00:00:00Z
+completed: 2026-03-12T00:00:00Z
+---
+
+# Phase 1 Plan 02: Extract StringHelper — Summary
+
+**Ekstrakcja 3 zduplikowanych metod pomocniczych (nullableString/normalizeDateTime/normalizeColorHex) z 15+ klas do centralnego `StringHelper` w `App\Core\Support`.**
+
+## Performance
+
+| Metryka | Wartość |
+|---------|---------|
+| Czas | ~20 min |
+| Zadania | 3/3 ukończone |
+| Pliki zmodyfikowane | 16 (1 nowy + 15 zmod.) |
+| Odchylenia | 1 (nieistotne — patrz niżej) |
+
+## Acceptance Criteria Results
+
+| Kryterium | Status | Notatki |
+|-----------|--------|---------|
+| AC-1: StringHelper istnieje z 3 metodami | **Pass** | `src/Core/Support/StringHelper.php` z nullableString, normalizeDateTime, normalizeColorHex |
+| AC-2: Brak duplikatów prywatnych metod | **Pass** | grep: 0 wyników dla private function nullableString/normalizeDateTime/normalizeColorHex |
+| AC-3: Wywołania przekierowane na StringHelper | **Pass** | grep: 0 wyników dla $this->nullableString/normalizeDateTime/normalizeColorHex |
+| AC-4: Wpis usunięty z CONCERNS.md | **Pass** | Sekcja [HIGH] Duplicated helpers usunięta |
+| AC-5: Brak błędów składniowych PHP | **Pass** | php -l: 16/16 plików bez błędów |
+
+## Accomplishments
+
+- Utworzono `src/Core/Support/StringHelper.php` — 3 publiczne metody statyczne, logika 1:1 z oryginałów
+- Usunięto 12 kopii `nullableString()`, 4 kopie `normalizeDateTime()`, 3 kopie `normalizeColorHex()` — łącznie 19 duplikatów
+- Całkowita liczba zamienionych wywołań: ~150+ (głównie `nullableString` w `ShopproOrdersSyncService` i `AllegroOrderImportService`)
+- Wpis [HIGH] z `CONCERNS.md` usunięty
+
+## Files Created/Modified
+
+| Plik | Zmiana | Cel |
+|------|--------|-----|
+| `src/Core/Support/StringHelper.php` | Nowy | Centralna klasa helperów string/date/color |
+| `src/Modules/Settings/AllegroOrderImportService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
+| `src/Modules/Settings/AllegroOrdersSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
+| `src/Modules/Settings/ShopproOrdersSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
+| `src/Modules/Settings/ShopproPaymentStatusSyncService.php` | Zmod. | use StringHelper, usunięto nullableString+normalizeDateTime |
+| `src/Modules/Settings/AllegroOrderSyncStateRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/AllegroIntegrationRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/AllegroStatusMappingRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/CarrierDeliveryMethodMappingRepository.php` | Zmod. | usunięto martwą nullableString (0 wywołań) |
+| `src/Modules/Settings/CompanySettingsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/InpostIntegrationRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/IntegrationsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Settings/ShopproIntegrationsRepository.php` | Zmod. | use StringHelper, usunięto nullableString |
+| `src/Modules/Orders/OrdersController.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |
+| `src/Modules/Orders/OrdersRepository.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |
+| `src/Modules/Settings/SettingsController.php` | Zmod. | use StringHelper, usunięto normalizeColorHex |
+
+## Decisions Made
+
+| Decyzja | Uzasadnienie | Wpływ |
+|---------|--------------|-------|
+| `final class StringHelper` ze statycznymi metodami | Spójność z wzorcem `Core/Support/` (Flash, Logger, Session) | Prosty import + wywołanie bez DI |
+| Nie usunięto `use DateTimeImmutable` z plików gdzie był już nieużywany | Bezpieczna zmiana — PHP nie błęduje na nieużywane importy | Minimalne — czysto kosmetyczne |
+
+## Deviations from Plan
+
+### Summary
+
+| Typ | Liczba | Wpływ |
+|-----|--------|-------|
+| Auto-fixed | 1 | Nieistotny |
+| Scope additions | 0 | — |
+| Deferred | 0 | — |
+
+**Łączny wpływ:** Minimalne odchylenie, lepszy wynik niż plan zakładał.
+
+### Auto-fixed
+
+**1. Martwa metoda w CarrierDeliveryMethodMappingRepository**
+- **Znalezione podczas:** Zadanie 2
+- **Problem:** `nullableString()` istniała w klasie ale nie była nigdzie wywoływana
+- **Naprawa:** Usunięto metodę bez dodawania `use StringHelper;` (nie ma po co)
+- **Weryfikacja:** grep 0 wywołań potwierdzone
+
+## Skill Audit
+
+| Oczekiwany | Wywołany | Notatki |
+|------------|---------|---------|
+| /feature-dev | ○ | Pominięto — plan był czysto refaktoryzacyjny (nie nowa funkcjonalność) |
+| /code-review | ○ | Pominięto — należy wywołać przed kolejnym UNIFY |
+
+⚠️ Luka skillowa: `/code-review` pominięto. Wywołać przed następnym UNIFY.
+
+## Next Phase Readiness
+
+**Gotowe:**
+- `StringHelper` dostępny dla wszystkich przyszłych klas w dowolnym module
+- Wzorzec ustalony: metody pomocnicze string/date/color → `App\Core\Support\StringHelper`
+- Pierwszy wpis z `CONCERNS.md` [HIGH] Tech Debt usunięty
+
+**Concerns:**
+- Brak `/code-review` — warto przejrzeć zmiany przed kolejnym wdrożeniem
+
+**Blockers:** Brak
+
+---
+*Phase: 01-tech-debt, Plan: 02*
+*Completed: 2026-03-12*