Files
Suman/docs/TEHNICKA_DOKUMENTACIJA.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

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/medusa v2.22.3 (Node.js >= 22)
  • Admin Dashboard: Ugrađeni Medusa Admin (Vite + React) proširen sa @medusajs/admin-sdk i @medusajs/ui v4.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, baza medusa-suman-doo.
  • Redis 7: Kontejner umbrella-redis, port 6379.

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)

  1. Svaki regionalni admin u user.metadata ima zapisan sales_channel_id.
  2. Middleware presreće sve administratorske zahtjeve prema narudžbama (/admin/orders*).
  3. Zahtjev za listu (GET /admin/orders): Injektuje se filter req.query.sales_channel_id = [user.metadata.sales_channel_id]. Admin vidi samo narudžbe iz svoje države.
  4. Zahtjev za detalje (GET /admin/orders/:id): Provjerava se kanal narudžbe. Ukoliko ne pripada kanalu korisnika, backend automatski vraća HTTP 403 NOT_ALLOWED.
  5. 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 Email Š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/ui prateć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={...}>
  • toast notifikacije 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.ts provjerava sales_channel_id i štiti narudžbe sa 403 NOT_ALLOWED.
  • B2B CRM Widget: Ugrađen u Admin na customer.details, izgrađen 100% od @medusajs/ui komponenti bez izmišljenih elemenata.
  • B2B Cjenovnik: Kreiran override cjenovnik sa popustom za HoReCa B2B Partneri grupu.
  • Event Subscriber: Sluša order.placed i 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 build prolazi sa izlaznim kodom 0 za 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

  1. Suncobrani (suncobrani): Profesionalni i dvorišni suncobrani visokog kvaliteta proizvedeni u BiH.
  2. Pergole i bioklimatske tende (pergole-i-bioklimatske-tende): Luksuzni aluminijski sistemi, bioklimatske rotirajuće lamele i troslojni PVC Blackout krovovi.
  3. 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.com koji vidi isključivo narudžbe i kupce iz Hrvatske.