Refactor code structure for improved readability and maintainability

2026-02-18 08:28:02 +01:00
parent a374c1d866
commit 37528c6af9
11 changed files with 2266 additions and 2524 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-shopPRO is a PHP e-commerce platform with an admin panel and customer-facing storefront. It uses Medoo ORM (`$mdb`), Redis caching, and is undergoing a migration from legacy architecture to Domain-Driven Design with Dependency Injection.
+shopPRO is a PHP e-commerce platform with an admin panel and customer-facing storefront. It uses Medoo ORM (`$mdb`), Redis caching, and a Domain-Driven Design architecture with Dependency Injection (migration from legacy architecture complete).

 ## PHP Version Constraint

@@ -50,21 +50,27 @@ shopPRO/
 │   ├── Domain/                 # Business logic repositories (\Domain\)
 │   ├── Shared/                 # Shared utilities (\Shared\)
 │   │   ├── Cache/              # CacheHandler, RedisConnection
+│   │   ├── Email/              # Email (PHPMailer wrapper)
 │   │   ├── Helpers/            # Helpers (formerly class.S.php)
+│   │   ├── Html/               # Html utility
+│   │   ├── Image/              # ImageManipulator
 │   │   └── Tpl/                # Template engine
 │   ├── admin/                  # Admin panel layer
-│   │   └── Controllers/        # DI controllers (\admin\Controllers\)
-│   ├── front/                  # Frontend layer
-│   │   ├── App.php             # Frontend router (\front\App)
-│   │   ├── LayoutEngine.php    # Layout engine (\front\LayoutEngine)
-│   │   ├── Controllers/        # DI controllers (\front\Controllers\)
-│   │   └── Views/              # Static views (\front\Views\)
-│   └── shop/                   # EMPTY — all legacy classes migrated to Domain\
+│   │   ├── App.php             # Admin router (\admin\App)
+│   │   ├── Controllers/        # DI controllers (\admin\Controllers\) — 28 controllers
+│   │   ├── Support/            # TableListRequestFactory, Forms/FormRequestHandler, Forms/FormFieldRenderer
+│   │   ├── Validation/         # FormValidator
+│   │   └── ViewModels/         # Forms/ (FormEditViewModel, FormField, FormTab, FormAction, FormFieldType), Common/ (PaginatedTableViewModel)
+│   └── front/                  # Frontend layer
+│       ├── App.php             # Frontend router (\front\App)
+│       ├── LayoutEngine.php    # Layout engine (\front\LayoutEngine)
+│       ├── Controllers/        # DI controllers (\front\Controllers\) — 8 controllers
+│       └── Views/              # Static views (\front\Views\) — 11 view classes
 ├── admin/                      # Admin panel
 │   ├── templates/              # Admin view templates
 │   └── layout/                 # Admin CSS/JS/icons
 ├── templates/                  # Frontend view templates
-├── libraries/                  # Third-party libraries
+├── libraries/                  # Third-party libraries (Medoo, RedBeanPHP, PHPMailer)
 ├── tests/                      # PHPUnit tests
 │   ├── bootstrap.php
 │   ├── stubs/                  # Test stubs (CacheHandler, Helpers, ShopProduct)
@@ -89,25 +95,27 @@ Custom autoloader in each entry point (not Composer autoload at runtime). Tries
 2. `autoload/{namespace}/{ClassName}.php` (PSR-4 style, fallback)

 ### Namespace Conventions (case-sensitive on Linux!)
- `\Domain\` → `autoload/Domain/` (uppercase D — new directory)
- `\admin\Controllers\` → `autoload/admin/Controllers/` (lowercase a — existing directory)
+- `\Domain\` → `autoload/Domain/` (uppercase D)
+- `\admin\Controllers\` → `autoload/admin/Controllers/` (lowercase a)
 - `\Shared\` → `autoload/Shared/`
 - `\front\` → `autoload/front/`
- ~~`\shop\`~~ → `autoload/shop/` (EMPTY — all classes migrated to `\Domain\`)
 - Do NOT use `\Admin\` (uppercase A) — the server directory is `admin/` (lowercase)
+- `\shop\` namespace is **deleted** — all 12 legacy classes migrated to `\Domain\`, `autoload/shop/` directory removed

-### Domain-Driven Architecture (migration complete for admin + frontend)
+### Domain-Driven Architecture (migration complete)

-All modules use this pattern:
+All legacy directories (`admin/controls/`, `admin/factory/`, `admin/view/`, `front/controls/`, `front/view/`, `front/factory/`, `shop/`) have been deleted. All modules now use this pattern:

 **Domain Layer** (`autoload/Domain/{Module}/`):
 - `{Module}Repository.php` — data access, business logic, Redis caching
 - Constructor DI with `$db` (Medoo instance)
 - Methods serve both admin and frontend (shared Domain, no separate services)

+**Domain Modules**: Article, Attribute, Banner, Basket, Cache, Category, Client, Coupon, Dashboard, Dictionaries, Integrations, Languages, Layouts, Newsletter, Order, Pages, PaymentMethod, Producer, Product, ProductSet, Promotion, Scontainers, Settings, ShopStatus, Transport, Update, User
+
 **Admin Controllers** (`autoload/admin/Controllers/`):
 - DI via constructor (repositories injected)
- Wired in `admin\App::route()` via `$newControllers` map
+- Wired in `admin\App::getControllerFactories()`

 **Frontend Controllers** (`autoload/front/Controllers/`):
 - DI via constructor
@@ -133,12 +141,20 @@ All modules use this pattern:
 - Full schema: `docs/DATABASE_STRUCTURE.md`

 ### Form Edit System
-Universal form system for admin edit views. Uses ViewModels (`FormEditViewModel`, `FormField`, `FormTab`, `FormAction`), validation (`FormValidator`), and rendering (`FormFieldRenderer`). Template: `admin/templates/components/form-edit.php`. Docs: `docs/FORM_EDIT_SYSTEM.md`.
+Universal form system for admin edit views. Docs: `docs/FORM_EDIT_SYSTEM.md`.
+- **ViewModels** (`admin\ViewModels\Forms\`): `FormEditViewModel`, `FormField`, `FormTab`, `FormAction`, `FormFieldType`
+- **Validation**: `admin\Validation\FormValidator`
+- **Rendering**: `admin\Support\Forms\FormFieldRenderer`, `admin\Support\Forms\FormRequestHandler`
+- **Template**: `admin/templates/components/form-edit.php`
+- **Table lists**: `admin\Support\TableListRequestFactory` + `admin\ViewModels\Common\PaginatedTableViewModel`

 ### Caching
 - Redis via `\Shared\Cache\CacheHandler` (singleton `RedisConnection`)
 - Key pattern for products: `shop\product:{id}:{lang}:{permutation_hash}`
 - Clear product cache: `\Shared\Helpers\Helpers::clear_product_cache($id)`
+- Pattern delete: `CacheHandler::deletePattern("shop\\product:{$id}:*")`
+- Default TTL: 86400 (24h)
+- Data is serialized — requires `unserialize()` after `get()`
 - Config: `config.php` (`$config['redis']`)

 ## Code Patterns
@@ -161,6 +177,11 @@ $repo = new \Domain\Example\ExampleRepository($mdb);
 $controller = new \admin\Controllers\ExampleController($repo);
 ```

+### Medoo ORM pitfalls
+- `$mdb->delete($table, $where)` takes **2 arguments**, NOT 3 — has caused bugs
+- `$mdb->get()` returns `null` when no record, NOT `false`
+- After `$mdb->insert()`, check `$mdb->id()` to confirm success
+
 ### File naming
 - New classes: `ClassName.php` (no `class.` prefix)
 - Legacy classes: `class.ClassName.php` (leave until migrated)
@@ -175,7 +196,7 @@ $controller = new \admin\Controllers\ExampleController($repo);

 When user says **"KONIEC PRACY"**, execute in order:
 1. Run tests
-2. Update documentation if needed: `docs/DATABASE_STRUCTURE.md`, `docs/PROJECT_STRUCTURE.md`, `docs/FRONTEND_REFACTORING_PLAN.md`, `docs/FORM_EDIT_SYSTEM.md`, `docs/CHANGELOG.md`, `docs/TESTING.md`
+2. Update documentation if needed: `docs/DATABASE_STRUCTURE.md`, `docs/PROJECT_STRUCTURE.md`, `docs/FORM_EDIT_SYSTEM.md`, `docs/CHANGELOG.md`, `docs/TESTING.md`
 3. Prepare update package per `docs/UPDATE_INSTRUCTIONS.md`
 4. Commit
 5. Push
@@ -184,12 +205,9 @@ Before starting implementation, review current state of docs (see AGENTS.md for

 ## Key Documentation
 - `docs/MEMORY.md` — project memory: known issues, confirmed patterns, ORM pitfalls, caching conventions
- `docs/PROJECT_STRUCTURE.md` — detailed project structure and module status
- `docs/REFACTORING_PLAN.md` — Domain migration plan and status
- `docs/FRONTEND_REFACTORING_PLAN.md` — frontend migration plan (mostly complete)
- `docs/LEGACY_SHOP_REFACTORING_PLAN.md` — plan usunięcia 12 legacy klas z `autoload/shop/` (UKOŃCZONY — wszystkie 12 klas usunięte)
+- `docs/PROJECT_STRUCTURE.md` — current architecture, layers, cache, entry points, integrations
 - `docs/DATABASE_STRUCTURE.md` — full database schema
- `docs/TESTING.md` — test suite status and history
+- `docs/TESTING.md` — test suite guide and structure
 - `docs/FORM_EDIT_SYSTEM.md` — form system architecture
 - `docs/CHANGELOG.md` — version history
 - `docs/UPDATE_INSTRUCTIONS.md` — how to build client update packages