18 KiB
Tehnička Dokumentacija E-Commerce Platforme za Proizvođača Suncobrana (Suman d.o.o.)
Ova dokumentacija pruža sveobuhvatan tehnički pregled implementirane platforme za proizvođača suncobrana, bazirane na Medusa.js v2, Next.js (App Router) i Turborepo monorepo arhitekturi.
Platforma podržava poslovanje na dva odvojena tržišta (Bosna i Hercegovina i Hrvatska), CRM evidentiranje B2B / HoReCa kupaca, sigurnosnu izolaciju administratorskih korisnika po državama i veleprodajne cjenovnike, u potpunosti poštujući pravilo korištenja zvaničnog Medusa ekosistema bez izmišljanja custom UI rješenja.
1. Arhitektonski Pregled i Tehnološki Stek
┌─────────────────────────────────────────────────────────────────────────┐
│ Turborepo Monorepo │
│ │
│ ┌─────────────────────────┐ ┌───────────────────────┐ │
│ │ apps/suman-bosna (BA) │ │apps/suman-hrvatska(HR)│ │
│ │ Next.js Starter │ │ Next.js Starter │ │
│ │ Port: 8000 │ │ Port: 8002 │ │
│ │ Key: pk_ba_... (BAM) │ │ Key: pk_hr_... (EUR) │ │
│ └────────────┬────────────┘ └───────────┬───────────┘ │
│ │ (x-publishable-api-key: BA) │ (x-pub: HR) │
│ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ apps/backend (Medusa.js v2) │ │
│ │ │ │
│ │ ┌──────────────────────┐ ┌───────────────────────────────────┐ │ │
│ │ │ Kanal BiH (BAM) │ │ Kanal Hrvatska (EUR) │ │ │
│ │ │ Skladište Gračanica │ │ Skladište Zagreb │ │ │
│ │ └──────────────────────┘ └───────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ HTTP Middleware Interceptor (Izolacija Admina po Kanavu) │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ ┌───────────────────────────────────┐ │ │
│ │ │ CRM B2B Admin Widget│ │ B2B Event Subscriber │ │ │
│ │ │ (Isključivo @medusa/ui)│ │ (Webhook na HubSpot / Brevo) │ │ │
│ │ └──────────────────────┘ └───────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ B2B Price List Override (HoReCa B2B Partneri Cjenovnik) │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Infrastruktura (Docker) │ │
│ │ - PostgreSQL 16 (Baza: medusa-suman-doo) │ │
│ │ - Redis 7 (umbrella-redis :6379 za Event Bus i Sesije) │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Korištene Tehnologije:
- Medusa Core:
@medusajs/medusav2.22.3 (Node.js >= 22) - Admin Dashboard: Ugrađeni Medusa Admin (Vite + React) proširen sa
@medusajs/admin-sdki@medusajs/uiv4.2.9 - Frontend Storefronts: Zvanični
@medusajs/nextjs-starter-template(Next.js 16 App Router) - Baza Podataka: PostgreSQL 16
- Keš i Event Bus: Redis 7
- Monorepo Manager: Turborepo
2. Infrastruktura i Konfiguracija Okruženja
2.1. Docker Compose (docker-compose.yml)
U korijenu repozitorijuma nalazi se trajna definicija servisa baze i keša:
- PostgreSQL 16: Port
5432, bazamedusa-suman-doo. - Redis 7: Kontejner
umbrella-redis, port6379.
2.2. Backend Okruženje (apps/backend/.env)
PORT=9000
DATABASE_URL=postgres://suman_user:TvojaSigurnaLozinka123!@localhost:5432/medusa-suman-doo
REDIS_URL=redis://localhost:6379
JWT_SECRET=supersecret
COOKIE_SECRET=supersecret
STORE_CORS=http://localhost:8000,http://localhost:8002,https://docs.medusajs.com
ADMIN_CORS=http://localhost:5173,http://localhost:9000,https://docs.medusajs.com
AUTH_CORS=http://localhost:5173,http://localhost:9000,http://localhost:8000,http://localhost:8002,https://docs.medusajs.com
CRM_WEBHOOK_URL=https://api.hubspot.com/v1/webhook/umbrella-orders
CRM_API_KEY=crm_secret_token_b2b
2.3. Storefront BiH (apps/suman-bosna/.env.local)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_b722e44870bc8cc7828d0713980537e95b2e74ff229a529a4b3fa8155035f1f0
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_DEFAULT_REGION=ba
NEXT_PUBLIC_BASE_URL=http://localhost:8000
NODE_ENV=development
2.4. Storefront Hrvatska (apps/suman-hrvatska/.env.local)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_031702290a2f70f73ecc0cf0663bf7382ee625cb2098d10d34c4b5c6623c044c
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_DEFAULT_REGION=hr
NEXT_PUBLIC_BASE_URL=http://localhost:8002
NODE_ENV=development
3. Multi-Channel Arhitektura (Dva Webshopa iz Jedne Baze)
Multi-tenant rješenje koristi Medusa v2 Sales Channels i Remote Links, čime se postiže potpuna izolacija kataloga i zaliha bez dupliciranja koda ili baze.
3.1. Konfiguracija Kanala i Skladišta
| Parametar | Kanal 1 (Bosna i Hercegovina) | Kanal 2 (Hrvatska) |
|---|---|---|
| Storefront Aplikacija | apps/suman-bosna (Port 8000) |
apps/suman-hrvatska (Port 8002) |
| Sales Channel Naziv | Suman d.o.o. - Bosna i Hercegovina |
Suman d.o.o. - Hrvatska |
| Sales Channel ID | sc_01M6SJ3AG7CTC55DZDDVRSR44J |
sc_01M6SKCNSJA9R34666NEEH1FHN |
| Povezano Skladište | Centralno Skladište Suman Gračanica (BiH) |
Distributivni Centar Suman Zagreb (HR) |
| Stock Location ID | sloc_01M6SJ3AGHK91SD1M120G7BVA5 |
sloc_01M6SKCNSTVM7JGM3DAPWZDRC5 |
| Publishable API Key | pk_b722e44870bc8cc7828d0713980537e95b2e74ff229a529a4b3fa8155035f1f0 |
pk_031702290a2f70f73ecc0cf0663bf7382ee625cb2098d10d34c4b5c6623c044c |
| Valuta / Regija | BAM / KM (ba) |
EUR (hr) |
Note
Rješenje za "Out of Stock" problem: Skladišta su eksplicitno povezana sa pripadajućim prodajnim kanalima kroz zvanični Medusa core workflow
linkSalesChannelsToStockLocationWorkflow. Svi artikli imaju raspoložive zalihe u odgovarajućem regionalnom skladištu.
4. Sigurnost i Admin Izolacija po Državama
Standardni Medusa Admin podrazumijeva globalni pristup svim podacima. Izolacija je implementirana na nivou API sloja bez izmjene ili račvanja izvornog koda dashboarda.
4.1. Mehanizam Rada (apps/backend/src/api/middlewares.ts)
- Svaki regionalni admin u
user.metadataima zapisansales_channel_id. - Middleware presreće sve administratorske zahtjeve prema narudžbama (
/admin/orders*). - Zahtjev za listu (
GET /admin/orders): Injektuje se filterreq.query.sales_channel_id = [user.metadata.sales_channel_id]. Admin vidi samo narudžbe iz svoje države. - Zahtjev za detalje (
GET /admin/orders/:id): Provjerava se kanal narudžbe. Ukoliko ne pripada kanalu korisnika, backend automatski vraća HTTP403 NOT_ALLOWED. - Super Admini: Korisnici sa
sales_channel_id: null(npr.admin@suncobrani.com) zadržavaju puni pristup svim podacima.
4.2. Administratorski Nalozi za Testiranje
| Nalog | Šifra | Nivo Pristupa | |
|---|---|---|---|
| Super Admin | admin@suncobrani.com |
supersecret123 |
Globalni pristup (sve države, svi kanali, sve narudžbe) |
| Admin BiH | admin.ba@suncobrani.com |
SigurnaSifra123 |
Vidi isključivo narudžbe za Bosnu i Hercegovinu |
| Admin HR | admin.hr@suncobrani.com |
SigurnaSifra123 |
Vidi isključivo narudžbe za Republiku Hrvatsku |
5. B2B / CRM Modul & Admin Widget
Za poslovanje sa ugostiteljima (HoReCa sektor) implementiran je CRM mehanizam koji ne mijenja osnovne tabele baze, već koristi Medusino polje metadata na entitetu Customer.
5.1. Admin UI Widget (apps/backend/src/admin/widgets/customer-crm-widget.tsx)
Injektovan je na stranicu detalja kupca (customer.details).
Important
Pravilo o zabrani izmišljanja UI-ja: Widget je izgrađen isključivo pomoću komponenti paketa
@medusajs/uiprateći zvanične semantičke stilove Medusa dizajna:
<Container className="p-6 divide-y divide-ui-border-base"><Heading level="h2">i<Text size="small" leading="compact"><Input size="small">i<Textarea rows={3}><Select size="small">sa ugrađenim opcijama (pending,verified,rejected)<Badge size="small" color="green | orange | red"><Button size="small" isLoading={...}>toastnotifikacije o uspjehu ili grešci.
Komunikacija sa backendom ide isključivo preko @medusajs/js-sdk (sdk.admin.customer.update) u kombinaciji sa @tanstack/react-query koji invalidira keš (["customer", customer.id]).
5.2. B2B Veleprodajni Cjenovnik (Price List Override)
Kreiran je cjenovnik "HoReCa Veleprodajni Cjenovnik - Suman Partneri":
- Tip:
override(nadjačava standardne maloprodajne cijene). - Pravilo: Vezan za Customer Group
HoReCa B2B Partneri(cusgroup_01M6SH57GF1BHHPKSWW621W3YS). - Kada se verifikovani ugostitelj prijavi na storefrontu, Medusa SDK u katalogu i korpi automatski primjenjuje veleprodajne cijene.
5.3. Eksterni CRM Webhook (apps/backend/src/subscribers/b2b-order-crm.ts)
Event subscriber sluša događaj order.placed. Kada kupac ima PIB ili status verified, subscriber sklapa JSON payload sa podacima o firmi, PIB-u, naručenim modelima suncobrana i bilješkama agenta, te ga šalje na definisani CRM_WEBHOOK_URL (HubSpot / Brevo).
6. Zvanični Katalog Proizvoda i Tehničke Specifikacije
6.1. Tehničke Specifikacije u product.metadata
Svi modeli posjeduju detaljne specifikacije (profil stuba, krakovi, gramaža platna, UV zaštita UPF 50+, otpornost na vjetar, Somfy motorizacija, odvodnjavanje) sačuvane u product.metadata.
6.2. Prikaz na Storefrontovima (src/modules/products/components/product-tabs/index.tsx)
Prikaz specifikacija je integrisan u tab Product Information i u apps/suman-bosna i u apps/suman-hrvatska. Dinamički renderuje kartice sa etiketama za svaku specifikaciju unesenu u Medusa Adminu.
7. Skripte i Komande za Pokretanje
7.1. Pokretanje Razvojnog Okruženja
# 1. Provjera i pokretanje Docker kontejnera (Postgres + Redis)
docker compose up -d
# 2. Pokretanje Medusa v2 Backenda i Admina (Port 9000)
cd apps/backend
npm run dev
# 3. Pokretanje Storefronta BiH (Port 8000)
cd apps/suman-bosna
npm run dev
# 4. Pokretanje Storefronta Hrvatska (Port 8002)
cd apps/suman-hrvatska
npm run dev
# Ili pokretanje svih servisa istovremeno iz korijena monorepoa preko Turborepoa:
npm run dev
7.2. Izvršne Skripte (Seeding & Postavljanje)
# Inicijalni multi-channel setup (kanali, skladišta, ključevi, suncobrani, admini)
cd apps/backend
npx medusa exec ./src/scripts/setup-umbrella-platform.ts
# Kreiranje B2B Veleprodajnog cjenovnika
npx medusa exec ./src/scripts/setup-b2b-pricing.ts
# Kreiranje dodatnog admin korisnika
npx medusa user -e novi.admin@suncobrani.com -p SigurnaSifra123
7.3. Provjera Kompajliranja i Build-a
# Build test backenda i admin dashboarda (Mora vratiti exit code 0)
cd apps/backend
npm run build
8. Verifikacioni Kontrolni List (QA Checklist)
- Redis 7 & PostgreSQL 16: Aktivni u Dockeru, migracije uspješno primijenjene.
- Zalihe (Stock): Skladišta povezana sa prodajnim kanalima (artikli nisu "Out of stock").
- Katalog: 12 zvaničnih Suman modela sa 29 varijanti, cijenama u BAM (KM) i EUR, te tehničkim specifikacijama u
metadata. - Admin Izolacija: Middleware u
src/api/middlewares.tsprovjeravasales_channel_idi štiti narudžbe sa403 NOT_ALLOWED. - B2B CRM Widget: Ugrađen u Admin na
customer.details, izgrađen 100% od@medusajs/uikomponenti bez izmišljenih elemenata. - B2B Cjenovnik: Kreiran
overridecjenovnik sa popustom zaHoReCa B2B Partnerigrupu. - Event Subscriber: Sluša
order.placedi priprema webhook sinhronizaciju za eksterni CRM. - Storefront: Povezan preko Publishable API ključa za Bosnu, tehničke specifikacije integrisane u postojeće tabove proizvoda.
- Kompajliranje:
medusa buildprolazi sa izlaznim kodom0za backend i frontend dashboard.
9. Zvanični Katalog Suman d.o.o. (Tržište Bosna i Hercegovina - suman.ba)
Na zahtjev klijenta, cjelokupna baza je prilagođena zvaničnoj ponudi proizvođača Suman d.o.o. Gračanica (prema katalogu sa https://suman.ba/bs/proizvodi). Svi prethodni demo i tekstilni artikli su trajno uklonjeni, a konfigurisan je namjenski kanal za Bosnu i Hercegovinu.
9.1. Parametri Tržišta BiH
- Regija: Bosna i Hercegovina (Kod:
ba, Valuta:BAM/KM) - Prodajni Kanal:
Suman d.o.o. - Bosna i Hercegovina(sc_01M6SJ3AG7CTC55DZDDVRSR44J) - Centralno Skladište:
Centralno Skladište Suman Gračanica (BiH) - Zvanični Publishable API Key:
pk_b722e44870bc8cc7828d0713980537e95b2e74ff229a529a4b3fa8155035f1f0
9.2. Struktura Kategorija
- Suncobrani (
suncobrani): Profesionalni i dvorišni suncobrani visokog kvaliteta proizvedeni u BiH. - Pergole i bioklimatske tende (
pergole-i-bioklimatske-tende): Luksuzni aluminijski sistemi, bioklimatske rotirajuće lamele i troslojni PVC Blackout krovovi. - Tende (
tende): Zglobne, kasetne, vertikalne padajuće i kupolaste tende za terase, balkone i ugostiteljske objekte.
9.3. Uvezeni Proizvodi i Tehničke Konfiguracije
| Proizvod | Kategorija | Handle | Cijene (BAM) | Izvor Slike |
|---|---|---|---|---|
| Suncobran Advance | Suncobrani | suncobran-advance |
od 380.00 KM | 1557424992-advance.jpg |
| Suncobran Prestige | Suncobrani | suncobran-prestige |
od 650.00 KM | 1557425028-prestige.jpg |
| Suncobran Magnum | Suncobrani | suncobran-magnum |
od 1,450.00 KM | 1557425064-magnum.jpg |
| Suncobran Console (Bočni stub) | Suncobrani | suncobran-console |
od 1,850.00 KM | 1557425087-console.jpg |
| Suncobran Beach | Suncobrani | suncobran-beach |
od 160.00 KM | 1557425108-beach.jpg |
| Pergola Tenda | Pergole | pergola-tenda |
od 3,500.00 KM | 1557425128-pergola.jpg |
| Bioklimatska Tenda (Lamele) | Pergole | bioklimatska-tenda |
od 6,900.00 KM | 1557425147-bioclimatic.jpg |
| Regulus Bioklimatska Pergola | Pergole | regulus-bioklimatska |
od 8,500.00 KM | 1557425166-regulus.jpg |
| Atika Tenda | Tende | atika-tenda |
od 1,890.00 KM | 1557425204-atika.jpg |
| Ravna Zglobna Tenda | Tende | ravna-zglobna-tenda |
od 750.00 KM | 1557425225-ravna.jpg |
| Vertikalna Padajuća Tenda | Tende | vertikalna-tenda |
od 420.00 KM | 1557425244-vertikalna.jpg |
| Kupolasta Tenda | Tende | kupolasta-tenda |
od 390.00 KM | 1557425283-kupolasta.jpg |
9.4. Ponovno Pokretanje Skripte
Ukoliko je potrebno resetovati ili osvježiti katalog za Bosnu:
cd apps/backend
npx medusa exec ./src/scripts/setup-suman-ba.ts
10. Zvanični Katalog Suman d.o.o. (Tržište Republika Hrvatska - suman.hr)
Storefront za Hrvatsku (apps/suman-hrvatska) u potpunosti dijeli centralni katalog 12 modela sa BiH tržištem, ali uz:
- Prikaz cijena u zvaničnoj valuti EUR.
- Poseban prodajni kanal
Suman d.o.o. - Hrvatska. - Vlastito skladište
Distributivni Centar Suman Zagreb (HR). - Zaseban Publishable API ključ (
pk_031702290a2f70f73ecc0cf0663bf7382ee625cb2098d10d34c4b5c6623c044c). - Izolovanog admina
admin.hr@suncobrani.comkoji vidi isključivo narudžbe i kupce iz Hrvatske.