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/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*