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"}