Software Specification — Commerce Engine

Verzia dokumentu: 1.0 Dátum: 2026-08-01 Súvisiaci release: v1.0

1. Úvod

1.1 Účel dokumentu

Tento dokument popisuje funkčnú a technickú špecifikáciu systému Commerce Engine (CE) — headless e-shop platformy postavenej na frameworku Laravel. Slúži ako referenčný podklad pre vývoj, údržbu a integráciu s klientskými aplikáciami.

1.2 Rozsah systému

Commerce Engine poskytuje:

• REST API pre katalóg produktov, košík, checkout a zákaznícke objednávky, ktoré je možné napojiť na ľubovoľný frontend (e-shop, mobilná aplikácia, B2B portál).
• Webovú administráciu (back office) na správu celého obchodného procesu — produkty, sklady, objednávky, zákazníci, cenotvorba, dokumenty a systémové nastavenia.
• Verejnú prezentačnú (marketingovú) stránku produktu.

1.3 Definície a skratky

2. Prehľad systému

2.1 Architektúra

Commerce Engine je monolitická Laravel aplikácia, ktorá súčasne poskytuje:

1. REST API (routes/api.php, prefix /api/v1) — bezstavové, autentifikované cez Laravel Sanctum (Bearer token), určené pre externé klientské aplikácie.
2. Webovú administráciu (routes/web.php) — session-based aplikácia s Blade + Tailwind CSS 4 frontendom, chránená autentifikáciou a rolami.
3. Verejnú prezentačnú stránku (/) — marketingová landing page bez nutnosti prihlásenia.

┌─────────────────────┐        REST API (Sanctum token)        ┌──────────────────────┐
│   Klientský e-shop  │ ─────────────────────────────────────▶ │   Commerce Engine    │
│                     │ ◀───────────────────────────────────── │   (Laravel API + BO) │
└─────────────────────┘                                        └──────────────────────┘
                                                                          │
                                                                          ▼
                                                                 ┌──────────────────-┐
                                                                 │  Databáza (SQLite/│
                                                                 │  MySQL/Postgres)  │
                                                                 └──────────────────-┘

2.2 Technologický stack

3. Funkčné požiadavky

3.1 Autentifikácia a používatelia

• Registrácia a prihlásenie do administrácie (session-based).
• Role používateľov: admin, manager, customer; middleware role:* obmedzuje prístup k jednotlivým sekciám administrácie.
• Voliteľná dvojfaktorová autentifikácia (2FA) cez TwoFactorController / TwoFactorChallengeController.
• Správa API tokenov (ApiTokenController) pre prístup k REST API cez Sanctum.
• Auditný log (AuditLogController) zaznamenávajúci zmeny v systéme.

3.2 Správa produktov (PIM)

• Entity: Product, ProductVariant, Category, Brand.
• CRUD operácie v administrácii (ProductController, CategoryController, BrandController), prístupné rolám admin, manager.
• Generovanie produktových štítkov (ProductLabelController).
• REST API pre čítanie katalógu (GET /api/v1/products, /products/{slug}, /categories, /categories/{slug}, /brands, /brands/{slug}) — verejne prístupné bez autentifikácie.

3.3 Skladové hospodárstvo (WMS)

• Entity: Warehouse, StockItem, StockMovement.
• Evidencia skladových pohybov (StockMovementController) s históriou zmien stavu zásob.

3.4 Košík a checkout (API)

• Podpora hosťovského košíka (identifikovaný guest_token v hlavičke X-Guest-Token) aj košíka prihláseného zákazníka.
• Endpointy: GET /api/v1/cart, POST /api/v1/cart/items, PATCH /api/v1/cart/items/{cartItem}, DELETE /api/v1/cart/items/{cartItem}.
• Guest checkout — dokončenie objednávky je možné bez prihlásenia (POST /api/v1/checkout); zákazník môže voliteľne vytvoriť účet priamo pri objednávke (parameter register + password), pričom po úspešnej registrácii API vráti prístupový token na automatické prihlásenie.
• Checkout vyžaduje kontaktné a fakturačné údaje: meno, priezvisko, e-mail, telefón, fakturačná adresa (ulica, mesto, PSČ, krajina).
• Doprava: výber kuriéra GLS alebo DPD (enum ShippingMethod).
• Platba: výber dobierka (COD, s príplatkom +2 € pripočítaným k celkovej sume objednávky) alebo bankový prevod (enum PaymentMethod).
• Pri prevode košíka na objednávku (guest → registrovaný / merge košíkov) sa korektne resetuje guest_token, aby nedochádzalo ku konfliktu unikátneho indexu pri ďalšom vytvorení hosťovského košíka.

3.5 Správa objednávok (OMS)

• Entity: Order, OrderItem, OrderStatusHistory.
• Stavový cyklus objednávky riadený enumom OrderStatus, zmena stavu cez OrderStatusController.
• Administrácia objednávok (OrderController) — zoznam, detail, úprava; prístupné rolám admin, manager.
• Zákaznícke REST API pre históriu vlastných objednávok: GET /api/v1/orders, GET /api/v1/orders/{order} (vyžaduje autentifikáciu cez Sanctum).

3.6 CRM — správa zákazníkov

• Entity: Customer, CustomerAddress.
• CRUD zákazníkov a správa ich adries (CustomerController, CustomerAddressController).

3.7 Cenotvorba a akcie

• Entity: Discount, Coupon, TaxRate, Currency.
• Správa zliav a kupónov (DiscountController, CouponController).
• Správa daňových sadzieb a mien (TaxRateController, CurrencyController) — obmedzené na rolu admin.

3.8 Dokumenty

• Entity: Document (typy podľa enumu DocumentType — napr. faktúra, dodací list, cenová ponuka).
• Generovanie dokumentov k objednávke (orders/{order}/documents), export do PDF (dompdf) a QR kódy.
• Správa dokumentov cez DocumentController (zoznam, detail, zmazanie).

3.9 Lokalizácia a nastavenia

• Entity: Language, Setting, EmailTemplate.
• Správa jazykov, e-mailových šablón a globálnych nastavení systému — dostupné len role admin.

3.10 Prezentačná (marketingová) stránka

• Verejne dostupná na / (route home), nevyžaduje prihlásenie.
• Sekcie: Home, Features, Pricing, API, Documentation, Roadmap, Support, odkaz Login.
• Sekcia Documentation obsahuje karty: ukážka administrácie, API dokumentácia, architektúra, licencie, cenník, kontakty.
• Cenník (Pricing): balíky Starter — 500 €, Professional — 1 500 €, Enterprise — 3 500 €.
• Vizuálny štýl: tmavá téma (tmavomodré pozadie #080f1f / #0a1428 / #0f1b33) s citrónovo žltými akcentami (#e8d500), transparentné logo a favicon.
• Terminológia: v marketingových textoch sa dôsledne používa výraz „e-shop“ namiesto „e-commerce“.

4. Dátový model (kľúčové entity)

User, Customer, CustomerAddress, Product, ProductVariant, Category, Brand, Warehouse, StockItem, StockMovement, Cart, CartItem, Order, OrderItem, OrderStatusHistory, Discount, Coupon, TaxRate, Currency, Language, Document, Setting, EmailTemplate, AuditLog.

Kľúčové enumy: OrderStatus, CartStatus, DiscountType, DocumentType, PaymentMethod (cod, bank_transfer), PaymentStatus, ShippingMethod (gls, dpd), UserRole (admin, manager, customer).

5. REST API — prehľad endpointov

6. Nefunkčné požiadavky

• Bezpečnosť: autentifikácia API cez Sanctum tokeny, voliteľná 2FA pre administráciu, kontrola prístupu podľa rolí (role:admin, role:admin,manager), auditný log zmien.
• Testovateľnosť: pokrytie funkčnými testami (PHPUnit) pre API endpointy (autentifikácia, košík, checkout); ku dňu vydania v1.0 prechádza 125/125 testov.
• Kvalita kódu: dodržiavanie štandardu Laravel Pint (vendor/bin/pint).
• Konfigurovateľnosť databázy: predvolene SQLite pre vývoj, s možnosťou prepnutia na MySQL/PostgreSQL cez .env.
• Rozšíriteľnosť: modulárna štruktúra (Services, Resources, Enums) umožňujúca postupné dopĺňanie ďalších modulov (integrácie s platobnými bránami, dopravcami, ERP, analytika).

7. Roadmapa (plánované rozšírenia)

Podľa sekcie Roadmap na prezentačnej stránke a README.md:

• Integrácie s platobnými bránami a externými dopravcami (nad rámec GLS/DPD).
• Rozšírená analytika a reporting.
• Ďalšie B2B funkcie a rozšírenia CRM/OMS modulov.

8. Súvisiace systémy

• E-shop (klient), ktorý konzumuje REST API Commerce Engine pre katalóg, košík, checkout a zákaznícke účty. Slúži ako ukážková implementácia integrácie s CE.

9. Referencie

• README.md — inštalácia, spustenie a prehľad modulov.
• CHANGELOG.md — história zmien k releasu v1.0.
• routes/api.php, routes/web.php — definícia dostupných endpointov.
• app/Enums/, app/Models/ — dátový model a stavové enumy.