diff --git a/.paul/PROJECT.md b/.paul/PROJECT.md new file mode 100644 index 00000000..78a600ee --- /dev/null +++ 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* diff --git a/.paul/ROADMAP.md b/.paul/ROADMAP.md new file mode 100644 index 00000000..056daea9 --- /dev/null +++ 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* diff --git a/.paul/STATE.md b/.paul/STATE.md new file mode 100644 index 00000000..3c3ffd81 --- /dev/null +++ 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* diff --git a/.paul/codebase/architecture.md b/.paul/codebase/architecture.md new file mode 100644 index 00000000..05aba85a --- /dev/null +++ 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* diff --git a/.paul/codebase/concerns.md b/.paul/codebase/concerns.md new file mode 100644 index 00000000..00bf2564 --- /dev/null +++ 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* diff --git a/.paul/codebase/conventions.md b/.paul/codebase/conventions.md new file mode 100644 index 00000000..9b45a572 --- /dev/null +++ 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* diff --git a/.paul/codebase/db_schema.md b/.paul/codebase/db_schema.md new file mode 100644 index 00000000..baa855e4 --- /dev/null +++ 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* diff --git a/.paul/codebase/integrations.md b/.paul/codebase/integrations.md new file mode 100644 index 00000000..e7f44497 --- /dev/null +++ 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* diff --git a/.paul/codebase/stack.md b/.paul/codebase/stack.md new file mode 100644 index 00000000..32f6fd00 --- /dev/null +++ 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* diff --git a/.paul/codebase/structure.md b/.paul/codebase/structure.md new file mode 100644 index 00000000..6873ddce --- /dev/null +++ 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* diff --git a/.paul/codebase/testing.md b/.paul/codebase/testing.md new file mode 100644 index 00000000..8ba21eae --- /dev/null +++ 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* diff --git a/.paul/codebase/todo.md b/.paul/codebase/todo.md new file mode 100644 index 00000000..078d295e --- /dev/null +++ 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. diff --git a/.paul/config.md b/.paul/config.md new file mode 100644 index 00000000..f62a538d --- /dev/null +++ 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* diff --git a/.paul/governance/governance_2026-04-27.jsonl b/.paul/governance/governance_2026-04-27.jsonl new file mode 100644 index 00000000..7b87e7fc --- /dev/null +++ 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"}