300 lines
18 KiB
Markdown
300 lines
18 KiB
Markdown
# 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`)
|
|
```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`)
|
|
```env
|
|
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`)
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Build test backenda i admin dashboarda (Mora vratiti exit code 0)
|
|
cd apps/backend
|
|
npm run build
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Verifikacioni Kontrolni List (QA Checklist)
|
|
|
|
- [x] **Redis 7 & PostgreSQL 16**: Aktivni u Dockeru, migracije uspješno primijenjene.
|
|
- [x] **Zalihe (Stock)**: Skladišta povezana sa prodajnim kanalima (artikli nisu "Out of stock").
|
|
- [x] **Katalog**: 12 zvaničnih Suman modela sa 29 varijanti, cijenama u BAM (KM) i EUR, te tehničkim specifikacijama u `metadata`.
|
|
- [x] **Admin Izolacija**: Middleware u `src/api/middlewares.ts` provjerava `sales_channel_id` i štiti narudžbe sa `403 NOT_ALLOWED`.
|
|
- [x] **B2B CRM Widget**: Ugrađen u Admin na `customer.details`, izgrađen 100% od `@medusajs/ui` komponenti bez izmišljenih elemenata.
|
|
- [x] **B2B Cjenovnik**: Kreiran `override` cjenovnik sa popustom za `HoReCa B2B Partneri` grupu.
|
|
- [x] **Event Subscriber**: Sluša `order.placed` i priprema webhook sinhronizaciju za eksterni CRM.
|
|
- [x] **Storefront**: Povezan preko Publishable API ključa za Bosnu, tehničke specifikacije integrisane u postojeće tabove proizvoda.
|
|
- [x] **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:
|
|
```bash
|
|
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.
|
|
|
|
|
|
|