Technická dokumentácia — Commerce Engine

Verzia dokumentu: 1.0 Dátum: 2026-08-01

Tento dokument dopĺňa SOFTWARE_SPECIFICATION.md (funkčná špecifikácia) o implementačné a prevádzkové detaily — architektúru kódu, dátovú schému, autentifikáciu, inštaláciu a testovanie.

1. Technologický stack

Vrstva	Technológia / verzia
Jazyk	PHP 8.4
Framework	Laravel 13
API autentifikácia	Laravel Sanctum ^4.0
2FA	pragmarx/google2fa ^9.0
PDF export	barryvdh/laravel-dompdf ^3.1
QR kódy	simplesoftwareio/simple-qrcode ^4.2
Databáza	MariaDB/MySQL (produkcia), SQLite (rýchly lokálny vývoj)
Frontend administrácie	Blade + Tailwind CSS 4, Vite
Testy	PHPUnit ^12.5
Code style	Laravel Pint ^1.27
Vývojárske nástroje	Laravel Boost, Laravel Pail, Laravel Tinker

2. Architektúra aplikácie

Commerce Engine je jeden Laravel projekt s tromi vrstvami vstupných bodov:

app/
├── Http/
│   ├── Controllers/          # Web (admin) kontroléry
│   │   └── Api/               # REST API kontroléry (v1)
│   ├── Requests/              # Form Request validácie (napr. CheckoutRequest)
│   ├── Resources/             # API Resources (transformácia modelov do JSON)
│   └── Middleware/            # napr. EnsureUserHasRole
├── Models/                    # Eloquent modely
├── Enums/                     # Stavové a typové enumy (native PHP enums)
├── Services/                  # Doménová logika (CartService, CheckoutService, DocumentNumberGenerator)
├── Observers/                 # Model observers (napr. audit log)
└── Providers/

2.1 Vrstvenie zodpovedností

Controller — prijme request, zvaliduje ho cez Form Request, deleguje logiku na Service, vráti Resource/View.
Service — obsahuje doménovú logiku nezávislú na HTTP vrstve (napr. CartService::resolveForRequest(), CheckoutService::checkout()), aby bola znovupoužiteľná a testovateľná.
Resource — jednotný formát JSON API odpovedí (OrderResource, ProductResource, ...), API odpovede sú vždy obalené v kľúči data.
Enum — typované konštanty pre stavy/nastavenia (OrderStatus, ShippingMethod, PaymentMethod, PaymentStatus, CartStatus, DiscountType, DocumentType, UserRole).

2.2 Rozdelenie API vs. Web

routes/api.php — bezstavové JSON API pod prefixom /api/v1, autentifikácia cez Sanctum Bearer token alebo hlavičku X-Guest-Token pre hosťovský košík.
routes/web.php — session-based administrácia chránená middlewarom auth a role:*; verejná landing page na /.

3. Autentifikácia a autorizácia

3.1 Administrácia (web)

Session-based prihlásenie (AuthController), guard web.
Role: admin, manager, customer (stĺpec role v tabuľke users, enum UserRole).
Middleware role:admin / role:admin,manager obmedzuje prístup k jednotlivým route skupinám (pozri routes/web.php).
Voliteľné 2FA: two_factor_secret + two_factor_enabled_at na users, overenie cez TOTP (google2fa), flow TwoFactorChallengeController po prihlásení.

3.2 REST API

Zákaznícka autentifikácia cez Laravel Sanctum — POST /api/v1/auth/login vráti Bearer token (personal_access_tokens), ktorý klient posiela v hlavičke Authorization: Bearer {token}.
Administrátorské API tokeny sa spravujú cez ApiTokenController (web admin) a taktiež využívajú Sanctum personal_access_tokens.
Guest identifikácia: hlavička X-Guest-Token identifikuje anonymný košík (carts.guest_token, unikátny index). Pri prvom pridaní položky do košíka sa token z hlavičky uloží priamo (nie generuje nový), aby zostal konzistentný medzi requestmi z klienta.
Pri prevode/zlúčení košíka (guest → zákazník po prihlásení/registrácii pri checkoute) sa guest_token v pôvodnom zázname vynuluje, aby sa predišlo kolízii s unikátnym indexom pri vytvorení nového hosťovského košíka.

4. Dátová schéma (hlavné tabuľky)

Tabuľka	Kľúčové stĺpce	Poznámka
`users`	`role`, `two_factor_secret`, `two_factor_enabled_at`, `is_active`	administrátorský/zákaznícky účet
`customers`	`user_id`, `first_name`, `last_name`, `company_name`, `ico`, `dic`, `is_company`	zákaznícky profil (B2C aj B2B)
`customer_addresses`	`customer_id`, `type`, `street`, `city`, `zip`, `country`, `is_default`	fakturačné/dodacie adresy
`products`	`category_id`, `brand_id`, `sku`, `price`, `sale_price`, `image_path`, `seo_*`	katalógová položka
`product_variants`	`product_id`, `sku`, `attributes` (JSON), `stock_quantity`	varianty produktu (napr. veľkosť/farba)
`categories`	`parent_id`, `slug`, `position`, `seo_*`	stromová štruktúra kategórií
`brands`	`slug`, `logo_path`	značky/výrobcovia
`warehouses`, `stock_items`, `stock_movements`	`quantity`, `reserved_quantity`, `type`	skladové hospodárstvo (WMS)
`carts`, `cart_items`	`customer_id` / `guest_token`, `status`, `unit_price`	košík (guest aj zákaznícky)
`orders`	`order_number`, `first_name`, `last_name`, `email`, `phone`, `billing_*`, `shipping_method`, `payment_method`, `status`, `payment_status`, `total_amount`	objednávka vrátane kontaktných/fakturačných údajov a dopravy/platby
`order_items`	`product_name`, `quantity`, `unit_price`, `total_price`	položky objednávky (snapshot ceny/názvu)
`order_status_histories`	`status`, `note`, `user_id`	história zmien stavu objednávky
`discounts`, `coupons`	`type`, `value`, `starts_at`, `ends_at`	zľavy a kupóny
`tax_rates`, `currencies`, `languages`	`rate`, `exchange_rate`, `code`	číselníky
`documents`	`order_id`, `type`, `document_number`, `file_path`	vygenerované dokumenty (faktúry a pod.)
`settings`	`company_*`, `iban`, `bic`, `default_currency_code`	globálne firemné nastavenia
`email_templates`	`subject`, `body`	šablóny pre transakčné e-maily
`audit_logs`	`user_id`, `action`, `auditable_type/id`, `changes` (JSON)	audit trail zmien entít
`personal_access_tokens`	Sanctum	API tokeny

4.1 Enumy (stavy)

OrderStatus — stavový cyklus objednávky (napr. nová, spracováva sa, odoslaná, doručená, stornovaná).
PaymentStatus — stav platby.
PaymentMethod — cod (dobierka, +2 € príplatok), bank_transfer (bankový prevod).
ShippingMethod — gls, dpd.
CartStatus — stav košíka (aktívny/konvertovaný/opustený).
DiscountType, DocumentType, UserRole — typové/kategorizačné enumy.

5. Kľúčové doménové služby

5.1 `CartService`

resolveForRequest() — nájde alebo vytvorí košík pre aktuálny request (podľa prihláseného zákazníka alebo X-Guest-Token); pri vytváraní nového guest košíka rešpektuje token poslaný klientom namiesto generovania nového.
Správa položiek košíka (pridanie, úprava množstva, odstránenie) s prepočtom cien.

5.2 `CheckoutService`

checkout() — validuje dostupnosť produktov, vytvorí Order + OrderItem záznamy z obsahu košíka, pripočíta príplatok za dobierku (+2 €), uloží kontaktné/fakturačné údaje a zvolenú dopravu/platbu.
Pri guest checkout s voľbou registrácie vytvorí User + Customer a vráti Sanctum token pre automatické prihlásenie klienta.
Po dokončení checkoutu resetuje guest_token pôvodného košíka.

5.3 `DocumentNumberGenerator`

Generuje sekvenčné čísla dokumentov (faktúry, dodacie listy) podľa typu a obdobia.

6. Konfigurácia prostredia (`.env`)

Kľúčové premenné (viď .env.example):

APP_NAME, APP_ENV, APP_URL, APP_LOCALE

DB_CONNECTION=mariadb   # alebo sqlite pre rýchly lokálny vývoj
DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

SESSION_DRIVER=database
QUEUE_CONNECTION=database
CACHE_STORE=database

MAIL_MAILER, MAIL_HOST, MAIL_PORT, ...   # transakčné e-maily

7. Inštalácia a lokálne spustenie

composer install
npm install

cp .env.example .env
php artisan key:generate

php artisan migrate --seed

Spustenie backendu:

php artisan serve            # http://127.0.0.1:8000

Spustenie frontendu (admin UI) v dev móde s live-reload:

npm run dev

Alternatívne, súbežné spustenie servera aj asset watchera (podľa composer.json scripts):

composer run dev

Produkčný build frontend assetov:

npm run build

8. Testovanie a kvalita kódu

Testy: php artisan test --compact (celá suita), --filter=NázovTestu pre výber konkrétneho testu.
Umiestnenie testov: tests/Feature/Api/* (API testy — Cart, Checkout, Auth...), tests/Feature/* (webová administrácia).
Ku dňu vydania v1.0: 125/125 testov prechádza.
Formátovanie kódu: vendor/bin/pint --dirty --format agent (kontrola/oprava len zmenených súborov) alebo vendor/bin/pint --format agent pre celý projekt.

9. Integrácia s klientskými aplikáciami

Klient komunikuje výhradne cez /api/v1/* endpointy.
Odpovede API sú vždy obalené v kľúči data — klient musí pri spracovaní odpovede pristupovať k response['data'], nie k celej surovej odpovedi.
Pre anonymných používateľov klient generuje/ukladá guest_token (napr. v session) a posiela ho v hlavičke X-Guest-Token pri každom požiadavku súvisiacom s košíkom/checkoutom.
Po prihlásení/registrácii počas checkoutu klient uloží vrátený Sanctum token a používa ho na autentifikované volania (/orders, /orders/{id}, /auth/logout).

10. Nasadenie a prevádzka (odporúčania)

Produkčná databáza: MariaDB/MySQL (podľa .env.example); SQLite je vhodné len pre lokálny vývoj/testy.
Queue a cache: driver database je vhodný pre menšiu prevádzku; pri raste odporúčame Redis (REDIS_* premenné sú už pripravené v .env.example).
Odchádzajúce e-maily: nakonfigurovať reálny MAIL_MAILER (predvolene log pre vývoj).
Zálohovanie: pravidelný zálohovací plán pre databázu a storage/app (vygenerované dokumenty/PDF).

11. Referencie

SOFTWARE_SPECIFICATION.md — funkčná špecifikácia systému.
README.md — stručný prehľad a inštalačné kroky.
CHANGELOG.md — história zmien.
app/Enums/, app/Models/, app/Services/ — zdrojový kód domény.