docs: map existing codebase with PAUL

- stack.md - PrestaShop 1.7.x, PHP, Smarty, SCSS, modules - architecture.md - MVC + hooks, override mechanism, CQRS in src/ - structure.md - Directory layout, key file locations - conventions.md - PHP/Smarty/SCSS/JS conventions, PS patterns - testing.md - No automated tests in custom modules - integrations.md - Allegro, Empik, BaseLinker, shipping, payments - concerns.md - Override fragility, EOL risk, missing CI/CD - db_schema.md - Custom tables, modified core tables Co-Authored-By: Claude <noreply@anthropic.com>
2026-04-27 12:41:05 +02:00
parent c5d0a259c7
commit b1e8bb3d12
14 changed files with 1069 additions and 0 deletions
--- a/.paul/PROJECT.md
+++ b/.paul/PROJECT.md
@@ -0,0 +1,30 @@
 # Project: interblue.pl
 ## Description
 Bieżące poprawki i rozwój istniejącego sklepu PrestaShop 1.7.x — elektronika oświetleniowa B2C.
 ## Core Value
 Klienci B2C mogą kupić elektronikę oświetleniową online.
 ## Requirements
 ### Must Have
 - [To be defined during planning]
 ### Should Have
 - [To be defined during planning]
 ### Nice to Have
 - [To be defined during planning]
 ## Constraints
 - PrestaShop 1.7.x — zmiany muszą być kompatybilne z tą wersją
 - Deployment przez FTP (brak CI/CD)
 - Cache PrestaShop musi być czyszczony ręcznie po zmianach PHP/override
 ## Success Criteria
 - Klienci B2C mogą kupić elektronikę oświetleniową online
 - [To be refined during planning]
 ---
 *Created: 2026-04-27*
--- a/.paul/ROADMAP.md
+++ b/.paul/ROADMAP.md
@@ -0,0 +1,22 @@
 # Roadmap: interblue.pl
 ## Overview
 Bieżące poprawki i rozwój istniejącego sklepu PrestaShop 1.7.x (interblue.pl) — elektronika oświetleniowa B2C.
 ## Current Milestone
 **v0.1 Initial Release** (v0.1.0)
 Status: Not started
 Phases: 0 of TBD complete
 ## Phases
 | Phase | Name | Plans | Status | Completed |
 |-------|------|-------|--------|-----------|
 | 1 | TBD | TBD | Not started | - |
 ## Phase Details
 Phases will be defined during `/paul:plan`.
 ---
 *Roadmap created: 2026-04-27*
--- a/.paul/STATE.md
+++ b/.paul/STATE.md
@@ -0,0 +1,48 @@
 # Project State
 ## Project Reference
 See: .paul/PROJECT.md (updated 2026-04-27)
 **Core value:** Klienci B2C mogą kupić elektronikę oświetleniową online
 **Current focus:** Project initialized — ready for planning
 ## Current Position
 Milestone: v0.1 Initial Release
 Phase: Not yet defined
 Plan: None yet
 Status: Ready to create roadmap and first PLAN
 Last activity: 2026-04-27 — Project initialized
 Progress:
 - Milestone: [░░░░░░░░░░] 0%
 ## Loop Position
 Current loop state:
 ```
 PLAN ──▶ APPLY ──▶ UNIFY
  ○        ○        ○     [Ready for first PLAN]
 ```
 ## Accumulated Context
 ### Decisions
 None yet.
 ### Deferred Issues
 None yet.
 ### Blockers/Concerns
 None yet.
 ## Session Continuity
 Last session: 2026-04-27
 Stopped at: Project initialization complete
 Next action: Run /paul:plan to define phases and first plan
 Resume file: .paul/PROJECT.md
 ---
 *STATE.md — Updated after every significant action*
--- a/.paul/codebase/architecture.md
+++ b/.paul/codebase/architecture.md
@@ -0,0 +1,141 @@
 # Architecture
 **Analysis Date:** 2026-04-27
 ## Pattern Overview
 **Overall:** PrestaShop 1.7.x MVC Monolith with Hook System and Override Mechanism
 **Key Characteristics:**
 - Hook-based extensibility (modules register to hooks, PrestaShop fires them)
 - Override mechanism (modules replace core classes by copying to `override/`)
 - Smarty MVC — controllers prepare data, templates render it
 - 133 modules active, many with overrides and custom hooks
 - Symfony components embedded (service container, YAML) in PS 1.7 core
 ## Layers
 **Core PrestaShop Layer:**
 - Purpose: Framework, models, standard controllers
 - Contains: `classes/` (models), `controllers/` (base front/admin), `config/`
 - Key entry: `config/config.inc.php`, `config/bootstrap.php`
 **Override Layer:**
 - Purpose: Replace core classes/controllers without touching core files
 - Contains: `override/classes/`, `override/controllers/`, `override/modules/`
 - Critical overrides: `override/classes/order/Order.php`, `override/classes/Hook.php`, `override/classes/Dispatcher.php`
 - Depends on: Core layer
 - Risk: Multiple modules contributing to same override file
 **Module Layer:**
 - Purpose: Business features, marketplace integrations, shipping, payments
 - Contains: `modules/` (133 modules)
 - Custom modules: `modules/customfeaturetab/`, `modules/AddOrderExtraFields/`
 - Hook registrations in each module's `install()` method
 - Depends on: Override layer + Core layer
 **Theme Layer:**
 - Purpose: Frontend rendering
 - Contains: `themes/InterBlue/templates/` (Smarty .tpl)
 - Assets: `themes/InterBlue/assets/css/`, `themes/InterBlue/assets/js/`
 - Depends on: Module layer (hook output inserted into templates)
 **CQRS Extension Layer (src/):**
 - Purpose: Modern query handling for Order domain
 - Contains: `src/Adapter/Order/QueryHandler/GetOrderForViewingHandler.php`
 - Interface: `src/Core/Domain/Order/QueryHandler/GetOrderForViewingHandlerInterface.php`
 - Result objects: `src/Core/Domain/Order/QueryResult/`
 - Pattern: Adapter bridging legacy PrestaShop to CQRS
 ## Data Flow
 **Frontend HTTP Request:**
 1. HTTP request hits `index.php`
 2. `Dispatcher` (overridden by fsadvancedurl) matches URL to controller
 3. Front controller executes (e.g., `ProductController`)
 4. Controller loads model data, fires hooks
 5. Smarty renders `.tpl` template with data
 6. Module hook outputs inserted at hook positions
 7. Response returned
 **Order Creation:**
 1. Customer submits checkout (via `onepagecheckoutps` — `override/controllers/front/OrderController.php`)
 2. `PaymentModule::validateOrder()` called (overridden in `modules/AddOrderExtraFields/override/classes/PaymentModule.php`)
 3. `actionBeforeAddOrder` hook fires (`override/classes/order/Order.php` — modrefchange)
 4. Order saved to DB with `order_source` field (Allegro/Sklep int./Telefonicznie)
 5. `actionBeforeAddOrderInvoice`, `actionBeforeAddDeliveryNumber` hooks fire
 6. x13allegro module checks if Allegro order, suppresses customer emails if so
 **State Management:**
 - Stateless HTTP requests — all state in MySQL database
 - Session: PrestaShop cookie-based session
 - Cache: Memcached for compiled templates/config
 ## Key Abstractions
 **Module:**
 - Purpose: Self-contained feature unit
 - Examples: `modules/customfeaturetab/customfeaturetab.php`, `modules/x13allegro/x13allegro.php`
 - Pattern: Class extending `Module`, implements `install()`/`uninstall()`, registers hooks
 **ObjectModel:**
 - Purpose: ORM for PrestaShop database tables
 - Examples: `modules/customfeaturetab/classes/CustomFeatureTabRule.php`
 - Pattern: Class extending `ObjectModel` with static `$definition` array
 **Override:**
 - Purpose: Replace core functionality without modifying core files
 - Examples: `override/classes/order/Order.php` extends `OrderCore`
 - Pattern: `class X extends XCore` in `override/` directory
 **Hook:**
 - Purpose: Extension point for modules
 - Execution intercepted: `override/classes/Hook.php` (cookiesplus GDPR filter)
 - Custom hooks: `actionBeforeAddOrder`, `actionBeforeAddOrderInvoice`, `actionBeforeAddDeliveryNumber`
 ## Entry Points
 **Frontend:**
 - URL routing: `override/classes/Dispatcher.php` (fsadvancedurl module)
 - Product pages: `override/controllers/front/ProductController.php`
 - Checkout: `override/controllers/front/OrderController.php` (onepagecheckoutps)
 **Admin Panel:**
 - URL: `/admin658c34/` (randomized for security)
 - Custom admin tabs registered by modules (e.g., "Karty cech produktu")
 **Background Scripts:**
 - `custom-cron.php` — Scheduled tasks
 - `export.php`, `export-csv.php` — Data exports
 - `import-products.php` — Bulk product import
 ## Error Handling
 **Strategy:** Mix — PrestaShop global error handler + per-module ad-hoc
 **Patterns:**
 - Custom modules use minimal error handling
 - `die()` calls found in empikmarketplace admin controllers
 - No global exception handling in custom modules
 - Cache clear required after PHP class changes
 ## Cross-Cutting Concerns
 **Caching:**
 - Memcached for compiled Smarty templates and PS config
 - LiteSpeed cache module (`modules/litespeedcache/`)
 - Manual purge required after changes
 **Translation:**
 - `$this->l('Text')` in all module PHP files
 - Primary locale: Polish (`pl-PL`)
 - No separate `.php` language files in custom modules
 **Security:**
 - Admin URL obfuscation: `admin658c34/`
 - Cookie consent: cookiesplus module intercepts Hook execution
 ---
 *Architecture analysis: 2026-04-27*
 *Update when major patterns change*
--- a/.paul/codebase/concerns.md
+++ b/.paul/codebase/concerns.md
@@ -0,0 +1,146 @@
 # Codebase Concerns
 **Analysis Date:** 2026-04-27
 ## Tech Debt
 **Override Chain Fragility — Order Processing:**
 - Issue: Three modules (modrefchange, AddOrderExtraFields, x13allegro) all modify `Order` class through overlapping overrides
 - Files: `override/classes/order/Order.php`, `modules/modrefchange/override/classes/order/Order.php`, `modules/AddOrderExtraFields/_overrides/classes/order/Order-modrefchange.php`
 - Why: Each module added override independently without documentation of interdependencies
 - Impact: Hook execution order undocumented; disabling modrefchange orphans hooks; AddOrderExtraFields install copies override file (fragile)
 - Fix approach: Document hook execution order, add comments to override file explaining all contributing modules
 **Payment Module Logic Bug:**
 - Issue: Operator precedence bug in order source detection
 - Files: `modules/AddOrderExtraFields/override/classes/PaymentModule.php` (line ~350)
 - Code: `if (!$order->module == 'x13allegro')` — evaluates as `!(false) == 'x13allegro'` not as intended
 - Impact: Order source may be incorrectly set in edge cases
 - Fix approach: Change to `if ($order->module !== 'x13allegro')`
 **One-Page Checkout Controller Duplication:**
 - Issue: `override/controllers/front/OrderController.php` (root, 653 lines) and `modules/onepagecheckoutps/public/override/controllers/front/OrderController.php` both exist; PS loads root override only
 - Files: `override/controllers/front/OrderController.php`, `modules/onepagecheckoutps/public/override/controllers/front/OrderController.php`
 - Impact: Module override is silently ignored; confusion when updating module
 - Fix approach: Document that root override is authoritative; remove or flag module copy
 ## Known Bugs
 **Die() Calls in Empikmarketplace:**
 - Symptoms: Admin pages may crash without user-friendly error
 - Files: `modules/empikmarketplace/controllers/admin/AdminEmpikOffersController.php`, `modules/empikmarketplace/controllers/admin/AdminEmpikProductsController.php`, `modules/empikmarketplace/controllers/front/cron.php`
 - Workaround: None — admin must retry operation
 - Root cause: Missing try/catch and error recovery in module controllers
 **Dev Mode IP Hardcoded:**
 - Symptoms: Debug mode silently enabled for traffic from specific IP
 - Files: `config/defines.inc.php` (line 28)
 - Risk: Exposes debug info if that IP is compromised or reused
 - Fix: Move dev detection to environment variable or remove entirely
 ## Security Considerations
 **Dispatcher URL Parsing — Potential Injection:**
 - Risk: Regex in `override/classes/Dispatcher.php` (line 69) parses raw `$_GET` without sanitization
 - Files: `override/classes/Dispatcher.php`
 - Current mitigation: PrestaShop built-in URL sanitization may catch most cases
 - Recommendations: Audit regex patterns, validate extracted values before use
 **Admin Path Obfuscation Only:**
 - Risk: `admin658c34/` relies on obscurity alone (no 2FA, IP restriction visible)
 - Files: `admin658c34/`
 - Current mitigation: Randomized folder name
 - Recommendations: Enable 2FA if supported, IP-restrict admin if hosting allows
 **Order Source Enum Hardcoded:**
 - Risk: `order_source` enum in `ps_orders` only allows ('Allegro', 'Sklep int.', 'Telefonicznie') — new order sources require DB migration
 - Files: `modules/AddOrderExtraFields/AddOrderExtraFields.php`
 - Recommendations: Consider VARCHAR with application-level validation instead of enum
 ## Performance Bottlenecks
 **Empikmarketplace Admin Views:**
 - Problem: Module overrides admin product catalog list views with custom Twig templates
 - Files: `modules/empikmarketplace/views/PrestaShop/Admin/Product/CatalogPage/Lists/list.html.twig`, `products_table.html.twig`
 - Impact: Admin product list may be slower or behave unexpectedly after empikmarketplace updates
 - Improvement: Keep module updated; test after each module upgrade
 **No Indexes on Custom Feature Tab:**
 - Problem: `ps_custom_feature_tab` has no index on `id_feature` or `id_feature_value`
 - Files: `modules/customfeaturetab/customfeaturetab.php` (table creation SQL)
 - Impact: Slow queries when many products loaded (full table scan per product)
 - Fix: `ALTER TABLE ps_custom_feature_tab ADD INDEX (id_feature, id_feature_value)`
 ## Fragile Areas
 **Override Load Order:**
 - Files: All files in `override/classes/` and `override/controllers/`
 - Why fragile: PrestaShop loads overrides alphabetically; installing new modules with overlapping overrides can silently fail or corrupt class index
 - Safe modification: Always clear `var/cache/*/class_index.php` after adding/modifying overrides
 - Test coverage: None
 **Hook System Intercept (cookiesplus):**
 - Files: `override/classes/Hook.php`
 - Why fragile: cookiesplus intercepts ALL hook execution for GDPR consent; if module corrupts its config, hooks may silently fail site-wide
 - Common failure: Module misconfiguration blocks legitimate module output
 - Safe modification: Test in staging if possible before enabling
 ## Scaling Limits
 **PrestaShop 1.7.x End of Life:**
 - Current capacity: Working for current traffic
 - Risk: No official security patches available for 1.7.x
 - Impact: Accumulating unpatched vulnerabilities in core and 45+ vendor dependencies
 - Scaling path: Plan migration to PrestaShop 8.x (significant effort)
 **No CI/CD — Manual FTP Deployment:**
 - Current: Changes deployed manually via FTP from VSCode
 - Risk: Human error, no rollback mechanism, no pre-deploy validation
 - Impact: Broken deployments require manual FTP rollback
 ## Dependencies at Risk
 **PrestaShop 1.7.x:**
 - Risk: End of life — no more security fixes
 - Impact: All custom modules, theme, overrides would need migration
 - Migration plan: PrestaShop 8.x upgrade (breaking changes in module APIs)
 **x13allegro (Allegro API):**
 - Risk: Allegro REST API versioning — module may need updates when API changes
 - Impact: Allegro order sync breaks if module not updated
 - Migration plan: Keep module updated; monitor x13.pl module updates
 **onepagecheckoutps (v1.0.1):**
 - Risk: Old version, complex OrderController override (653 lines)
 - Impact: Checkout flow breaks on PS updates
 - Migration plan: Test and update before any PS core updates
 ## Missing Critical Features
 **No Automated Testing:**
 - Problem: Zero automated tests for custom modules
 - Blocks: Confidence in refactoring, PS upgrade path verification
 - Implementation complexity: Medium (PHPUnit setup per module)
 **No Staging Environment:**
 - Problem: Changes go directly to production
 - Current workaround: Test manually in production during low-traffic hours
 - Blocks: Safe testing of marketplace integrations, checkout changes
 - Implementation complexity: Medium (duplicate hosting setup)
 **No Rollback Mechanism:**
 - Problem: No automated rollback for failed deployments
 - Current workaround: Restore via FTP from backup
 - Blocks: Confidence in deploying risky changes
 ## Database Design Issues
 **utf8 vs utf8mb4:**
 - Files: `modules/customfeaturetab/customfeaturetab.php` (CREATE TABLE uses `utf8`)
 - Risk: Cannot store 4-byte Unicode characters (some emoji, rare CJK)
 - Fix: Migrate custom tables to `utf8mb4` charset
 ---
 *Concerns audit: 2026-04-27*
 *Update as issues are fixed or new ones discovered*
--- a/.paul/codebase/conventions.md
+++ b/.paul/codebase/conventions.md
@@ -0,0 +1,123 @@
 # Coding Conventions
 **Analysis Date:** 2026-04-27
 ## Naming Patterns
 **Files:**
 - Module main file: `{modulename}.php` (lowercase, no hyphens)
 - ObjectModel classes: PascalCase — `CustomFeatureTabRule.php`
 - Admin controllers: `Admin{Name}Controller.php`
 - Templates: `{page-name}.tpl` (kebab-case)
 **Classes:**
 - Modules: PascalCase matching folder — `class CustomFeatureTab extends Module`
 - ObjectModels: PascalCase — `class CustomFeatureTabRule extends ObjectModel`
 - Overrides: same name as core — `class Order extends OrderCore`
 - Admin controllers: `class AdminCustomFeatureTabController extends ModuleAdminController`
 **Methods:**
 - camelCase for all methods: `install()`, `getMatchingRules()`, `installDb()`
 - Hook methods: `hook{HookName}()` — e.g., `hookDisplayProductExtraContent($params)`
 - AJAX handlers: `ajaxProcess{ActionName}()` — e.g., `ajaxProcessGetFeatureValues()`
 - Private helpers: underscore prefix — `_installDb()`, `_uninstallDb()`
 **Variables:**
 - camelCase: `$featureValue`, `$tabContent`
 - Constants: `UPPER_SNAKE_CASE` — `_DB_PREFIX_`, `_PS_VERSION_`, `_MYSQL_ENGINE_`
 ## Code Style
 **PHP:**
 - Indentation: 4 spaces (custom modules); some legacy (AddOrderExtraFields) uses 2 spaces
 - No strict line length limit observed
 - Every PHP file begins with: `if (!defined('_PS_VERSION_')) exit;`
 **SCSS:**
 - Tool: VSCode Live Sass Compiler
 - Compile directives at top: `// out: custom.css, compress: true, sourceMap: true`
 - Variables: `$cOrange: #ff7100;`, `$cBlue: #218fff;`
 - Section separators: `/** Sekcja *****/` comment blocks (Polish labels)
 - Comments in Polish
 - Output: compressed CSS with sourcemap
 **JavaScript:**
 - jQuery as primary framework: `$()`, `$(function() { ... })`
 - camelCase variables: `scrollTrigger`, `backToTop`, `phoneBox`
 - Polish comments for feature descriptions
 - Event handlers: `$(element).on('event', handler)`
 ## PrestaShop-Specific Patterns
 **Translations:**
 - Always use: `$this->l('Text to translate')` — never hardcode user-facing strings
 - Primary locale: Polish (`pl-PL`)
 - Example: `$this->displayName = $this->l('Karty cech produktu');`
 **Module `__construct()`:**
 ```php
 $this->name = 'customfeaturetab';
 $this->tab = 'front_office_features';
 $this->version = '1.0.0';
 $this->bootstrap = true;
 $this->ps_versions_compliancy = array('min' => '1.7.0.0', 'max' => _PS_VERSION_);
 parent::__construct();  // always AFTER property assignment
 ```
 **Install method pattern:**
 ```php
 public function install() {
    return parent::install()
        && $this->registerHook('displayProductExtraContent')
        && $this->_installDb();
 }
 ```
 **Database queries:**
 - Direct execution: `Db::getInstance()->execute($sql)` or `Db::getInstance()->executeS($sql)`
 - Always use `_DB_PREFIX_` for table names
 - Always use `_MYSQL_ENGINE_` for CREATE TABLE statements
 - Backtick-escape table/column names in SQL
 **ObjectModel `$definition`:**
 ```php
 public static $definition = [
    'table' => 'custom_feature_tab',
    'primary' => 'id_custom_feature_tab',
    'multilang' => true,
    'fields' => [
        'id_feature' => ['type' => self::TYPE_INT, 'validate' => 'isUnsignedId'],
        'active' => ['type' => self::TYPE_BOOL, 'validate' => 'isBool'],
        // lang fields:
        'title' => ['type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isGenericName'],
    ],
 ];
 ```
 **Smarty templates:**
 - Extend layouts: `{extends file='page.tpl'}`
 - Blocks: `{block name='page_content'}{/block}`
 - Unescaped HTML: `{$variable nofilter}`
 - Loop: `{foreach from=$items item=item}{/foreach}`
 ## Import Organization
 No enforced import order — standard PHP `require_once` or PrestaShop autoloader.
 ## Error Handling
 - Standard pattern: return `false` from `install()`/`uninstall()` on failure
 - Some legacy modules use `die()` for errors (avoid in new code)
 - No exception handling standard in custom modules
 ## Comments
 - File headers with author/copyright in legacy modules
 - Polish comments in SCSS and JS for section descriptions
 - `/** Comment */` doc-style for public methods in newer custom modules
 - PrestaShop security check at top of every file: `if (!defined('_PS_VERSION_')) exit;`
 ---
 *Convention analysis: 2026-04-27*
 *Update when patterns change*
--- a/.paul/codebase/db_schema.md
+++ b/.paul/codebase/db_schema.md
@@ -0,0 +1,88 @@
 # Database Schema
 **Analysis Date:** 2026-04-27
 ## Connection
 - Host: `dedyk75.cyber-folks.pl`
 - Database: `interblue_sklep`
 - Table prefix: `ps_`
 - Engine: InnoDB
 - Charset: UTF-8 (note: custom tables use `utf8` not `utf8mb4`)
 - Cache: Memcached
 ## Core PrestaShop Tables (selected)
 Standard PrestaShop tables present (not listed exhaustively — see PS docs):
 - `ps_orders` — Orders (modified by AddOrderExtraFields, see below)
 - `ps_order_history` — Order status history
 - `ps_order_invoice` — Invoices
 - `ps_order_payment` — Payment records (modified by AddOrderExtraFields)
 - `ps_product` — Products
 - `ps_product_lang` — Product translations
 - `ps_cart` — Shopping carts
 - `ps_customer` — Customers
 ## Custom Tables (Added by Modules)
 ### `ps_custom_feature_tab` — Feature Tab Rules
 Created by: `modules/customfeaturetab/customfeaturetab.php`
 | Column | Type | Notes |
 |--------|------|-------|
 | id_custom_feature_tab | INT UNSIGNED | PRIMARY KEY, AUTO_INCREMENT |
 | id_feature | INT UNSIGNED | Feature ID from ps_feature |
 | id_feature_value | INT UNSIGNED | Feature value ID |
 | position | INT UNSIGNED | Display order |
 | active | TINYINT(1) | Enable/disable |
 | date_add | DATETIME | |
 | date_upd | DATETIME | |
 ### `ps_custom_feature_tab_lang` — Feature Tab Content (Multilang)
 Created by: `modules/customfeaturetab/customfeaturetab.php`
 | Column | Type | Notes |
 |--------|------|-------|
 | id_custom_feature_tab | INT UNSIGNED | FK → ps_custom_feature_tab |
 | id_lang | INT UNSIGNED | FK → ps_lang |
 | title | VARCHAR(255) | Tab title |
 | content | TEXT | Tab HTML content |
 Primary key: (id_custom_feature_tab, id_lang)
 ## Modified Core Tables (by Modules)
 ### `ps_orders` — Order Source Field
 Added by: `modules/AddOrderExtraFields/AddOrderExtraFields.php`
 | Column | Type | Notes |
 |--------|------|-------|
 | order_source | ENUM('Allegro', 'Sklep int.', 'Telefonicznie') | Added via ALTER TABLE |
 Logic: Set in `modules/AddOrderExtraFields/override/classes/PaymentModule.php`
 - 'Allegro' — when `$order->module == 'x13allegro'`
 - 'Sklep int.' — default for web store orders
 - 'Telefonicznie' — manual phone orders (set manually in admin)
 ### `ps_order_payment` — Card Payment Field
 Added by: `override/classes/order/OrderPayment.php`
 - Additional field for storing card payment type (max 254 chars)
 ## Migration Approach
 - No migration framework — DDL executed in module `install()` methods
 - ALTER TABLE statements in `AddOrderExtraFields.php`
 - CREATE TABLE in `customfeaturetab.php`
 - No rollback scripts (uninstall drops custom tables)
 - No version tracking for schema changes
 ## Known Issues
 - Custom tables use `utf8` charset (should be `utf8mb4` for full Unicode/emoji support)
 - `ps_custom_feature_tab` has no index on `id_feature` or `id_feature_value` (potential slow queries on large catalogs)
 - `order_source` enum requires ALTER TABLE to add new order sources
 ---
 *DB schema: 2026-04-27*
 *Update when modules add/modify tables*
--- a/.paul/codebase/integrations.md
+++ b/.paul/codebase/integrations.md
@@ -0,0 +1,115 @@
 # External Integrations
 **Analysis Date:** 2026-04-27
 ## Marketplaces
 **Allegro:**
 - x13allegro (v7.4.0) - Primary Allegro integration, order sync, product listing
  - Module: `modules/x13allegro/x13allegro.php`
  - Sync script: `modules/x13allegro/sync.php`
  - Suppresses customer emails for Allegro orders
 - marzaallegro (v1.0.0) - Allegro pricing/markup module
  - Module: `modules/marzaallegro/`
 **Empik:**
 - empikmarketplace (v2.3.0 by Waynet) - EmpikPlace integration
  - Module: `modules/empikmarketplace/empikmarketplace.php`
  - PSR-4 autoload: `Empik\Marketplace\`
  - Overrides admin product catalog views:
    `modules/empikmarketplace/views/PrestaShop/Admin/Product/CatalogPage/Lists/list.html.twig`
 ## Shipping / Logistics
 **DPD Polska:**
 - Module: `modules/dpdpoland/` (v4.5.0)
 **InPost:**
 - Module: `modules/sensbitinpost/` (v5.9.2) - InPost ShipX API
 **Poczta Polska:**
 - Module: `modules/sensbitpocztapolska/` (v5.6.2)
 **Paczka w Ruchu:**
 - Module: `modules/sensbitpaczkawruchu/`
 **FedEx:**
 - Module: `modules/sensbitfedex/`
 **Geis Logistic:**
 - Module: `modules/GeisLogistic/`
 ## Payment Gateways
 **Przelewy24:**
 - Module: `modules/przelewy24/` (v1.3.96) - Polish online payments
 **iMoje (ING Bank):**
 - Module: `modules/imoje/` (v1.3.4) - Visa, MasterCard, BLIK
 **Native PrestaShop:**
 - Cash on delivery: `modules/ps_cashondelivery/`
 - Wire transfer: `modules/ps_wirepayment/`
 - Check payment: `modules/ps_checkpayment/`
 ## Order Management
 **BaseLinker:**
 - Module: `modules/baselinker/` (v0.0.25) - Multi-channel order management
  - Integration via webservice API
 **One-Page Checkout:**
 - Module: `modules/onepagecheckoutps/` (v1.0.1 by PresTeamShop)
  - Overrides: `override/controllers/front/OrderController.php` (653 lines)
 ## Analytics & Tracking
 **Google Tag Manager:**
 - Module: `modules/cdc_googletagmanager/`
 **Google Analytics 4:**
 - Module: `modules/pdgoogleanalytycs4pro/` (uses Guzzle HTTP client)
 **Google Merchant Center:**
 - Module: `modules/pdgooglemerchantcenterpro/`
 **eKomi Ratings:**
 - Module: `modules/ekomiratingsandreviews/`
 ## SEO & URL
 **Advanced URLs:**
 - Module: `modules/fsadvancedurl/` - Custom URL rewriting
  - Overrides: `override/classes/Dispatcher.php`, `override/classes/Link.php`
 **Sitemap:**
 - Module: `modules/gsitemap/`
 ## Performance & Caching
 **LiteSpeed Cache:**
 - Module: `modules/litespeedcache/`
  - Override: `override/classes/Media.php`
 **PS Optimizer + Lazy Images + WebP:**
 - `modules/psoptimizer/`, `modules/pshowlazyimg/`, `modules/x13webp/`
 ## Cookie Consent
 **Cookies Plus:**
 - Module: `modules/cookiesplus/`
  - Override: `override/classes/Hook.php` - intercepts hook execution for GDPR consent
 ## Environment Configuration
 **Production:**
 - DB: `app/config/parameters.php` (credentials, memcached config)
 - Admin: `admin658c34/` (obfuscated path)
 - Deployment: FTP via `.vscode/ftp-kr.json`
 **No staging environment detected.**
 ---
 *Integration audit: 2026-04-27*
 *Update when adding/removing external services*
--- a/.paul/codebase/stack.md
+++ b/.paul/codebase/stack.md
@@ -0,0 +1,86 @@
 # Technology Stack
 **Analysis Date:** 2026-04-27
 ## Languages
 **Primary:**
 - PHP 7.x+ - All server-side logic (modules, overrides, controllers)
 - Smarty - Template engine for `.tpl` theme files in `themes/InterBlue/templates/`
 **Secondary:**
 - SCSS/CSS - Stylesheets in `themes/InterBlue/assets/css/`
 - JavaScript - Frontend logic in `themes/InterBlue/assets/js/`
 ## Runtime
 **Environment:**
 - PHP 5.6+ minimum requirement (targeting PHP 7.x+ for PS 1.7.x stability)
 - MySQL/MariaDB - Database (`interblue_sklep` on `dedyk75.cyber-folks.pl`)
 - Memcached - Caching layer (`ps_caching: 'CacheMemcached'`)
 **Package Manager:**
 - No Node.js package manager for custom code
 - Composer used by individual modules (empikmarketplace, autoupgrade)
 ## Frameworks
 **Core:**
 - PrestaShop 1.7.x - E-commerce framework (MVC + Hooks)
 - Symfony components - Used internally by PS 1.7 (service container, YAML)
 **Testing:**
 - None - No test framework in custom modules
 **Build/Dev:**
 - VSCode Live Sass Compiler - Compiles `custom.scss` to `custom.css` (compressed + sourcemap)
 - Config: `.vscode/settings.json`
 ## Key Dependencies
 **Critical:**
 - PrestaShop 1.7.x - Core e-commerce platform
 - `prestashop/module-lib-service-container` (^1.4) - PSR-11 container for empikmarketplace
 - `guzzlehttp/guzzle` - HTTP client (analytics, integration modules)
 **Marketplace Modules:**
 - x13allegro 7.4.0 - Allegro integration - `modules/x13allegro/`
 - empikmarketplace 2.3.0 - Empik integration - `modules/empikmarketplace/`
 - baselinker 0.0.25 - BaseLinker webservice - `modules/baselinker/`
 **Shipping Modules:**
 - dpdpoland 4.5.0 - `modules/dpdpoland/`
 - sensbitinpost 5.9.2 - `modules/sensbitinpost/`
 - sensbitpocztapolska 5.6.2 - `modules/sensbitpocztapolska/`
 **Payment Modules:**
 - przelewy24 1.3.96 - `modules/przelewy24/`
 - imoje 1.3.4 - `modules/imoje/`
 ## Configuration
 **Environment:**
 - Database credentials: `app/config/parameters.php`
 - DB host: `dedyk75.cyber-folks.pl`, DB: `interblue_sklep`, prefix: `ps_`
 - Mailer: SMTP (localhost 127.0.0.1)
 - Locale: `pl-PL`
 **Build:**
 - `.vscode/settings.json` - Live Sass Compiler config
 - `themes/InterBlue/config/theme.yml` - Theme metadata and hook assignments
 ## Platform Requirements
 **Development:**
 - Windows + VSCode with Live Sass Compiler extension
 - SFTP/FTP Sync extension for deployment
 **Production:**
 - Hosting: dedyk75.cyber-folks.pl (cyber-folks.pl)
 - Deployment: Manual FTP via `.vscode/ftp-kr.json`
 - Cache clearing: Manual via admin panel or `var/cache/` deletion
 ---
 *Stack analysis: 2026-04-27*
 *Update after major dependency changes*
--- a/.paul/codebase/structure.md
+++ b/.paul/codebase/structure.md
@@ -0,0 +1,149 @@
 # Codebase Structure
 **Analysis Date:** 2026-04-27
 ## Directory Layout
 ```
 interblue.pl/
 ├── admin658c34/         # Admin panel (obfuscated path for security)
 ├── app/                 # Symfony app config, parameters
 │   └── config/          # parameters.php (DB credentials, cache)
 ├── classes/             # PrestaShop core model classes
 ├── config/              # Bootstrap, defines, autoloader
 ├── controllers/         # Core front/admin controllers
 ├── custom/              # Custom utility files (medoo.php, scripts)
 ├── modules/             # 133 installed modules
 ├── override/            # Class and controller overrides
 │   ├── classes/         # Core class overrides
 │   │   ├── order/       # Order, OrderInvoice, OrderPayment, OrderCarrier
 │   │   └── controller/  # FrontController override
 │   ├── controllers/
 │   │   └── front/       # ProductController, OrderController, CategoryController
 │   └── modules/         # Module template overrides
 ├── src/                 # Custom CQRS extensions (Order domain)
 │   ├── Adapter/Order/QueryHandler/
 │   └── Core/Domain/Order/
 ├── themes/
 │   └── InterBlue/       # Custom theme
 │       ├── assets/
 │       │   ├── css/     # SCSS sources + compiled CSS
 │       │   └── js/      # custom.js
 │       ├── config/      # theme.yml
 │       ├── mails/pl/    # Polish email templates
 │       └── templates/   # Smarty .tpl templates
 ├── var/cache/           # Compiled cache (do not edit)
 ├── .vscode/             # VS Code config (Live Sass, FTP)
 ├── .paul/               # PAUL project management
 └── changelog/           # Daily changelogs (YYYY-MM-DD.md)
 ```
 ## Directory Purposes
 **`modules/` — Key custom and integration modules:**
 - `modules/customfeaturetab/` — Custom product tabs from feature values
 - `modules/AddOrderExtraFields/` — Order source field (Allegro/Sklep int.)
 - `modules/x13allegro/` — Allegro marketplace (primary, v7.4.0)
 - `modules/empikmarketplace/` — Empik marketplace (v2.3.0)
 - `modules/baselinker/` — BaseLinker order management
 - `modules/onepagecheckoutps/` — One-page checkout
 - `modules/dpdpoland/`, `modules/sensbitinpost/`, etc. — Shipping carriers
 - `modules/przelewy24/`, `modules/imoje/` — Payment gateways
 **`override/` — Critical overrides:**
 - `override/classes/order/Order.php` — Hooks before invoice/delivery number (modrefchange)
 - `override/classes/Hook.php` — GDPR cookie consent intercept (cookiesplus)
 - `override/classes/Dispatcher.php` — Custom URL routing (fsadvancedurl)
 - `override/classes/Link.php` — URL generation (fsadvancedurl)
 - `override/controllers/front/OrderController.php` — One-page checkout (onepagecheckoutps)
 - `override/controllers/front/ProductController.php` — Custom URL parsing
 **`themes/InterBlue/` — Custom theme:**
 - `assets/css/custom.scss` — Main stylesheet (EDIT THIS for CSS changes)
 - `assets/css/custom.css` — Compiled output (auto-generated, do not edit)
 - `assets/css/theme.scss` — Theme base styles
 - `assets/js/custom.js` — Custom JavaScript (jQuery)
 - `templates/catalog/product.tpl` — Product detail page
 - `templates/catalog/listing/` — Category/listing pages
 - `templates/checkout/` — Checkout templates
 - `config/theme.yml` — Theme config, hook assignments
 **`src/` — CQRS Order extensions:**
 - `src/Adapter/Order/QueryHandler/GetOrderForViewingHandler.php`
 - `src/Core/Domain/Order/QueryHandler/GetOrderForViewingHandlerInterface.php`
 - `src/Core/Domain/Order/QueryResult/` — Value objects
 ## Key File Locations
 **Configuration:**
 - `app/config/parameters.php` — DB credentials, memcached, mailer config
 - `config/defines.inc.php` — Constants, dev mode flag
 - `config/config.inc.php` — Main PS bootstrap
 - `.vscode/ftp-kr.json` — FTP deployment config
 - `.vscode/settings.json` — Live Sass Compiler settings
 **Core Logic:**
 - `override/classes/order/Order.php` — Order creation hooks
 - `modules/AddOrderExtraFields/override/classes/PaymentModule.php` — Order source logic
 - `modules/customfeaturetab/customfeaturetab.php` — Feature tab module
 - `modules/customfeaturetab/classes/CustomFeatureTabRule.php` — ObjectModel
 **Theme Entry:**
 - `themes/InterBlue/assets/css/custom.scss` — CSS entry point (edit this)
 - `themes/InterBlue/assets/js/custom.js` — JS entry point
 **Admin:**
 - `admin658c34/` — Admin panel root
 ## Naming Conventions
 **Files:**
 - Module main files: `{modulename}/{modulename}.php` (e.g., `customfeaturetab/customfeaturetab.php`)
 - ObjectModel classes: PascalCase (e.g., `CustomFeatureTabRule.php`)
 - Admin controllers: `Admin{Name}Controller.php`
 - Smarty templates: `{page-name}.tpl` in appropriate subdirectory
 **Directories:**
 - Modules: lowercase, no hyphens (e.g., `customfeaturetab`, `addcolumninlist`)
 - Theme templates: follow PrestaShop structure (`catalog/`, `checkout/`, `customer/`)
 **Database Tables:**
 - Custom tables use `ps_` prefix + module name (e.g., `ps_custom_feature_tab`)
 - Module columns on core tables: `ps_orders.order_source`
 ## Where to Add New Code
 **New CSS/SCSS changes:**
 - Edit: `themes/InterBlue/assets/css/custom.scss`
 - Auto-compiled by Live Sass Compiler on save
 **New custom module:**
 - Create: `modules/{modulename}/{modulename}.php`
 - ObjectModel: `modules/{modulename}/classes/{ModelName}.php`
 - Admin controller: `modules/{modulename}/controllers/admin/Admin{Name}Controller.php`
 - Templates: `modules/{modulename}/views/templates/`
 **New PrestaShop override:**
 - Add to: `override/classes/{ClassName}.php` or `override/controllers/{type}/{Name}Controller.php`
 - Clear PS class index after: delete `var/cache/*/class_index.php`
 **New product page content:**
 - Hook: `displayProductExtraContent` (or `displayProductAdditionalInfo`)
 - Implement in a module
 ## Special Directories
 **`var/cache/`:**
 - Purpose: Compiled Smarty templates, class indexes, config cache
 - Source: Auto-generated by PrestaShop
 - Action: Clear via admin panel after PHP/template changes
 **`admin658c34/`:**
 - Purpose: Admin panel
 - Security: Randomized folder name (obfuscation)
 - Not in git (typically)
 ---
 *Structure analysis: 2026-04-27*
 *Update when directory structure changes*
--- a/.paul/codebase/testing.md
+++ b/.paul/codebase/testing.md
@@ -0,0 +1,67 @@
 # Testing Patterns
 **Analysis Date:** 2026-04-27
 ## Test Framework
 **Runner:** None — no unit/integration test framework in custom modules
 **Static Analysis:**
 - PHPStan (level 5) present only in `modules/blockreassurance/tests/php/phpstan/phpstan.neon`
 - Not configured for custom modules (`customfeaturetab`, `AddOrderExtraFields`)
 **Run Commands:**
 ```bash
 # No test commands defined
 # Only available for blockreassurance (pre-installed PS module):
 # modules/blockreassurance/tests/php/phpstan/
 ```
 ## Test File Organization
 **Custom modules — no tests found:**
 - `modules/customfeaturetab/` — no tests directory
 - `modules/AddOrderExtraFields/` — no tests directory
 - `modules/addcolumninlist/` — no tests directory
 **Pre-installed modules with static analysis only:**
 - `modules/blockreassurance/tests/php/phpstan/` — PHPStan config only
 **Core PrestaShop:**
 - `classes/ConfigurationTest.php` — system configuration checker (not unit tests)
 ## Coverage
 **Requirements:** None enforced
 **Current state:** No automated test coverage for custom code
 ## Testing Approach in This Project
 Since there is no automated test suite, verification is done manually:
 1. **Deploy to production via FTP** (`.vscode/ftp-kr.json`)
 2. **Clear PrestaShop cache** — Admin → Advanced Parameters → Performance
 3. **Manual browser testing** of affected pages
 4. **Check admin panel** for errors after module changes
 ## Recommendations for Adding Tests
 If implementing tests in the future:
 **For PHP modules:**
 - PHPUnit 9.x (compatible with PHP 7.x)
 - Composer dev dependency in module
 - Test location: `modules/{name}/tests/`
 **For static analysis:**
 - PHPStan level 5+ with PrestaShop stubs
 - Config: `modules/{name}/phpstan.neon`
 **For Smarty templates:**
 - Manual verification only (no template test framework)
 ---
 *Testing analysis: 2026-04-27*
 *Update when test patterns change*
--- a/.paul/codebase/todo.md
+++ b/.paul/codebase/todo.md
@@ -0,0 +1,4 @@
 # TODO
 > Luźny parking pomysłów, rzeczy do sprawdzenia, rzeczy które mogą nigdy nie być wdrożone.
 > Nie wymaga formalności — wrzucaj co chcesz.
--- a/.paul/config.md
+++ b/.paul/config.md
@@ -0,0 +1,33 @@
 # Project Config
 **Project:** interblue.pl
 **Created:** 2026-04-27
 ## Project Settings
 ```yaml
 project:
  name: interblue.pl
  version: 0.0.0
 ```
 ## Integrations
 ### SonarQube
 ```yaml
 sonarqube:
  enabled: false
  reason: "User declined during init"
 ```
 ## Preferences
 ```yaml
 preferences:
  auto_commit: false
  verbose_output: false
 ```
 ---
 *Config created: 2026-04-27*
--- a/.paul/governance/governance_2026-04-27.jsonl
+++ b/.paul/governance/governance_2026-04-27.jsonl
@@ -0,0 +1,17 @@
 {"ts":"2026-04-27T10:28:13Z","tool":"Bash","cmd":"mkdir -p .paul/phases .paul/codebase\",\"description\":\"Create .paul/ directory structure\"},\"tool_response\":{\"stdout\":\"\",\"stderr\":\"\",\"interrupted\":false,\"isImage\":false,\"noOutputExpec","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:28:17Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\db_schema.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:28:21Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\todo.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:30:56Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\PROJECT.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:31:06Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\ROADMAP.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:31:14Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\STATE.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:31:38Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\config.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:35:05Z","tool":"Bash","cmd":"wc -l /c/visual\\\\ studio\\\\ code/projekty/interblue.pl/override/classes/order/Order.php /c/visual\\\\ studio\\\\ code/projekty/interblue.pl/override/controllers/front/OrderController.php\"},\"tool_","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:35:07Z","tool":"Bash","cmd":"tree -L 2 -d /c/visual\\\\ studio\\\\ code/projekty/interblue.pl/override/ 2>/dev/null || find /c/visual\\\\ studio\\\\ code/projekty/interblue.pl/override -maxdepth 2 -type d | sort\"},\"tool_respons","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:37:38Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\stack.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:37:58Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\integrations.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:38:29Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\architecture.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:38:59Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\structure.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:39:16Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\db_schema.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:39:51Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\conventions.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:40:12Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\testing.md","cwd":"/c/visual studio code/projekty/interblue.pl"}
 {"ts":"2026-04-27T10:40:51Z","tool":"Write","file":"C:\\\\visual studio code\\\\projekty\\\\interblue.pl\\\\.paul\\\\codebase\\\\concerns.md","cwd":"/c/visual studio code/projekty/interblue.pl"}