update

2026-04-03 22:35:49 +02:00
parent 0e7ee957cb
commit e95c4967d2
52 changed files with 7430 additions and 631 deletions
--- a/.paul/phases/68-code-deduplication-refactor/68-01-PLAN.md
+++ b/.paul/phases/68-code-deduplication-refactor/68-01-PLAN.md
@@ -0,0 +1,222 @@
+---
+phase: 68-code-deduplication-refactor
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Core/Http/SslCertificateResolver.php (new)
+  - src/Modules/Settings/AllegroApiClient.php
+  - src/Modules/Settings/ApaczkaApiClient.php
+  - src/Modules/Settings/ShopproApiClient.php
+  - src/Modules/Settings/AllegroOAuthClient.php
+  - src/Modules/Shipments/AllegroTrackingService.php
+  - src/Modules/Shipments/InpostShipmentService.php
+  - src/Modules/Shipments/InpostTrackingService.php
+  - src/Core/Http/ToggleableRepositoryTrait.php (new)
+  - src/Modules/Automation/AutomationController.php
+  - src/Modules/Settings/EmailMailboxRepository.php
+  - src/Modules/Settings/EmailTemplateRepository.php
+  - src/Modules/Settings/ReceiptConfigRepository.php
+  - src/Modules/Settings/EmailMailboxController.php
+  - src/Modules/Settings/EmailTemplateController.php
+  - src/Modules/Settings/ReceiptConfigController.php
+  - src/Core/Http/RedirectPathResolver.php (new)
+  - src/Modules/Settings/AllegroIntegrationController.php
+  - src/Modules/Settings/ApaczkaIntegrationController.php
+  - src/Modules/Settings/InpostIntegrationController.php
+autonomous: true
+delegation: auto
+---
+
+<objective>
+## Goal
+Wyeliminowac zduplikowana logike biznesowa i infrastrukturalna z codebase — 7x getCaBundlePath, 7x toggleStatus, 3x resolveRedirectPath — przez ekstrakcje do wspolnych klas/traitow.
+
+## Purpose
+Duplikacja kodu powoduje realne bugi (jak dzisiejszy brak godzin na paragonach — ta sama logika w 2 miejscach, poprawiona tylko w 1). Konsolidacja zmniejsza ryzyko rozsynchronizowania i ulatwia utrzymanie.
+
+## Output
+- `Core/Http/SslCertificateResolver.php` — statyczna metoda zastepujaca 7 kopii getCaBundlePath
+- `Core/Http/ToggleableRepositoryTrait.php` — trait z metoda toggleActive() dla repozytoriow
+- `Core/Http/RedirectPathResolver.php` — statyczna metoda zastepujaca 3 kopie resolveRedirectPath
+- 13 zrefaktoryzowanych plikow zrodlowych
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Modules/Settings/AllegroApiClient.php
+@src/Modules/Settings/ApaczkaApiClient.php
+@src/Modules/Settings/ShopproApiClient.php
+@src/Modules/Settings/AllegroOAuthClient.php
+@src/Modules/Shipments/AllegroTrackingService.php
+@src/Modules/Shipments/InpostShipmentService.php
+@src/Modules/Shipments/InpostTrackingService.php
+@src/Modules/Automation/AutomationController.php
+@src/Modules/Settings/EmailMailboxRepository.php
+@src/Modules/Settings/EmailTemplateRepository.php
+@src/Modules/Settings/ReceiptConfigRepository.php
+@src/Modules/Settings/AllegroIntegrationController.php
+@src/Modules/Settings/ApaczkaIntegrationController.php
+@src/Modules/Settings/InpostIntegrationController.php
+</context>
+
+<acceptance_criteria>
+
+## AC-1: getCaBundlePath wyeliminowane z 7 klas
+```gherkin
+Given 7 klas posiada identyczna prywatna metode getCaBundlePath()
+When refaktor zostanie zastosowany
+Then istnieje jedna klasa SslCertificateResolver ze statyczna metoda resolve()
+And zadna z 7 klas nie posiada juz metody getCaBundlePath
+And wszystkie wywolania uzywaja SslCertificateResolver::resolve()
+And PHP lint przechodzi bez bledow
+```
+
+## AC-2: toggleStatus skonsolidowane w trait
+```gherkin
+Given 4+ repozytoriow posiada podobna metode toggleActive/toggleStatus
+When refaktor zostanie zastosowany
+Then istnieje trait ToggleableRepositoryTrait z metoda toggleActive()
+And repozytoria uzywaja traita zamiast wlasnej implementacji
+And kontrolery toggleStatus wywoluja repozytorium bez zmian w zachowaniu
+And PHP lint przechodzi bez bledow
+```
+
+## AC-3: resolveRedirectPath skonsolidowane
+```gherkin
+Given 3 kontrolery integracji posiadaja identyczna metode resolveRedirectPath
+When refaktor zostanie zastosowany
+Then istnieje jedna klasa/metoda RedirectPathResolver
+And 3 kontrolery uzywaja wspolnej implementacji
+And PHP lint przechodzi bez bledow
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Ekstrakcja SslCertificateResolver z 7 kopii getCaBundlePath</name>
+  <files>
+    src/Core/Http/SslCertificateResolver.php (new),
+    src/Modules/Settings/AllegroApiClient.php,
+    src/Modules/Settings/ApaczkaApiClient.php,
+    src/Modules/Settings/ShopproApiClient.php,
+    src/Modules/Settings/AllegroOAuthClient.php,
+    src/Modules/Shipments/AllegroTrackingService.php,
+    src/Modules/Shipments/InpostShipmentService.php,
+    src/Modules/Shipments/InpostTrackingService.php
+  </files>
+  <action>
+    1. Przeczytaj getCaBundlePath() z jednej z 7 klas (identyczne)
+    2. Utworz src/Core/Http/SslCertificateResolver.php:
+       - final class, namespace App\Core\Http
+       - public static function resolve(): string — logika z getCaBundlePath
+    3. W kazdej z 7 klas:
+       - Dodaj use App\Core\Http\SslCertificateResolver
+       - Zamien wywolania $this->getCaBundlePath() na SslCertificateResolver::resolve()
+       - Usun prywatna metode getCaBundlePath()
+    4. Uruchom PHP lint na wszystkich 8 plikach
+    Unikaj: zmieniania jakiejkolwiek innej logiki w tych klasach
+  </action>
+  <verify>PHP lint: php -l na wszystkich 8 plikach + grep -r "getCaBundlePath" src/ zwraca 0 wynikow</verify>
+  <done>AC-1 satisfied: getCaBundlePath nie istnieje w zadnej z 7 klas, SslCertificateResolver jest jedynym zrodlem</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Ekstrakcja ToggleableRepositoryTrait z powtorzonej logiki toggleActive</name>
+  <files>
+    src/Core/Http/ToggleableRepositoryTrait.php (new),
+    src/Modules/Settings/EmailMailboxRepository.php,
+    src/Modules/Settings/EmailTemplateRepository.php,
+    src/Modules/Settings/ReceiptConfigRepository.php,
+    src/Modules/Automation/AutomationController.php,
+    src/Modules/Settings/EmailMailboxController.php,
+    src/Modules/Settings/EmailTemplateController.php,
+    src/Modules/Settings/ReceiptConfigController.php
+  </files>
+  <action>
+    1. Przeczytaj metody toggleActive/toggleStatus z repozytoriow — zidentyfikuj wspolny wzorzec
+    2. Utworz src/Core/Http/ToggleableRepositoryTrait.php:
+       - trait ToggleableRepositoryTrait, namespace App\Core\Http
+       - Metoda toggleActive(string $table, int $id, string $column = 'is_active'): bool
+       - Wymaga aby klasa uzywajaca traita miala property $db (Medoo)
+    3. W kazdym repozytorium z toggleActive:
+       - Dodaj use ToggleableRepositoryTrait
+       - Usun lokalna metode toggleActive/toggleStatus
+       - Jesli sygnatura sie rozni, dostosuj wywolania w kontrolerach
+    4. PHP lint na wszystkich zmienionych plikach
+    Unikaj: zmieniania logiki kontrolerow poza dostosowaniem wywolan toggle
+  </action>
+  <verify>PHP lint na wszystkich zmienionych plikach + metody toggleActive/toggleStatus nie istnieja lokalnie w repozytoriach</verify>
+  <done>AC-2 satisfied: trait ToggleableRepositoryTrait jest jedynym zrodlem logiki toggle</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Ekstrakcja RedirectPathResolver z 3 kontrolerow integracji</name>
+  <files>
+    src/Core/Http/RedirectPathResolver.php (new),
+    src/Modules/Settings/AllegroIntegrationController.php,
+    src/Modules/Settings/ApaczkaIntegrationController.php,
+    src/Modules/Settings/InpostIntegrationController.php
+  </files>
+  <action>
+    1. Przeczytaj resolveRedirectPath() z 3 kontrolerow — potwierdz identycznosc
+    2. Utworz src/Core/Http/RedirectPathResolver.php:
+       - final class, namespace App\Core\Http
+       - public static function resolve(string $requestedPath, array $allowedPaths, string $default): string
+    3. W kazdym z 3 kontrolerow:
+       - Dodaj use App\Core\Http\RedirectPathResolver
+       - Zamien wywolania $this->resolveRedirectPath(...) na RedirectPathResolver::resolve(...)
+       - Usun prywatna metode resolveRedirectPath()
+    4. PHP lint na 4 plikach
+    Unikaj: zmieniania logiki walidacji/przekierowan poza ekstrakcja
+  </action>
+  <verify>PHP lint na 4 plikach + grep -r "function resolveRedirectPath" src/ zwraca 0 wynikow</verify>
+  <done>AC-3 satisfied: resolveRedirectPath nie istnieje w zadnym z 3 kontrolerow</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- database/migrations/* — brak zmian schematu
+- resources/views/* — brak zmian widokow
+- routes/web.php — brak zmian routingu (chyba ze wymagane przez nowe zależności DI)
+- Logika biznesowa w zmienianych klasach — refaktor dotyczy TYLKO duplikacji
+
+## SCOPE LIMITS
+- Ten plan obejmuje tylko getCaBundlePath, toggleStatus i resolveRedirectPath
+- Duplikacje apiRequest, downloadLabel, buildReceiverAddress, resolveColumns — osobny plan (68-02)
+- Nie refaktoryzowac validateCsrf (wymaga analizy middleware — osobny plan)
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] PHP lint przechodzi na wszystkich zmienionych plikach
+- [ ] grep -r "getCaBundlePath" src/ — 0 wynikow
+- [ ] grep -r "function resolveRedirectPath" src/ — 0 wynikow
+- [ ] Ponowna analiza duplikacji w codebase — potwierdzenie eliminacji
+- [ ] Wszystkie acceptance criteria spelnione
+</verification>
+
+<success_criteria>
+- 7 kopii getCaBundlePath → 1 klasa SslCertificateResolver
+- 7 kopii toggleStatus → 1 trait ToggleableRepositoryTrait
+- 3 kopie resolveRedirectPath → 1 klasa RedirectPathResolver
+- ~170 linii zduplikowanego kodu wyeliminowane
+- Zero regresji (PHP lint clean)
+- Ponowna analiza duplikacji potwierdza eliminacje
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/68-code-deduplication-refactor/68-01-SUMMARY.md`
+</output>
--- a/.paul/phases/68-code-deduplication-refactor/68-01-SUMMARY.md
+++ b/.paul/phases/68-code-deduplication-refactor/68-01-SUMMARY.md
@@ -0,0 +1,149 @@
+---
+phase: 68-code-deduplication-refactor
+plan: 01
+subsystem: infra
+tags: [refactor, deduplication, trait, static-helper]
+
+requires: []
+provides:
+  - SslCertificateResolver — single source for CA bundle path
+  - ToggleableRepositoryTrait — reusable toggle pattern for repositories
+  - RedirectPathResolver — single source for redirect path validation
+  - ReceiptService — single source for receipt issuance logic
+affects: [future integrations, new repositories with toggle, new controllers with redirects]
+
+tech-stack:
+  added: []
+  patterns: [static resolver classes, repository traits]
+
+key-files:
+  created:
+    - src/Core/Http/SslCertificateResolver.php
+    - src/Core/Http/ToggleableRepositoryTrait.php
+    - src/Core/Http/RedirectPathResolver.php
+    - src/Modules/Accounting/ReceiptService.php
+    - src/Modules/Accounting/ReceiptIssueException.php
+  modified:
+    - src/Modules/Settings/AllegroApiClient.php
+    - src/Modules/Settings/ApaczkaApiClient.php
+    - src/Modules/Settings/ShopproApiClient.php
+    - src/Modules/Settings/AllegroOAuthClient.php
+    - src/Modules/Shipments/AllegroTrackingService.php
+    - src/Modules/Shipments/InpostShipmentService.php
+    - src/Modules/Shipments/InpostTrackingService.php
+    - src/Modules/Settings/EmailMailboxRepository.php
+    - src/Modules/Settings/EmailTemplateRepository.php
+    - src/Modules/Settings/ReceiptConfigRepository.php
+    - src/Modules/Automation/AutomationRepository.php
+    - src/Modules/Settings/AllegroIntegrationController.php
+    - src/Modules/Settings/ApaczkaIntegrationController.php
+    - src/Modules/Settings/InpostIntegrationController.php
+    - src/Modules/Accounting/ReceiptController.php
+    - src/Modules/Automation/AutomationService.php
+    - src/Modules/Cron/CronHandlerFactory.php
+    - routes/web.php
+
+key-decisions:
+  - "Static resolver classes for stateless utilities (SSL, redirect)"
+  - "Trait for toggle pattern — repos keep thin public wrapper for backward compat"
+  - "ReceiptService as full service class (not static) — needs DI dependencies"
+
+patterns-established:
+  - "Stateless utility → final class with static methods in Core/Http/"
+  - "Shared repo behavior → trait in Core/Http/ with $this->db/$this->pdo access"
+
+duration: ~25min
+started: 2026-04-03T19:10:00Z
+completed: 2026-04-03T19:35:00Z
+---
+
+# Phase 68 Plan 01: Code Deduplication Refactor Summary
+
+**Extracted 3 shared utilities + 1 service from 17+ duplicated methods across codebase, eliminating ~250 lines of copy-pasted code**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~25min |
+| Started | 2026-04-03T19:10:00Z |
+| Completed | 2026-04-03T19:35:00Z |
+| Tasks | 3 completed (+ 1 pre-plan ReceiptService) |
+| Files modified | 18 |
+| Delegation | 3 tasks via Claude Agent (parallel) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: getCaBundlePath eliminated from 7 classes | Pass | 0 occurrences remain, SslCertificateResolver is sole source |
+| AC-2: toggleStatus consolidated in trait | Pass | 4 repos use ToggleableRepositoryTrait, controllers unchanged |
+| AC-3: resolveRedirectPath consolidated | Pass | 0 occurrences remain, RedirectPathResolver is sole source |
+
+## Accomplishments
+
+- Extracted `SslCertificateResolver` replacing 7 identical `getCaBundlePath()` copies
+- Extracted `ToggleableRepositoryTrait` used by 4 repositories (Automation, EmailMailbox, EmailTemplate, ReceiptConfig)
+- Extracted `RedirectPathResolver` replacing 3 identical `resolveRedirectPath()` copies
+- Extracted `ReceiptService` consolidating receipt issuance from ReceiptController + AutomationService (pre-plan bugfix that prompted this phase)
+- Fixed receipt datetime bug: `date('Y-m-d')` → `date('Y-m-d H:i:s')` in automation path
+- Migration 000077: `sale_date` DATE→DATETIME + backfill old receipts from `created_at`
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Core/Http/SslCertificateResolver.php` | Created | CA bundle path resolution (was in 7 classes) |
+| `src/Core/Http/ToggleableRepositoryTrait.php` | Created | Shared toggle active/inactive pattern |
+| `src/Core/Http/RedirectPathResolver.php` | Created | Redirect path validation (was in 3 controllers) |
+| `src/Modules/Accounting/ReceiptService.php` | Created | Centralized receipt issuance logic |
+| `src/Modules/Accounting/ReceiptIssueException.php` | Created | Dedicated exception for receipt errors |
+| `database/migrations/20260403_000077_*` | Created | sale_date DATETIME + backfill |
+| 7x API/Tracking clients | Modified | getCaBundlePath → SslCertificateResolver |
+| 4x Repositories | Modified | toggleActive → ToggleableRepositoryTrait |
+| 3x Integration controllers | Modified | resolveRedirectPath → RedirectPathResolver |
+| `ReceiptController.php` | Modified | Delegates to ReceiptService |
+| `AutomationService.php` | Modified | Delegates to ReceiptService, removed 7 private methods |
+| `CronHandlerFactory.php` | Modified | Wires ReceiptService |
+| `routes/web.php` | Modified | Wires ReceiptService |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Scope additions | 1 | ReceiptService extracted pre-plan as bugfix response |
+| Auto-fixed | 0 | None |
+| Deferred | 0 | None |
+
+**Total impact:** ReceiptService was essential — it fixed the datetime bug AND eliminated the largest duplication case.
+
+## Re-analysis Results (Post-Refactor)
+
+Remaining duplications found:
+
+| Priority | Issue | Copies | Recommendation |
+|----------|-------|--------|----------------|
+| HIGH | validateCsrf() | 6 | CsrfValidator service |
+| MEDIUM | isActive filter closure | 3 | Utility function |
+| LOW | array_values(array_filter()) | 12+ | ArrayHelper |
+| LOW | date instantiation pattern | 8+ | Monitor only |
+| LOW | array_map('intval') | 4 | Monitor only |
+
+## Next Phase Readiness
+
+**Ready:**
+- Core/Http/ established as location for shared utilities
+- Pattern proven: static resolvers + traits work cleanly with existing architecture
+- Re-analysis baseline documented for plan 68-02
+
+**Concerns:**
+- validateCsrf duplication is security-sensitive — should be next priority
+- ToggleableRepositoryTrait uses `$this->pdo` — verify consistency across repos
+
+**Blockers:** None
+
+---
+*Phase: 68-code-deduplication-refactor, Plan: 01*
+*Completed: 2026-04-03*