127 lines
6.1 KiB
Markdown
127 lines
6.1 KiB
Markdown
# Architecture
|
|
|
|
## Request Flow
|
|
|
|
```
|
|
HTTP Request
|
|
→ public/index.php
|
|
→ bootstrap/app.php (loads config, registers PDO, services)
|
|
→ Application::boot() (loads routes/web.php)
|
|
→ Router::dispatch(Request) (matches URL, runs middleware pipeline)
|
|
→ [Middleware] (AuthMiddleware, ApiKeyMiddleware)
|
|
→ Controller::method() (parse input → call repository/service → render)
|
|
→ Template::render() (PHP native, layout composition)
|
|
→ Response::send()
|
|
```
|
|
|
|
## Layer Map
|
|
|
|
| Layer | Location | Responsibility |
|
|
|-------|----------|----------------|
|
|
| Entry | `public/index.php` | Bootstrap only |
|
|
| Routes | `routes/web.php` (581 lines) | All ~80 routes; manual DI wiring |
|
|
| Core | `src/Core/` (25 files) | Framework infrastructure |
|
|
| Controllers | `src/Modules/*/Controller.php` | Request parsing → response |
|
|
| Services | `src/Modules/*/Service.php` | Business logic |
|
|
| Repositories | `src/Modules/*/Repository.php` | PDO data access (34+ repos) |
|
|
| Views | `resources/views/` | PHP templates with `$e()` / `$t()` |
|
|
| Components | `resources/views/components/` | Reusable UI blocks |
|
|
|
|
## Module Inventory (`src/Modules/`)
|
|
|
|
| Module | Files | Key Classes | Purpose |
|
|
|--------|-------|-------------|---------|
|
|
| **Auth** | 3 | `AuthController`, `AuthMiddleware`, `AuthService` | Login/logout, session |
|
|
| **Users** | 2 | `UserController`, `UserRepository` | User CRUD |
|
|
| **Orders** | 3 | `OrdersController` (1187 LOC), `OrdersRepository` (1221 LOC) | Order list, detail, status, payment, correlated subquery for return-risk |
|
|
| **Shipments** | 17 | `ShipmentController`, provider services + tracking services | Shipment creation, label download, tracking polling |
|
|
| **Accounting** | 5 | `AccountingController`, `ReceiptService`, `ReceiptRepository` | Receipts, invoices, PDF, Excel export |
|
|
| **Email** | 3 | `EmailSendingService`, `VariableResolver`, `AttachmentGenerator` | Template-based email with PDF attachments |
|
|
| **Automation** | 6 | `AutomationService` (834 LOC), `AutomationRepository`, `AutomationExecutionLogRepository` | Event→condition→action rules, email triggers |
|
|
| **Settings** | 51+ | Integration controllers, OAuth clients, API clients, mappers | Allegro/shopPRO/Apaczka/InPost config, status mappings |
|
|
| **Cron** | 12 | `CronRepository`, `CronHandlerFactory`, handler classes | Scheduled imports, syncs, token refresh |
|
|
| **Printing** | 4 | `PrintApiController`, `PrintJobRepository`, `ApiKeyMiddleware` | REST API for Windows print client |
|
|
| **Statistics** | 2 | `OrdersStatisticsController`, `OrdersStatisticsRepository` | Dashboard aggregates |
|
|
| **Info** | 1 | `InfoController` | Health check |
|
|
|
|
## Key Data Flows
|
|
|
|
### Order Lifecycle
|
|
1. **Import** — Cron handler → API client → `OrderImportService` → `OrdersRepository::insertOrder()` → `AutomationService::executeForNewOrder()`
|
|
2. **Status update** — `OrdersController::updateStatus()` → `OrdersRepository::updateStatus()` → automation check
|
|
3. **Status sync** — Cron → `AllegroStatusSyncService` / `ShopproStatusSyncService` → carrier API
|
|
|
|
### Shipment Flow
|
|
1. **Create** — `ShipmentController::create()` → `ShipmentProviderRegistry` → carrier `ShipmentService::createShipment()` → `ShipmentPackageRepository::insert()`
|
|
2. **Track** — Cron `ShipmentTrackingHandler` → `ShipmentTrackingRegistry` → carrier tracking API → `ShipmentPackageRepository::updateDeliveryStatus()`
|
|
|
|
### Receipt / Invoice
|
|
1. **Generate** — `ReceiptController::store()` → `ReceiptService::generateReceipt()` → `ReceiptRepository::insert()` + Dompdf PDF
|
|
2. **Email** — `EmailSendingService::send()` → `VariableResolver::resolve()` → `AttachmentGenerator::generatePdf()` → PHPMailer SMTP
|
|
|
|
### Automation Rules
|
|
1. **Setup** — `AutomationController` → `AutomationRepository::insertRule()`
|
|
2. **Trigger** — `AutomationService::executeForOrder()` → evaluates trigger (`order_status_changed`, `order_status_aged`) → runs action (send email, update status)
|
|
3. **Log** — `AutomationExecutionLogRepository` tracks every run
|
|
|
|
### Cron Jobs
|
|
|
|
| Handler | Task |
|
|
|---------|------|
|
|
| `AllegroOrdersImportHandler` | Fetch new Allegro orders |
|
|
| `AllegroStatusSyncHandler` | Push status changes to Allegro |
|
|
| `AllegroTokenRefreshHandler` | OAuth token refresh (24h expiry) |
|
|
| `ShopproOrdersImportHandler` | Fetch new shopPRO orders |
|
|
| `ShopproStatusSyncHandler` | Push status to shopPRO |
|
|
| `ShopproPaymentStatusSyncHandler` | Sync payment statuses |
|
|
| `ShipmentTrackingHandler` | Poll carrier tracking APIs |
|
|
| `OrderStatusAgedHandler` | Trigger automation for stuck statuses |
|
|
| `AutomationHistoryCleanupHandler` | Purge old automation logs |
|
|
|
|
## Dependency Injection
|
|
|
|
Manual constructor injection in `routes/web.php` — no DI container library. Example:
|
|
|
|
```php
|
|
$ordersController = new OrdersController(
|
|
$template, $translator, $auth,
|
|
$app->orders(), $shipmentPackageRepository,
|
|
$receiptRepository, $receiptConfigRepository, ...
|
|
);
|
|
```
|
|
|
|
All production classes are `final` — prevents accidental inheritance.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
bootstrap/ app.php (service wiring, config loading)
|
|
bin/ migrate.php, cron.php (CLI entry points)
|
|
config/ app.php, database.php
|
|
database/
|
|
migrations/ 84 SQL files (YYYYMMDD_NNNNNN_description.sql)
|
|
drafts/ WIP migrations
|
|
public/
|
|
index.php HTTP entry point
|
|
.htaccess Apache rewrite rules
|
|
assets/css/ Compiled CSS (app.css, login.css, modules/)
|
|
assets/js/ jquery-alerts.js, global-search.js, automation-form.js
|
|
resources/
|
|
views/ PHP templates by module + components/ layouts/
|
|
scss/ SCSS sources (app.scss, login.scss, modules/_*.scss)
|
|
modules/ jquery-alerts JS+SCSS source
|
|
lang/pl/ Polish translations
|
|
routes/
|
|
web.php All routes (581 lines)
|
|
src/
|
|
Core/ Framework (25 files)
|
|
Modules/ 13 feature modules (~200+ PHP files)
|
|
storage/
|
|
logs/ app.log
|
|
sessions/ PHP session files
|
|
cache/ PHPUnit cache, etc.
|
|
tests/
|
|
Unit/ PHPUnit tests (7+ service test files)
|
|
bootstrap.php PSR-4 autoloader for tests
|
|
```
|