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

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.