feat(domain): Domain\Scontainers + Domain\Banners repositories z wrapper delegation

Phase 3 complete: - ScontainersRepository: containerDetails, containerSave, containerDelete, scontainerByLang - BannersRepository: bannerDetails, bannerSave, bannerDelete, activeBanners, mainBanner - 4 legacy factories converted to thin wrappers delegating to Domain repos Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 18:04:42 +02:00
parent 7949e9b6a3
commit 73ff0ca5b6
11 changed files with 612 additions and 286 deletions
--- a/.paul/PROJECT.md
+++ b/.paul/PROJECT.md
@@ -7,10 +7,11 @@ Autorski system CMS z panelem administracyjnym (17 modułów admin, 13 modułów
 Autorski system CMS umożliwiający zarządzanie treściami i stronami internetowymi.

 ## Already Completed
- Domain (6 repos): Articles, Languages, Layouts, Pages, Settings, User
- Shared (5 modules): Cache, Helpers, Html, Image, Tpl
+- Domain (8 repos): Articles, Languages, Layouts, Pages, Settings, User, Scontainers, Banners
+- Shared (7 modules): Cache, Helpers, Html, Image, Tpl, Email, Security
 - Form Edit System: FormEditViewModel, multi-tab, validation, persistence
 - PHPUnit base: Bootstrap, 3 test files
+- Wrapper delegation pattern: legacy factories delegate to Domain repositories

 ## Requirements

@@ -45,3 +46,4 @@ Autorski system CMS umożliwiający zarządzanie treściami i stronami interneto

 ---
 *Created: 2026-04-04*
+*Last updated: 2026-04-04 after Phase 3*
--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@@ -6,7 +6,7 @@ Pełna refaktoryzacja cmsPRO do architektury DDD wzorowanej na shopPRO. Wzorzec:
 ## Current Milestone
 **v0.1 Refaktoryzacja** (v0.1.0)
 Status: In progress
-Phases: 2 of 19 complete
+Phases: 3 of 19 complete

 ## Already Completed (before PAUL)
 - **Domain (6 repos):** Articles, Languages, Layouts, Pages, Settings, User
@@ -20,7 +20,7 @@ Phases: 2 of 19 complete
 |-------|------|-------|--------|-----------|
 | 1 | Infrastructure & Autoloader | 1 | Complete | 2026-04-04 |
 | 2 | Shared: Email + Security | 1 | Complete | 2026-04-04 |
-| 3 | Domain: Scontainers + Banners | 1 | Not started | - |
+| 3 | Domain: Scontainers + Banners | 1 | Complete | 2026-04-04 |
 | 4 | Domain: Authors + Newsletter | 1 | Not started | - |
 | 5 | Domain: SeoAdditional + Cron + Releases | 1 | Not started | - |
 | 6 | Admin: Base Infrastructure | 1 | Not started | - |
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -5,18 +5,18 @@
 See: .paul/PROJECT.md (updated 2026-04-04)

 **Core value:** Autorski system CMS umożliwiający zarządzanie treściami i stronami internetowymi.
-**Current focus:** Phase 2 complete — ready for Phase 3
+**Current focus:** Phase 3 complete — ready for Phase 4

 ## Current Position

 Milestone: v0.1 Refaktoryzacja
-Phase: 2 of 19 (Shared: Email + Security) — Complete
-Plan: 02-01 complete
+Phase: 3 of 19 (Domain: Scontainers + Banners) — Complete
+Plan: 03-01 complete
 Status: Loop closed, ready for next PLAN
-Last activity: 2026-04-04 — Phase 2 complete, UNIFY done
+Last activity: 2026-04-04 — Phase 3 complete, UNIFY done

 Progress:
- Milestone: [▓░░░░░░░░░] 10%
+- Milestone: [▓▓░░░░░░░░] 15%

 ## Loop Position

@@ -29,8 +29,8 @@ PLAN ──▶ APPLY ──▶ UNIFY
 ## Performance Metrics

 **Velocity:**
- Total plans completed: 2
- Total execution time: ~18min
+- Total plans completed: 3
+- Total execution time: ~20min

 **By Phase:**

@@ -38,6 +38,7 @@ PLAN ──▶ APPLY ──▶ UNIFY
 |-------|-------|------------|----------|
 | 01-infrastructure | 1/1 | ~10min | ~10min |
 | 02-shared-email-security | 1/1 | ~8min | ~8min |
+| 03-domain-scontainers-banners | 1/1 | ~2min | ~2min |

 ## Accumulated Context

@@ -46,6 +47,9 @@ PLAN ──▶ APPLY ──▶ UNIFY
 - CsrfToken: single token per session (shopPRO pattern)
 - Email: PHPMailer require via __DIR__ absolute paths
 - Shared layer kompletny: Cache, Helpers, Html, Image, Tpl, Email, Security
+- Wrapper delegation: factory creates new repo per call (no singleton)
+- Front repos: $lang[0] passed explicitly, repos don't use globals
+- Front caching: migrated from \Cache:: to \Shared\Cache\CacheHandler::

 ### Deferred Issues
 None.
@@ -56,9 +60,9 @@ None.
 ## Session Continuity

 Last session: 2026-04-04
-Stopped at: Phase 2 complete, loop closed
-Next action: Run /paul:plan for Phase 3 (Domain: Scontainers + Banners)
-Resume file: .paul/phases/02-shared-email-security/02-01-SUMMARY.md
+Stopped at: Phase 3 complete, loop closed
+Next action: Run /paul:plan for Phase 4 (Domain: Authors + Newsletter)
+Resume file: .paul/phases/03-domain-scontainers-banners/03-01-SUMMARY.md

 ---
 *STATE.md — Updated after every significant action*
--- a/.paul/phases/03-domain-scontainers-banners/03-01-PLAN.md
+++ b/.paul/phases/03-domain-scontainers-banners/03-01-PLAN.md
@@ -0,0 +1,198 @@
+---
+phase: 03-domain-scontainers-banners
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - autoload/Domain/Scontainers/ScontainersRepository.php
+  - autoload/Domain/Banners/BannersRepository.php
+  - autoload/admin/factory/class.Scontainers.php
+  - autoload/admin/factory/class.Banners.php
+  - autoload/front/factory/class.Scontainers.php
+  - autoload/front/factory/class.Banners.php
+autonomous: true
+delegation: auto
+---
+
+<objective>
+## Goal
+Create Domain\Scontainers\ScontainersRepository and Domain\Banners\BannersRepository, then convert legacy factory classes to wrapper delegation.
+
+## Purpose
+Continue DDD refactoring — migrate Scontainers and Banners data access from static factory methods (global $mdb) to injected-dependency Domain repositories. Establishes wrapper delegation pattern for the first time in the project.
+
+## Output
+- 2 new Domain repository files
+- 4 legacy factory files converted to wrappers
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@autoload/admin/factory/class.Scontainers.php
+@autoload/admin/factory/class.Banners.php
+@autoload/front/factory/class.Scontainers.php
+@autoload/front/factory/class.Banners.php
+@autoload/Domain/Languages/LanguagesRepository.php (pattern reference)
+</context>
+
+<acceptance_criteria>
+
+## AC-1: ScontainersRepository exists with all methods
+```gherkin
+Given the autoloader is configured for Domain\ namespace
+When ScontainersRepository is instantiated with $db (Medoo)
+Then it provides containerDetails(), containerSave(), containerDelete(), scontainerByLang() methods
+And all methods use $this->db instead of global $mdb
+```
+
+## AC-2: BannersRepository exists with all methods
+```gherkin
+Given the autoloader is configured for Domain\ namespace
+When BannersRepository is instantiated with $db (Medoo)
+Then it provides bannerDetails(), bannerSave(), bannerDelete(), activeBanners(), mainBanner() methods
+And all methods use $this->db instead of global $mdb
+```
+
+## AC-3: Legacy admin factories delegate to repositories
+```gherkin
+Given admin\factory\Scontainers and admin\factory\Banners exist
+When their static methods are called (e.g. container_save(), banner_delete())
+Then they instantiate the Domain repository with global $mdb
+And delegate the call to the corresponding repository method
+And return the same result as before
+```
+
+## AC-4: Legacy front factories delegate to repositories
+```gherkin
+Given front\factory\Scontainers and front\factory\Banners exist
+When their static methods are called (e.g. scontainer_details(), banners())
+Then they delegate to the Domain repository
+And caching behavior is preserved (Cache::fetch/store in repository)
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create ScontainersRepository and BannersRepository</name>
+  <files>autoload/Domain/Scontainers/ScontainersRepository.php, autoload/Domain/Banners/BannersRepository.php</files>
+  <action>
+    Create Domain\Scontainers\ScontainersRepository following LanguagesRepository pattern:
+    - namespace Domain\Scontainers
+    - Constructor: __construct($db) storing Medoo instance
+    - containerDetails($containerId): get from pp_scontainers + pp_scontainers_langs (all langs)
+    - containerSave($containerId, $title, $text, $status, $showTitle, $src, $html): insert/update pp_scontainers + pp_scontainers_langs with multi-language support. Handle single-lang vs multi-lang arrays exactly as current factory does. Call \S::delete_cache() after.
+    - containerDelete($containerId): delete from pp_scontainers, call \S::delete_cache()
+    - scontainerByLang($scontainerId, $langId): get container + single lang translation, use \Shared\Cache\CacheHandler::fetch/store (migrate from \Cache:: to \Shared\Cache\CacheHandler::)
+
+    Create Domain\Banners\BannersRepository following same pattern:
+    - namespace Domain\Banners
+    - Constructor: __construct($db)
+    - bannerDetails($bannerId): get from pp_banners + pp_banners_langs (all langs)
+    - bannerSave($bannerId, $name, $status, $dateStart, $dateEnd, $homePage, $src, $url, $html, $text): insert/update pp_banners + pp_banners_langs. Handle single/multi lang arrays. Call \S::delete_cache().
+    - bannerDelete($bannerId): delete from pp_banners, call \S::delete_cache()
+    - activeBanners($langId): active non-homepage banners with date filtering, use \Shared\Cache\CacheHandler for caching
+    - mainBanner($langId): single active homepage banner with date filtering, cached
+
+    IMPORTANT:
+    - PHP < 8.0 compatible (no match, no named args, no union types, no str_contains)
+    - Use $this->db->query() for complex SQL (date filtering in Banners) — keep raw SQL identical to current factory
+    - Multi-language save pattern: query pp_langs for active languages, loop and insert translations
+    - Status/checkbox conversion ('on' → 1, else 0) stays in repository methods
+  </action>
+  <verify>php -l autoload/Domain/Scontainers/ScontainersRepository.php && php -l autoload/Domain/Banners/BannersRepository.php</verify>
+  <done>AC-1 and AC-2 satisfied: Both repositories exist with all methods, use injected $db</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Convert legacy factories to wrapper delegation</name>
+  <files>autoload/admin/factory/class.Scontainers.php, autoload/admin/factory/class.Banners.php, autoload/front/factory/class.Scontainers.php, autoload/front/factory/class.Banners.php</files>
+  <action>
+    Convert all 4 factory files to thin wrappers that delegate to Domain repositories.
+
+    Pattern for each static method:
+    ```php
+    public static function method_name($args)
+    {
+      global $mdb;
+      $repo = new \Domain\Scontainers\ScontainersRepository($mdb);
+      return $repo->methodName($args);
+    }
+    ```
+
+    admin\factory\Scontainers:
+    - container_delete($id) → $repo->containerDelete($id)
+    - container_save(...) → $repo->containerSave(...)
+    - container_details($id) → $repo->containerDetails($id)
+
+    admin\factory\Banners:
+    - banner_delete($id) → $repo->bannerDelete($id)
+    - banner_save(...) → $repo->bannerSave(...)
+    - banner_details($id) → $repo->bannerDetails($id)
+
+    front\factory\Scontainers:
+    - scontainer_details($id) → $repo->scontainerByLang($id, $lang[0]) — note: use global $lang
+
+    front\factory\Banners:
+    - banners() → $repo->activeBanners($lang[0])
+    - main_banner() → $repo->mainBanner($lang[0])
+
+    IMPORTANT:
+    - Keep namespace declarations unchanged (admin\factory, front\factory)
+    - Keep method signatures identical (same parameter names and order)
+    - For front factories: pass $lang[0] explicitly to repository (repo does NOT use global $lang)
+  </action>
+  <verify>php -l autoload/admin/factory/class.Scontainers.php && php -l autoload/admin/factory/class.Banners.php && php -l autoload/front/factory/class.Scontainers.php && php -l autoload/front/factory/class.Banners.php</verify>
+  <done>AC-3 and AC-4 satisfied: All legacy factories delegate to Domain repositories, signatures unchanged</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- autoload/autoloader.php (autoloader stable)
+- composer.json (PSR-4 mapping already includes Domain\)
+- autoload/admin/controls/class.Scontainers.php (admin controllers — Phase 10)
+- autoload/admin/controls/class.Banners.php (admin controllers — Phase 10)
+- autoload/admin/view/ (admin views — later phases)
+- autoload/front/view/ (front views — later phases)
+- autoload/class.Scontainer.php (legacy ArrayAccess entity — separate concern)
+- Any existing Domain\ repositories (Articles, Languages, Layouts, Pages, Settings, User)
+
+## SCOPE LIMITS
+- Only factory → repository migration, NOT admin controllers or views
+- No new Composer dependencies
+- No database schema changes
+- Do not refactor the multi-language save pattern (keep it working as-is)
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] php -l passes for all 6 files (2 new + 4 modified)
+- [ ] ScontainersRepository has: containerDetails, containerSave, containerDelete, scontainerByLang
+- [ ] BannersRepository has: bannerDetails, bannerSave, bannerDelete, activeBanners, mainBanner
+- [ ] All 4 factory files are thin wrappers (no direct $mdb usage, only delegation)
+- [ ] No PHP 8.0+ syntax used
+- [ ] \S::delete_cache() calls preserved in repository methods
+- [ ] Caching (\Shared\Cache\CacheHandler) used in front-facing repository methods
+</verification>
+
+<success_criteria>
+- All tasks completed
+- All verification checks pass
+- Zero regression — factory method signatures unchanged
+- Domain repositories follow established pattern (constructor DI, $this->db)
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/03-domain-scontainers-banners/03-01-SUMMARY.md`
+</output>
--- a/.paul/phases/03-domain-scontainers-banners/03-01-SUMMARY.md
+++ b/.paul/phases/03-domain-scontainers-banners/03-01-SUMMARY.md
@@ -0,0 +1,115 @@
+---
+phase: 03-domain-scontainers-banners
+plan: 01
+subsystem: domain
+tags: [medoo, repository, scontainers, banners, wrapper-delegation]
+
+requires:
+  - phase: 01-infrastructure
+    provides: PSR-4 autoloader for Domain\ namespace
+
+provides:
+  - Domain\Scontainers\ScontainersRepository
+  - Domain\Banners\BannersRepository
+  - Wrapper delegation pattern (first usage in project)
+
+affects: [phase-10-admin-banners-authors-scontainers, phase-15-front-pages-menu-banners-scontainers]
+
+tech-stack:
+  added: []
+  patterns: [wrapper-delegation, domain-repository-with-cache]
+
+key-files:
+  created:
+    - autoload/Domain/Scontainers/ScontainersRepository.php
+    - autoload/Domain/Banners/BannersRepository.php
+  modified:
+    - autoload/admin/factory/class.Scontainers.php
+    - autoload/admin/factory/class.Banners.php
+    - autoload/front/factory/class.Scontainers.php
+    - autoload/front/factory/class.Banners.php
+
+key-decisions:
+  - "Wrapper delegation pattern: factory static methods delegate to repo instances via global $mdb"
+  - "Front factories pass $lang[0] explicitly — repositories do not use global $lang"
+  - "Caching migrated from \\Cache:: to \\Shared\\Cache\\CacheHandler:: in repository layer"
+
+patterns-established:
+  - "Wrapper delegation: global $mdb; $repo = new \\Domain\\X\\XRepository($mdb); return $repo->method()"
+  - "Front factory passes language ID explicitly to repository"
+
+duration: ~2min
+started: 2026-04-04T00:00:00Z
+completed: 2026-04-04T00:00:00Z
+---
+
+# Phase 3 Plan 01: Scontainers + Banners Repositories Summary
+
+**Domain repositories for Scontainers and Banners with wrapper delegation in all 4 legacy factories.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~2min |
+| Tasks | 2 completed (delegated) |
+| Files created | 2 |
+| Files modified | 4 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: ScontainersRepository exists with all methods | Pass | 5 methods (incl. constructor), 110 lines |
+| AC-2: BannersRepository exists with all methods | Pass | 6 methods (incl. constructor), 148 lines |
+| AC-3: Legacy admin factories delegate to repositories | Pass | 6 static methods → thin wrappers |
+| AC-4: Legacy front factories delegate to repositories | Pass | 3 static methods → thin wrappers, $lang[0] passed explicitly |
+
+## Accomplishments
+
+- Created ScontainersRepository with containerDetails, containerSave, containerDelete, scontainerByLang
+- Created BannersRepository with bannerDetails, bannerSave, bannerDelete, activeBanners, mainBanner
+- Established wrapper delegation pattern — first usage in the project, template for all future phases
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `autoload/Domain/Scontainers/ScontainersRepository.php` | Created | Domain repository for scontainers CRUD + cached front read |
+| `autoload/Domain/Banners/BannersRepository.php` | Created | Domain repository for banners CRUD + cached active/main banner |
+| `autoload/admin/factory/class.Scontainers.php` | Modified | Wrapper: 3 methods delegate to ScontainersRepository |
+| `autoload/admin/factory/class.Banners.php` | Modified | Wrapper: 3 methods delegate to BannersRepository |
+| `autoload/front/factory/class.Scontainers.php` | Modified | Wrapper: 1 method delegates with $lang[0] |
+| `autoload/front/factory/class.Banners.php` | Modified | Wrapper: 2 methods delegate with $lang[0] |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Wrapper creates new repo instance per call | Matches static factory pattern, no singleton needed | Simple, no state leaks between calls |
+| Front repos use CacheHandler, not \Cache | Aligns with Shared layer conventions | Consistent caching across Domain layer |
+| $lang[0] passed as parameter, not global in repo | Repositories should not depend on globals | Cleaner, testable API |
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Domain\Scontainers and Domain\Banners available for Admin controllers (Phase 10)
+- Wrapper delegation pattern established for future Domain phases (4, 5)
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 03-domain-scontainers-banners, Plan: 01*
+*Completed: 2026-04-04*