update
This commit is contained in:
Jacek
@@ -1,3 +1,192 @@
|
||||
# ARCHITECTURE
|
||||
|
||||
> Struktura klas, modulow, przeplywow i zaleznosci w projekcie.
|
||||
## Scope
|
||||
|
||||
Dokument opisuje aktualna architekture runtime projektu `shopPRO`:
|
||||
- warstwy aplikacji i ich odpowiedzialnosci,
|
||||
- przeplywy requestow (admin/front/api),
|
||||
- Dependency Injection i miejsca wiringu,
|
||||
- konwencje autoloadera i namespace,
|
||||
- granice miedzy nowa architektura a pozostalosciami legacy.
|
||||
|
||||
## High-level layout
|
||||
|
||||
Kod aplikacji jest podzielony na 4 glowne warstwy:
|
||||
|
||||
1. `autoload/Domain/` - logika biznesowa i dostep do danych (28 modulow)
|
||||
2. `autoload/admin/` - panel administracyjny (router + kontrolery + form system)
|
||||
3. `autoload/front/` - frontend sklepu (router + layout engine + kontrolery/widoki)
|
||||
4. `autoload/api/` - REST API (`api.php`, `ApiRouter`, kontrolery endpointow)
|
||||
|
||||
Komponenty wspoldzielone sa trzymane w `autoload/Shared/`.
|
||||
|
||||
## Directory map (runtime)
|
||||
|
||||
```text
|
||||
autoload/
|
||||
Domain/ # 28 modulow domenowych
|
||||
Shared/ # Cache, Helpers, Tpl, Html, Email, Image
|
||||
admin/
|
||||
App.php # routing + DI factories
|
||||
Controllers/ # 28 kontrolerow admin
|
||||
Support/ # formularze/tabele
|
||||
Validation/ # walidacja formularzy
|
||||
ViewModels/ # modele widokow
|
||||
front/
|
||||
App.php # routing + DI factories + fallback legacy
|
||||
LayoutEngine.php # silnik layoutu frontend
|
||||
Controllers/ # 8 kontrolerow frontend
|
||||
Views/ # 11 statycznych klas widokow
|
||||
api/
|
||||
ApiRouter.php # auth + endpoint dispatch
|
||||
Controllers/ # 4 kontrolery API
|
||||
```
|
||||
|
||||
## Entry points i przeplyw
|
||||
|
||||
### Admin (`admin/index.php`)
|
||||
|
||||
1. Bootstrap (sesja, DB, autoload)
|
||||
2. `admin\App::update()` - uruchamia pending migracje
|
||||
3. `admin\App::special_actions()` - logowanie/wylogowanie/2FA
|
||||
4. `admin\App::render()`:
|
||||
- auth gate (lub formularz logowania),
|
||||
- `route()` -> kontroler + akcja,
|
||||
- render przez `Shared\Tpl\Tpl`.
|
||||
|
||||
### Front (`index.php`)
|
||||
|
||||
1. Bootstrap (sesja, DB, autoload, jezyk)
|
||||
2. Mapowanie URL (redirecty + routes)
|
||||
3. `front\App::checkUrlParams()`
|
||||
4. `front\App::route()`:
|
||||
- artykul/produkt/kategoria,
|
||||
- nowe kontrolery DI,
|
||||
- fallback do `front\controls\*` (legacy, jesli istnieje)
|
||||
5. `front\LayoutEngine::show()` sklada finalny HTML.
|
||||
|
||||
### API (`api.php`)
|
||||
|
||||
1. Bootstrap (bez sesji biznesowej)
|
||||
2. Tworzenie `\api\ApiRouter`
|
||||
3. `ApiRouter::handle()`:
|
||||
- auth przez `X-Api-Key`,
|
||||
- walidacja `endpoint` i `action`,
|
||||
- dispatch do kontrolera API,
|
||||
- JSON response przez `sendSuccess()` / `sendError()`.
|
||||
|
||||
Szczegolowa specyfikacja endpointow: `.paul/docs/API.md`.
|
||||
|
||||
## Dependency Injection (manual factories)
|
||||
|
||||
DI jest realizowane recznie w mapach factory:
|
||||
|
||||
- admin: `autoload/admin/App.php` -> `getControllerFactories()`
|
||||
- front: `autoload/front/App.php` -> `getControllerFactories()`
|
||||
- api: `autoload/api/ApiRouter.php` -> `getControllerFactories()`
|
||||
|
||||
Wzorzec:
|
||||
- router tworzy repozytoria domenowe,
|
||||
- repozytoria sa wstrzykiwane do kontrolerow przez konstruktor,
|
||||
- kontroler wywoluje metody domenowe i zwraca HTML/JSON.
|
||||
|
||||
## Autoloader i namespace rules
|
||||
|
||||
Kazdy entry point korzysta z custom autoloadera:
|
||||
|
||||
1. `autoload/{namespace}/class.{ClassName}.php` (legacy)
|
||||
2. `autoload/{namespace}/{ClassName}.php` (nowy format)
|
||||
|
||||
Mapowanie namespace -> katalog (case-sensitive na Linux):
|
||||
|
||||
- `\Domain\` -> `autoload/Domain/`
|
||||
- `\Shared\` -> `autoload/Shared/`
|
||||
- `\admin\` -> `autoload/admin/` (male `a`)
|
||||
- `\front\` -> `autoload/front/`
|
||||
- `\api\` -> `autoload/api/`
|
||||
|
||||
Nie uzywac `\Admin\` (duze `A`), bo katalog runtime to `admin/`.
|
||||
|
||||
## Domain layer (28 modulow)
|
||||
|
||||
Aktualne moduly:
|
||||
|
||||
`Article`, `Attribute`, `Banner`, `Basket`, `Cache`, `Category`, `Client`, `Coupon`, `CronJob`, `Dashboard`, `Dictionaries`, `Integrations`, `Languages`, `Layouts`, `Newsletter`, `Order`, `Pages`, `PaymentMethod`, `Producer`, `Product`, `ProductSet`, `Promotion`, `Scontainers`, `Settings`, `ShopStatus`, `Transport`, `Update`, `User`.
|
||||
|
||||
Zasada: logika biznesowa i dostep do danych sa w Domain, bez duplikowania osobnych warstw "admin service" i "front service" dla tych samych przypadkow (wyjatki tylko tam, gdzie historycznie juz istnieja, np. `OrderAdminService`).
|
||||
|
||||
## Admin architecture
|
||||
|
||||
- Router: `admin\App`
|
||||
- Kontrolery: `autoload/admin/Controllers/*.php` (28 klas)
|
||||
- Form system:
|
||||
- `admin\ViewModels\Forms\*`
|
||||
- `admin\Support\Forms\FormRequestHandler`
|
||||
- `admin\Support\Forms\FormFieldRenderer`
|
||||
- `admin\Validation\FormValidator`
|
||||
- template: `admin/templates/components/form-edit.php`
|
||||
|
||||
Admin ma pelne DI i nie korzysta z fallbacku na legacy kontrolery.
|
||||
|
||||
## Front architecture
|
||||
|
||||
- Router: `front\App`
|
||||
- Layout engine: `front\LayoutEngine`
|
||||
- Kontrolery DI: `autoload/front/Controllers/*.php` (8 klas)
|
||||
- Widoki statyczne: `autoload/front/Views/*.php` (11 klas)
|
||||
|
||||
Wazne: frontend nadal ma fallback do `\front\controls\*`, wiec architektura jest hybrydowa (new DI + remaining legacy paths).
|
||||
|
||||
## API architecture
|
||||
|
||||
- Router: `api\ApiRouter`
|
||||
- Endpointy: `orders`, `products`, `dictionaries`, `categories`
|
||||
- Kontrolery: `autoload/api/Controllers/*ApiController.php` (4 klasy)
|
||||
- API jest stateless, autoryzowane naglowkiem `X-Api-Key`
|
||||
|
||||
Source-of-truth API to runtime:
|
||||
- `api.php`
|
||||
- `autoload/api/ApiRouter.php`
|
||||
- `autoload/api/Controllers/*`
|
||||
|
||||
## Shared components
|
||||
|
||||
Najwazniejsze klasy wspoldzielone:
|
||||
|
||||
- `Shared\Cache\CacheHandler`, `Shared\Cache\RedisConnection`
|
||||
- `Shared\Helpers\Helpers`
|
||||
- `Shared\Tpl\Tpl`
|
||||
- `Shared\Html\Html`
|
||||
- `Shared\Email\Email`
|
||||
- `Shared\Image\ImageManipulator`
|
||||
|
||||
## Data and cache conventions
|
||||
|
||||
- ORM: Medoo (`$mdb`)
|
||||
- Prefix tabel: `pp_`
|
||||
- Cache: Redis, domyslnie TTL `86400`
|
||||
- Dane cache czesto serializowane (`serialize`/`unserialize`)
|
||||
- Czyszczenie cache produktu: pattern `shop\\product:{id}:*`
|
||||
|
||||
## Security boundaries
|
||||
|
||||
- Admin:
|
||||
- sesja uzytkownika admina,
|
||||
- CSRF token w akcjach POST,
|
||||
- 2FA email flow (pending session + verify).
|
||||
- API:
|
||||
- `X-Api-Key` porownywany przez `hash_equals()`,
|
||||
- brak logiki sesyjnej.
|
||||
- Front:
|
||||
- sesja klienta + walidacja przeplywow frontendowych.
|
||||
|
||||
## Source files
|
||||
|
||||
Najwazniejsze pliki do szybkiej orientacji:
|
||||
|
||||
- `autoload/admin/App.php`
|
||||
- `autoload/front/App.php`
|
||||
- `autoload/front/LayoutEngine.php`
|
||||
- `autoload/api/ApiRouter.php`
|
||||
- `.paul/docs/API.md`
|
||||
- `docs/PROJECT_STRUCTURE.md`
|
||||
|
||||
Reference in New Issue
Block a user