first commit

This commit is contained in:
Nermin Karic
2026-11-22 21:49:17 +01:00
commit f5e2fcbf98
693 changed files with 82975 additions and 0 deletions

View File

@@ -0,0 +1,299 @@
# 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.

View File

@@ -0,0 +1,79 @@
# Faza 01: HR Webshop i Multi-Channel Sinhronizacija (`apps/suman-hrvatska`)
**Prioritet projekta:** PRIORITET 1 (Soft opening: 15. 01. 2027. / Primopredaja: 15. 02. 2027.)
---
## 1. Cilj Faze
U skladu sa ugovorom (Tačka 1 i Tačka 19), **webshop za Hrvatsku (`shop.suman.hr`) je primarni fokus projekta**.
Trenutno je sav napredni UI dizajn implementiran u `apps/suman-bosna`, dok je `apps/suman-hrvatska` ostao na bazičnom Medusa starter predlošku. Cilj ove faze je prenos i potpuna adaptacija modernog dizajna na HR storefront sa hrvatskom terminologijom, valutom EUR i povezivanjem na magacin Zagreb.
---
## 2. Zadaci za Implementaciju
### 2.1. Prenos UI komponenti na `apps/suman-hrvatska`
Kopirati i prilagoditi komponente iz `apps/suman-bosna/src/modules/home/components/` u `apps/suman-hrvatska/src/modules/home/components/`:
- `hero` (Full width sa opcijom videa ili slike, podrška za floating header overlay)
- `partners-ticker` (Marquee sa partnerima)
- `product-showcase` (Slajder sa 4 glavne kategorije suncobrana)
- `mission-section` (Kartice: tradicija, vizija, standardi kvaliteta)
- `cta-banner` (Full-bleed poziv na akciju)
- `latest-news` (Horizontalni news slajder sa karticama)
- `faq-section` (Dvo-kolonski harmonika FAQ)
- `nav` (Verzija 1: Floating zaobljeni header + Verzija 2: Klasični puni header)
- `footer` (Partnerski banner kartica + 4 kolone navigacije)
### 2.2. Lokalizacija na Hrvatski Jezik (HR) i Valuta EUR
U `apps/suman-hrvatska/src/config/`:
- `navigation.json`: "Košarica", "Moj račun", "Svi proizvodi", "Suncobrani", "Pergole", "Tende".
- `footer.json`: Linkovi na hrvatske zakonske stranice ("Uvjeti poslovanja", "Dostava i povrat", "Privatnost podataka").
- `hero.json`, `banner.json`, `mission.json`, `faq.json`: Lektura teksta na hrvatski standard (npr. *tjedana* umjesto *sedmica*, *uvjeti* umjesto *uslovi*, *cijene* sa oznakom € / EUR).
### 2.3. Povezivanje sa Medusa Backendom
U `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
```
- Potvrditi da Publishable Key filtrira katalog isključivo za kanal `Suman d.o.o. - Hrvatska`.
- Potvrditi da se cijene automatski prikazuju u **EUR (€)** sa stopom PDV-a od **25%**.
- Potvrditi da se dostupnost računa prema skladištu `Distributivni Centar Suman Zagreb (HR)`.
---
## 3. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/suman-hrvatska/
├── src/
│ ├── config/
│ │ ├── banner.json
│ │ ├── faq.json
│ │ ├── footer.json
│ │ ├── hero.json
│ │ ├── mission.json
│ │ ├── navigation.json
│ │ ├── news.json
│ │ └── products-showcase.json
│ ├── components/ui/
│ │ ├── logo.tsx
│ │ ├── section-header.tsx
│ │ └── dynamic-icon.tsx
│ ├── modules/
│ │ ├── home/components/...
│ │ └── layout/templates/
│ │ ├── nav/index.tsx
│ │ └── footer/index.tsx
│ └── app/[countryCode]/(main)/page.tsx
```
---
## 4. Kriteriji Uspješnosti (DoD - Definition of Done)
1. Storefront `apps/suman-hrvatska` se pokreće na portu `8002` bez ijedne greške.
2. Naslovna stranica vizuelno je 100% identična visokokvalitetnom dizajnu sa plutajućim headerom, responsive prikazom i konzistentnim razmacima.
3. Sve cijene su u EUR (€).
4. Sav tekst na navigaciji, dugmadima, sekcijama i footeru je na standardnom hrvatskom jeziku.

View File

@@ -0,0 +1,179 @@
# Faza 02: Tri Prodajna Scenarija i Novi Medusa Modul za Proizvode na Upit
**Referenca ugovora:** Tačka 3, 4, 6 i 7 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
Suman prodaje proizvode kroz tri potpuno različita poslovna toka:
1. **Scenarij 1a (Na zalihi)**: Roba je fizički na zalihi u skladištu (Zagreb ili Gračanica). Direktna kupovina kroz korpu i brza isporuka.
2. **Scenarij 1b (Po narudžbi)**: Roba se proizvodi po narudžbi kupca. Kupac normalno plaća kroz checkout, uz istaknut rok izrade/isporuke (npr. *„Po narudžbi — isporuka za 10–14 radnih dana“*).
3. **Scenarij 2 (Na upit)**: **Isključivo za tende, pergole i nestandardne projekte**. Nema automatske cijene i nema dugmeta za dodavanje u korpu. Umjesto toga, razvija se **novi Medusa v2 modul za upite** koji se maksimalno oslanja na postojeći Medusa ekosistem (katalog, kanale, administraciju i widgete).
---
## 2. Novi Medusa v2 Modul za Proizvode i Upite (`inquiry` modul)
Kako bi se maksimalno iskoristio Medusa.js framework bez improvizovanih vanjskih baza ili nepovezanih skripti, kreira se formalni Medusa v2 modul:
📁 `apps/backend/src/modules/inquiry/`
```
apps/backend/src/modules/inquiry/
├── index.ts # Definicija modula (Module Definition)
├── models/
│ └── inquiry.ts # Data Model definisan preko model.define
├── service.ts # InquiryModuleService (nasljeđuje MedusaService)
└── migrations/ # Automatske MikroORM migracije za PostgreSQL
```
### 2.1. Data Model Upita (`apps/backend/src/modules/inquiry/models/inquiry.ts`)
Definisanje modela korištenjem zvaničnog `@medusajs/framework/utils`:
```typescript
import { model } from "@medusajs/framework/utils"
export const Inquiry = model.define("inquiry", {
id: model.id().primaryKey(),
name: model.text(),
email: model.text(),
phone: model.text(),
company_name: model.text().nullable(),
city: model.text(),
dimensions: model.text().nullable(), // npr. "6x4m, terasa restorana"
message: model.text(),
status: model.enum([
"new", // Novi neobrađeni upit
"contacted", // Kupac kontaktiran
"quote_sent", // Ponuda pripremljena i poslata
"won", // Realizovana prodaja
"lost", // Otkazano / Nerealizovano
"archived" // Arhivirano
]).default("new"),
notes: model.text().nullable(), // Interne zabilješke komercijaliste
metadata: model.json().nullable(), // Dodatna polja (tip montiranja, boja fasade, itd.)
})
```
### 2.2. Remote Links — Povezivanje sa Postojećim Medusa Entitetima
Maksimalno iskorištavamo postojeće Medusa v2 module putem Remote Links mehanizma (`defineLink`):
`apps/backend/src/links/inquiry-links.ts`
1. **Veza sa Medusa Katalogom Proizvoda (`Modules.PRODUCT`)**:
- Svaki upit se povezuje sa postojećim Medusa proizvodom (npr. *Regulus Bioklimatska Pergola*, *Atika Tenda*).
- Koriste se već uneseni nazivi, opisi, tehničke specifikacije i galerije slika iz Medusa baze.
2. **Veza sa Prodajnim Kanalom (`Modules.SALES_CHANNEL`)**:
- Upit se veže za prodajni kanal (`Suman d.o.o. - Hrvatska` ili `Suman d.o.o. - Bosna i Hercegovina`).
- Ovo automatski omogućava **izolaciju ovlasti**: administrator u Zagrebu vidi samo upite sa `shop.suman.hr`, a administrator u Gračanici samo sa `shop.suman.ba`.
3. **Veza sa Kupcem (`Modules.CUSTOMER`)**:
- Ako je kupac već registrovan u Medusi, upit se automatski veže za njegov profil i CRM historiju.
---
## 3. Upravljanje Proizvodima na Upit u Medusa Adminu
Kako bi administratori mogli jednostavno označiti koji proizvodi idu preko upita i pratiti pristigle upite, koriste se zvanične Medusa Admin ekstenzije (`@medusajs/admin-sdk` i `@medusajs/ui`):
### 3.1. Admin Widget na Detaljima Proizvoda (`product.details.after`)
`apps/backend/src/admin/widgets/product-inquiry-widget.tsx`
- Ubacuje se direktno na Medusinu ugrađenu stranicu proizvoda (`/app/products/:id`).
- Sadrži:
- **Prekidač (Switch / Toggle)**: *"Prodajni scenarij: Proizvod na upit (Quote Only)"*.
- **Polja za postavke upita**: Oznaka dugmeta (npr. *"Zatražite izmjeru i ponudu"*), zahtijevana polja (npr. traži unos dimenzija prostora).
- **Pregled upita za taj proizvod**: Mini-tabela sa svim kupcima koji su poslali upit specifično za taj model tende ili pergole.
### 3.2. Namjenska Admin Stranica: `/app/inquiries` (Pregled Svih Upita)
`apps/backend/src/admin/routes/inquiries/page.tsx`
- Kreira novu stavku u glavnom meniju Medusa Admina: **"Upiti i Ponude"**.
- Prikazuje tabelu sa svim prispjelim upitima sa filtriranjem po:
- **Tržištu** (Hrvatska / BiH)
- **Statusu** (`Novi`, `Kontaktiran`, `Ponuda poslata`, `Završeno`)
- **Proizvodu** (Pergole, Kasetne tende, Vertikalne tende)
- **Datumu prijema**
- Klikom na red u tabeli otvara se bočni panel (**Drawer**) sa kompletnim podacima kupca, porukom, dimenzijama i mogućnošću unosa internih bilješki i promjene statusa.
---
## 4. Workflows i Automatske Notifikacije
### 4.1. Medusa Workflow: `createInquiryWorkflow`
`apps/backend/src/workflows/create-inquiry.ts`
1. **Validacija ulaznih podataka**: Provjera ispravnosti emaila, telefona i postojanja proizvoda.
2. **Kreiranje zapisa u bazi**: Upis u tabelu `inquiry` preko `InquiryModuleService`.
3. **Povezivanje Remote Linkova**: Automatsko vezivanje za proizvod i prodajni kanal.
4. **Emitovanje događaja**: `eventBus.emit("inquiry.created", { id, sales_channel_id })`.
### 4.2. Subscriber za Email Notifikacije (`subscribers/inquiry-notifier.ts`)
- **Email komercijali Sumana**: Obavještava prodajni tim o novom upitu sa svim detaljima (dimenzije, grad, telefon, link direktno u Medusa Admin).
- **Email potvrde kupcu**: *"Zahvaljujemo na interesu za [Naziv Proizvoda]. Vaš upit je zaprimljen i naš komercijalni tim će vas kontaktirati u roku od 24 radna sata."*
---
## 5. Storefront Prikaz (Korisničko Iskustvo na Webu)
### 5.1. Tri Prodajna Scenarija na PDP Stranici (`ProductActions`)
Na stranici proizvoda u `apps/suman-hrvatska` i `apps/suman-bosna`, komponenta automatski prepoznaje prodajni model:
1. **Scenarij 1a (`in_stock`) — Na zalihi**:
- Zeleni bedž: `✓ Na zalihi` (dostava 2–4 radna dana).
- Standardni prikaz cijene i dugme *"Dodaj u košaricu"*.
2. **Scenarij 1b (`made_to_order`) — Po narudžbi**:
- Narandžasti bedž: `⏱ Po narudžbi — isporuka za {lead_time}`.
- Prikaz cijene i dugme *"Naruči uz izradu"*.
- U korpi i na računu jasno istaknut rok isporuke za tu stavku.
3. **Scenarij 2 (`quote_only`) — Proizvod na upit (Tende i Pergole)**:
- **Cijena je sakrivena** (nema polja za cijenu niti nula KM/EUR).
- **Dugme za korpu je uklonjeno**.
- Prikazuje se istaknuto primarno dugme: *"Zatražite ponudu i savjetovanje"*.
- Klikom se otvara responzivna forma prilagođena proizvodu.
### 5.2. Forma za Slanje Upita (`InquiryModal` / `InquiryForm`)
`src/modules/products/components/inquiry-modal/index.tsx`
- Polja:
- Ime i prezime
- Naziv firme (opciono)
- E-mail i Broj telefona
- Grad / Lokacija ugradnje
- Okvirne dimenzije prostora (širina x izbačaj u metrima)
- Poruka / Opis prostora (terasa, dvorište, balkon)
- Podaci se šalju na `POST /store/inquiries`.
- Kupac odmah dobija potvrdu na ekranu sa brojem upita.
---
## 6. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/backend/
├── src/
│ ├── modules/inquiry/ # NOVI MEDUSA V2 MODUL
│ │ ├── index.ts
│ │ ├── models/inquiry.ts
│ │ ├── service.ts
│ │ └── migrations/...
│ ├── links/inquiry-links.ts # Remote Links (Product & SalesChannel)
│ ├── api/
│ │ ├── store/inquiries/route.ts # Storefront POST API
│ │ └── admin/inquiries/route.ts # Admin GET & PATCH API
│ ├── workflows/create-inquiry.ts # Medusa workflow za unos upita
│ ├── subscribers/inquiry-notifier.ts # Email obavijesti
│ └── admin/
│ ├── routes/inquiries/page.tsx # Samostalni Admin ekran za upite
│ └── widgets/product-inquiry-widget.tsx # Widget na detaljima proizvoda
apps/suman-hrvatska/ & apps/suman-bosna/
├── src/
│ ├── modules/products/
│ │ ├── components/
│ │ │ ├── product-actions/index.tsx # Prepoznavanje quote_only scenarija
│ │ │ ├── product-price/index.tsx # Sakrivanje cijene za quote_only
│ │ │ ├── sale-scenario-badge/index.tsx # Bedževi raspoloživosti
│ │ │ └── inquiry-modal/index.tsx # Responzivna forma za slanje upita
│ │ └── templates/index.tsx # Layout stranice proizvoda
```
---
## 7. Kriteriji Uspješnosti (DoD)
1. **Medusa Admin ima novu stavku "Upiti i Ponude"** sa tabelom, statusima i bočnim Drawerom.
2. **Na svakom proizvodu u Medusa Adminu postoji widget** kojim se proizvod može jednim klikom postaviti kao "Na upit", uz uvid u sve upite za taj artikal.
3. Za tende i pergole na webshopu **nema cijene niti dugmeta za kupovinu** — prikazuje se dugme *"Zatražite ponudu"*.
4. Popunjavanje i slanje forme na webshopu automatski kreira zapis u Medusa bazi, povezuje ga sa proizvodom i kanalom, te šalje email notifikacije.
5. Administrator za Hrvatsku vidi samo upite sa `shop.suman.hr`, a administrator za BiH samo sa `shop.suman.ba`.

View File

@@ -0,0 +1,159 @@
# Faza 03: Dinamički 2D Konfigurator Suncobrana (Medusa-Driven & Responsive)
**Referenca ugovora:** Tačka 2, 12, 13 i 17 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
Implementirati **2D Konfigurator suncobrana** direktno integrisan u webshop sa mogućnošću trenutne kupovine konfigurisane stavke kroz standardnu korpu i checkout.
> [!IMPORTANT]
> ### KLJUČNI ZAHTJEV ZA DINAMIČNOST I VIZUELNI PRIKAZ
> 1. **Trenutni vizuelni prikaz**: Budući da klijent još nije dostavio konačne 2D PNG rendere (rok po ugovoru je 01. 12. 2026.), konfigurator mora **već sada imati živu vizuelnu interakciju** — odabir boje platna u realnom vremenu mijenja boju kupole suncobrana, odabir konstrukcije mijenja izgled stuba/krakova, a odabir postolja mijenja bazu suncobrana pomoću slojevitog SVG/Canvas/CSS renderovanja.
> 2. **Medusa-Driven (Bez programiranja)**: Arhitektura mora biti u potpunosti dinamička. Sve opcije, boje, cijene i postolja čitaju se iz Medusa baze. Kada administrator u Medusa Adminu doda novu boju platna ili novi tip postolja, **konfigurator to automatski prikazuje bez potrebe za izmjenom koda na frontendu**.
> 3. **100% Responsive**: Besprijekoran prikaz i lakoća korištenja na mobilnim telefonima, tabletima i velikim desktop ekranima.
---
## 2. Arhitektura Podataka u Medusa Backend-u
Konfigurator koristi standardni Medusa v2 sistem opcija i varijanti (`ProductOption` i `ProductVariant`), dopunjen sa vizuelnim atributima u `metadata`:
### 2.1. Definicija Opcija Proizvoda (`ProductOptions`)
Za svaki model suncobrana (npr. *Suncobran Prestige*, *Suncobran Magnum*, *Suncobran Console*), u Medusi se kreiraju opcije:
1. **`Dimenzija i Oblik`**:
- Vrijednosti: `3.0 x 3.0 m Kvadratni`, `3.5 x 3.5 m Kvadratni`, `4.0 x 4.0 m Kvadratni`, `Ø 4.0 m Okrugli`
2. **`Boja Platna`**:
- Vrijednosti sa `metadata` bojom:
- `Antracit siva` (`color_hex: "#2B2D2F"`)
- `Bež / Natur` (`color_hex: "#E8D8C8"`)
- `Bordo crvena` (`color_hex: "#6B1D2F"`)
- `Tamno plava / Navy` (`color_hex: "#012555"`)
- `Bijela` (`color_hex: "#F5F5F5"`)
- `Crna` (`color_hex: "#1A1A1A"`)
3. **`Boja Konstrukcije`**:
- Vrijednosti sa `metadata` teksturom:
- `Eloksirani natur aluminij` (`color_hex: "#C0C0C0"`)
- `Antracit plastificirani` (`color_hex: "#33373B"`)
- `Bijeli plastificirani` (`color_hex: "#FFFFFF"`)
4. **`Postolje i Učvršćenje`**:
- Vrijednosti:
- `Križno postolje (osnovno, bez ploča)`
- `Križno postolje sa 4 betonske ploče (120 kg)`
- `Podna ugradna prirubnica (za betoniranje u podlogu)`
- `Mobilno postolje sa točkovima i kočnicom`
5. **`Dodatna Oprema`**:
- Vrijednosti: `Bez dodataka`, `Zaštitna navlaka sa patentom`, `LED rasvjeta na krakovima`, `Navlaka + LED rasvjeta`
### 2.2. Pravila Kompatibilnosti (`compatibility_rules`)
U `product.metadata.configurator_rules` definišu se pravila:
```json
{
"forbidden_combinations": [
{
"dimenzija": "4.0 x 4.0 m Kvadratni",
"postolje": "Križno postolje (osnovno, bez ploča)",
"reason_hr": "Za suncobran dimenzija 4x4m obavezno je postolje sa betonskim pločama ili podna prirubnica zbog stabilnosti na vjetru.",
"reason_ba": "Za suncobran dimenzija 4x4m obavezno je postolje sa betonskim pločama ili podna prirubnica zbog stabilnosti na vjetru."
}
]
}
```
---
## 3. Slojeviti 2D Canvas/SVG Engine (Frontend)
Komponenta `UmbrellaVisualizer` radi na principu **4 vizuelna sloja (Layers)**:
```
┌────────────────────────────────────────────────────────┐
│ Layer 4: Dodatna oprema (Navlaka / LED sjaj) │
├────────────────────────────────────────────────────────┤
│ Layer 3: Platno suncobrana (SVG kupola sa CSS bojom) │
├────────────────────────────────────────────────────────┤
│ Layer 2: Konstrukcija (Stub, zglobovi, krakovi) │
├────────────────────────────────────────────────────────┤
│ Layer 1: Postolje (Križ, betonske ploče ili prirubnica)│
└────────────────────────────────────────────────────────┘
```
- **Dinamičko bojenje platna**: Boja platna se primjenjuje kao dinamička CSS maska ili SVG fill preko bazne teksture sjenčenja (`mix-blend-mode: multiply` sa realističnim naborima tkanine).
- **Zamjena slojeva kada stignu Džafini renderi**: Kada klijent dostavi finalne PNG rendere (rok 01. 12.), u Medusa varijante se jednostavno upisuju URL-ovi gotovih PNG slojeva u `metadata.layer_image_url`, i vizuelizator automatski prelazi na fotografske slojeve bez izmjene koda!
---
## 4. Korisnički Doživljaj (UX) i Responsivnost
### 4.1. Desktop Prikaz (2 Kolone)
- **Lijeva kolona (Sticky 60%)**:
- Veliki interaktivni 2D prikaz suncobrana.
- Dugmad za brzi pregled (Rotacija/ugao, prikaz otvoren/zatvoren suncobran, zumiranje detalja tkanine).
- **Desna kolona (40% sa skrolovanjem)**:
1. Naziv modela i oznaka raspoloživosti (*Na zalihi* ili *Po narudžbi — isporuka za 14 dana*).
2. Koraci konfiguracije sa vizuelnim swatch krugovima za boje i karticama za opremu.
3. Cijena koja se ažurira u realnom vremenu pri svakom kliku (EUR u HR, KM u BiH).
4. Dugme *"Dodaj u košaricu"* sa sažetkom konfiguracije.
### 4.2. Mobilni Prikaz (Prilagođeno dodiru)
- **Gornji dio (fiksiran ili polu-sticky)**: 2D vizuelni preview suncobrana koji se odmah ažurira.
- **Donji dio**: Horizontalni koraci (*1. Krov → 2. Platno → 3. Boja konstrukcije → 4. Postolje → 5. Dodaci*).
- **Fiksno donje dno (Sticky Bottom Bar)**:
- Prikaz trenutne ukupne cijene u EUR/KM.
- Dugme *"Dodaj konfiguraciju u košaricu"*.
---
## 5. Integracija sa Medusa Korpom i Checkoutom
Kada kupac klikne *"Dodaj u košaricu"*:
1. Front-end pronalazi tačnu `ProductVariant` ili kreira stavku sa specifikacijom.
2. U `CartLineItem.metadata` upisuju se:
```json
{
"is_configured": true,
"configured_options": {
"model": "Suncobran Prestige",
"dimension": "3.5 x 3.5 m Kvadratni",
"fabric_color": "Antracit siva (#2B2D2F)",
"frame_color": "Eloksirani natur aluminij",
"base": "Križno postolje sa 4 betonske ploče",
"accessories": "Zaštitna navlaka sa patentom"
},
"generated_sku": "SUM-PRES-3535-ANT-NAT-BASE4-COV",
"preview_snapshot_url": "..."
}
```
3. Cijena se verifikuje na Medusa backendu iz cjenovnika pripadajuće regije.
4. U korpi, na checkoutu, u email potvrdi i u Medusa Adminu prikazuje se kompletan spisak opcija i slika konfiguracije.
---
## 6. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/suman-hrvatska/ & apps/suman-bosna/
├── src/
│ ├── modules/configurator/
│ │ ├── components/
│ │ │ ├── umbrella-configurator.tsx # Glavni kontejner konfiguratora
│ │ │ ├── umbrella-visualizer.tsx # 2D Canvas/SVG slojeviti prikaz
│ │ │ ├── option-selector-tabs.tsx # Koraci odabira (platno, postolje...)
│ │ │ ├── color-swatch-picker.tsx # Izbor boje platna i konstrukcije
│ │ │ ├── compatibility-alert.tsx # Upozorenje na nedozvoljene kombinacije
│ │ │ └── configurator-sticky-bar.tsx # Mobilna traka sa cijenom i korpom
│ │ └── lib/
│ │ ├── compatibility-checker.ts # Logika pravila kompatibilnosti
│ │ └── price-calculator.ts # Proračun cijene konfiguracije
│ └── app/[countryCode]/(main)/products/[handle]/page.tsx
```
---
## 7. Kriteriji Uspješnosti (DoD)
1. Konfigurator je dostupan na stranici suncobrana i odmah vizuelno reaguje na promjenu svake opcije (boja platna, konstrukcija, postolje).
2. Dodavanje nove boje ili novog postolja u Medusa Adminu automatski se pojavljuje u konfiguratoru na frontendu.
3. Nedozvoljene kombinacije (npr. preveliko platno bez adekvatnog postolja) su onemogućene sa jasnom porukom kupcu.
4. Konfigurisani proizvod se dodaje u korpu sa tačnim SKU-om, cijenom i spiskom opcija, te se može kupiti kroz standardni checkout.
5. Prikaz na mobilnom telefonu je potpuno fluidan, brz i jednostavan za korištenje jednim prstom.

View File

@@ -0,0 +1,103 @@
# Faza 04: Dostavne Zone, Lično Preuzimanje i Pravna Lica (R1 Račun)
**Referenca ugovora:** Tačka 9 i 18 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
1. **Dostavne zone i lično preuzimanje**: Suncobrani i postolja su glomazna i teška roba. Za Hrvatsku je obavezno razdvajanje dostave na **Kopno** i **Otoke** (zbog trajektnog transporta), kao i opcija **Ličnog preuzimanja u Zagrebu (0 EUR)**. Za BiH se postavlja zona **Cijela BiH** i **Lično preuzimanje u Gračanici (0 KM)**.
2. **Kupovina za pravna lica (R1 Račun)**: Značajan dio kupaca Sumana su ugostitelji, hoteli i preduzeća. U checkoutu je obavezno omogućiti unos podataka za firmu: **OIB za Hrvatsku** (uz validaciju od 11 cifara) te **JIB i PDV broj za BiH**.
3. **PDV obračun**: Jasno iskazan PDV (25% za HR, 17% za BiH) na svim koracima korpe i checkouta.
---
## 2. Implementacija Dostave i Ličnog Preuzimanja
### 2.1. Konfiguracija Shipping Opcija u Medusi
U Medusa backendu se za regije konfigurišu namjenske opcije dostave:
#### Za Hrvatsku (`region_hr`):
1. **Dostava na adresu — Kopno**:
- Cijena: npr. 25,00 € (besplatno za narudžbe iznad zadanog iznosa, npr. 500 €).
- Rok isporuke: 2–4 radna dana.
2. **Dostava na adresu — Otoci**:
- Cijena: prilagođena otočna tarifa (npr. 45,00 €).
- Rok isporuke: 3–7 radnih dana.
3. **Lično preuzimanje — Distributivni centar Zagreb**:
- Cijena: **0,00 € (Besplatno)**.
- Adresa: *Suman d.o.o. Zagreb, Hrvatska*.
- Uputstvo kupcu: Roba se može preuzeti nakon primitka email obavijesti da je narudžba spremna.
#### Za Bosnu i Hercegovinu (`region_ba`):
1. **Standardna brza dostava — Cijela BiH**:
- Cijena: npr. 15,00 KM (besplatno iznad zadanog iznosa).
- Rok isporuke: 24/48h radnim danima.
2. **Lično preuzimanje — Centrala Gračanica**:
- Cijena: **0,00 KM (Besplatno)**.
- Adresa: *Branilaca grada bb, 75320 Gračanica, BiH*.
---
## 3. Kupovina za Pravna Lica (R1 Račun u Checkoutu)
### 3.1. Checkout Korak: Podaci o Kupcu i Računu
U komponentu `ShippingAddress` i `BillingAddress` na checkoutu dodaje se:
```
[ ] Kupujem kao pravna osoba / Trebam R1 račun za firmu
--------------------------------------------------------
(Ako je označeno, otvaraju se polja):
* Naziv tvrtke / obrta: [ ]
* OIB (Hrvatska): [ 11 cifara ] (za shop.suman.hr)
* JIB / PDV broj (BiH): [ 13 cifara / 12 cifara ] (za shop.suman.ba)
* Ime i prezime kontakt osobe: [ ]
```
### 3.2. Validacija OIB-a (Hrvatska)
Implementirati matematičku validaciju OIB-a prema standardu **ISO 7064 (MOD 11, 10)**:
- Tačno 11 brojčanih znakova.
- Kontrolna cifra se provjerava prije nastavka checkouta.
- Ako OIB nije ispravan, kupac dobija jasnu poruku: *"Uneseni OIB nije valjan. Molimo provjerite unos."*
### 3.3. Pohrana u Bazi (`Order Metadata`)
Podaci o firmi se spremaju u `order.metadata`:
```json
{
"is_business_order": true,
"company_name": "Ugostiteljstvo d.o.o.",
"tax_id": "12345678901",
"tax_id_type": "OIB",
"vat_rate": 0.25,
"pickup_location": "Zagreb DC"
}
```
---
## 4. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/backend/
├── src/
│ ├── scripts/setup-shipping-zones.ts # Kreiranje zona Kopno, Otoci, Zagreb, Gračanica
│ └── workflows/validate-tax-id.ts # Validacija OIB / JIB
apps/suman-hrvatska/ & apps/suman-bosna/
├── src/
│ ├── lib/util/oib-validator.ts # Algoritam za validaciju OIB-a
│ ├── modules/checkout/
│ │ ├── components/
│ │ │ ├── addresses/index.tsx # R1 checkbox i polja za firmu
│ │ │ ├── shipping/index.tsx # Prikaz zona i ličnog preuzimanja
│ │ │ └── review/index.tsx # Prikaz podataka za R1 račun
│ │ └── templates/checkout-summary/index.tsx # Prikaz PDV-a i dostave
```
---
## 5. Kriteriji Uspješnosti (DoD)
1. Kupac u Hrvatskoj može odabrati dostavu na Kopno, Otoke ili besplatno preuzimanje u Zagrebu.
2. Kupac u BiH može odabrati dostavu u BiH ili besplatno preuzimanje u Gračanici.
3. Označavanjem opcije za R1 račun otvaraju se polja za firmu i OIB/JIB.
4. Neispravan OIB zaustavlja prelazak na plaćanje uz jasnu poruku greške.
5. Na potvrdi narudžbe i u emailu jasno su ispisani podaci firme, OIB, odabrana zona i iznos PDV-a.

View File

@@ -0,0 +1,81 @@
# Faza 05: Načini Plaćanja (Kartice, Pouzeće i Virman)
**Referenca ugovora:** Tačka 10 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
U skladu sa ugovorom, kupcima na oba webshopa moraju biti omogućena tri ravnopravna načina plaćanja:
1. **Kartično online plaćanje (Kreditne i debitne kartice)**: Integracija jednog platnog procesora (Monri WebPay, CorvusPay, WSPay ili Stripe) sa 3D Secure 2.0 zaštitom.
2. **Plaćanje pouzećem (Gotovinom kuriru pri preuzimanju)**: Uključeno bez dodatnog troška.
3. **Plaćanje uplatom na račun (Virman / Opća uplatnica)**: Uključeno bez dodatnog troška, od izuzetnog značaja za pravna lica (B2B).
---
## 2. Implementacija Načina Plaćanja
### 2.1. Plaćanje Uplatom na Račun (Virman / Transakcijski Račun)
Kada kupac odabere *"Uplata na račun / Virmansko plaćanje"*:
- Narudžba se kreira sa statusom plaćanja `awaiting_payment`.
- Na ekranu potvrde i u automatskom emailu kupac dobija generisane podatke za uplatu:
- **Za Hrvatsku (`shop.suman.hr`)**:
- Primalac: *Suman d.o.o., Zagreb*
- IBAN: *HR... (račun u EUR)*
- Model i poziv na broj: *HR01 {broj_narudžbe}*
- Iznos: *{ukupno_eur} €*
- Opis plaćanja: *Narudžba suncobrana br. {broj_narudžbe}*
- **Za Bosnu i Hercegovinu (`shop.suman.ba`)**:
- Primalac: *„SUMAN“ d.o.o. Gračanica*
- Transakcijski račun: *161... (BAM / KM)*
- Poziv na broj: *{broj_narudžbe}*
- Iznos: *{ukupno_km} KM*
### 2.2. Plaćanje Pouzećem (Gotovina pri Preuzimanju)
- Za kupce koji žele platiti kuriru prilikom dostave.
- Narudžba se kreira sa statusom plaćanja `pending_cod`.
- Na potvrdi se ispisuje napomena: *"Pripremite tačan iznos gotovine za kurirsku službu prilikom preuzimanja pošiljke."*
### 2.3. Kartični Platni Procesor (Online Plaćanje)
- Kreira se Medusa Payment Provider modul:
`apps/backend/src/modules/payment-gateway/`
- Podržava standardni tok:
1. `initiatePayment`: Kreira sesiju plaćanja sa iznosom, valutom i ID-em korpe.
2. `authorizePayment`: Preusmjerava na formu procesora ili ugrađeni 3DS modal.
3. Webhook endpoint `POST /store/payment-webhook` koji prima obavijest od procesora i automatski označava narudžbu kao `captured` (plaćena).
> [!NOTE]
> **Preporuka za procesor:** Ukoliko Suman posluje u HR i BiH, **Monri Payments** je regionalni lider sa direktnom podrškom za banke u obje države, ili **CorvusPay** / **WSPay** za tržište Hrvatske.
---
## 3. Email Notifikacije Kupcima
Koristi se ugrađeni notification modul sa predlošcima:
1. **Potvrda narudžbe**: Detaljna specifikacija konfigurisanog suncobrana, slika, rok isporuke i instrukcije za uplatu.
2. **Narudžba u proizvodnji / nabavi**: Obavijest kupcu da je izrada počela.
3. **Narudžba spremna za isporuku / preuzimanje**: Sadrži broj pošiljke (tracking) ili lokaciju skladišta za preuzimanje.
---
## 4. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/backend/
├── src/
│ ├── modules/payment/
│ │ ├── bank-transfer-provider.ts # Virman / uplatnica
│ │ ├── cash-on-delivery-provider.ts # Pouzeće
│ │ └── card-payment-provider.ts # Kartični gateway (Monri/Corvus/Stripe)
│ └── subscribers/order-placed-mailer.ts # Slanje potvrde i uplatnice
apps/suman-hrvatska/ & apps/suman-bosna/
├── src/
│ ├── modules/checkout/components/payment/index.tsx
│ └── modules/order/templates/order-completed-template.tsx
```
---
## 5. Kriteriji Uspješnosti (DoD)
1. Kupac u checkoutu može odabrati: Karticu, Pouzeće ili Uplatu na račun.
2. Odabirom uplate na račun, kupac odmah na ekranu i u emailu dobija tačne instrukcije (IBAN/račun, poziv na broj, model).
3. Testna kartična transakcija uspješno prolazi kroz 3DS verifikaciju i narudžba se automatski bilježi kao plaćena u Medusa Adminu.

View File

@@ -0,0 +1,87 @@
# Faza 06: Medusa Admin Proširenja (Nabavni Pregled, Upiti i Izolacija)
**Referenca ugovora:** Tačka 5 i 8 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
1. **Pregled narudžbi za nabavu (Tačka 8)**: Za proizvode koji se rade po narudžbi, nabavnoj službi i proizvodnji Sumana potreban je poseban ekran koji **sabira iste stavke iz svih otvorenih narudžbi po SKU šifri**, uz mogućnost izvoza u Excel/CSV.
2. **Evidencija upita za tende i pergole (Tačka 3 & 4)**: Pregled i obrada pristiglih upita za proizvode na upit unutar Medusa Admina.
3. **Izolacija ovlasti po tržištu (Tačka 5)**: Administrator za Hrvatsku ne smije vidjeti narudžbe iz BiH i obrnuto, dok Glavni administrator ima uvid u sve.
---
## 2. Implementacija Nabavnog Pregleda (Procurement View)
### 2.1. API Ruta: `GET /admin/procurement`
Backend kreira namensku agregacijsku rutu:
`apps/backend/src/api/admin/procurement/route.ts`
- Filtrira narudžbe koje imaju status `U proizvodnji / nabavi`.
- Prolazi kroz sve stavke (`items`) i sabira količine prema `SKU` i konfiguraciji:
- Npr:
- `SUM-PRES-3535-ANT`: 18 komada (Suncobran Prestige 3.5x3.5m antracit)
- `BASE-CONCR-120KG`: 14 komada (Betonske ploče 120kg)
- `COVER-WATERPROOF`: 22 komada (Zaštitne navlake)
- Vraća JSON sa zbirnim podacima i omogućava preuzimanje CSV datoteke (`?format=csv`).
### 2.2. Medusa Admin Custom UI Stranica
Pomoću Medusa Admin SDK-a kreira se nova stranica u meniju:
`apps/backend/src/admin/routes/procurement/page.tsx`
- **Filteri**: Po tržištu (Hrvatska / BiH), po modelu suncobrana, po vremenskom periodu.
- **Tabela zbirnih stavki**: Slika, SKU, Naziv modela, Odabrana konfiguracija, Ukupno naručeno komada, Rok isporuke.
- **Dugme za izvoz**: *"Izvezi u Excel (CSV)"*.
---
## 3. Modul za Upite (Tende i Pergole)
> [!NOTE]
> *Arhitektura data modela, Remote Links i backend servisa za upite definisana je u [FAZA-02.md](./FAZA-02-prodajni-scenariji-i-upiti.md). Ova faza pokriva integraciju uloge i sigurnosnu izolaciju administratorskog pregleda.*
### 3.1. Admin Stranica: `/admin/inquiries`
`apps/backend/src/admin/routes/inquiries/page.tsx`
- Prikazuje sve pristigle upite sa webshopa (`shop.suman.hr` i `shop.suman.ba`).
- Kolone: Datum, Tržište, Kupac (Ime, Email, Telefon), Proizvod (Pergola / Tenda), Dimenzije, Status obrade.
- **Statusi obrade**:
- `Novi upit` (plavo)
- `Kupac kontaktiran` (žuto)
- `Ponuda poslata` (ljubičasto)
- `Završeno / Realizovano` (zeleno)
- `Otkazano` (sivo)
---
## 4. Potpuna Sigurnosna Izolacija Ovlasti po Tržištu
Proširuje se postojeći middleware u `apps/backend/src/api/middlewares.ts`:
1. **Uloge administratora**:
- `super_admin`: Vidi oba prodajna kanala, sve narudžbe, oba skladišta.
- `admin_hr`: `user.metadata.sales_channel_id === "sc_suman_hr"`. Automatski filtrira `/admin/orders`, `/admin/inquiries`, `/admin/procurement` samo na Hrvatsku.
- `admin_ba`: `user.metadata.sales_channel_id === "sc_suman_ba"`. Automatski filtrira podatke samo na Bosnu i Hercegovinu.
2. **Pokušaj pristupa tuđoj narudžbi**: Ako HR administrator pokuša otvoriti narudžbu iz BiH, backend vraća `403 Forbidden`.
---
## 5. Fajlovi koji se Kreiraju / Mijenjaju
```
apps/backend/
├── src/
│ ├── api/
│ │ ├── admin/
│ │ │ ├── procurement/route.ts # Agregacija i CSV export
│ │ │ └── inquiries/route.ts # Pregled i izmjena statusa upita
│ │ └── middlewares.ts # Sigurnosna izolacija po rolama
│ └── admin/
│ └── routes/
│ ├── procurement/page.tsx # UI ekran za nabavku
│ └── inquiries/page.tsx # UI ekran za upite
```
---
## 6. Kriteriji Uspješnosti (DoD)
1. U Medusa Adminu se u bočnom meniju pojavljuju stavke *"Nabavka (Po narudžbi)"* i *"Upiti"*.
2. Klikom na *"Izvezi u Excel"* preuzima se CSV datoteka sa tačno sabranim količinama po SKU šiframa.
3. Upiti poslani sa forme za pergole odmah se prikazuju u listi upita sa statusom *"Novi"*.
4. Administrator iz Hrvatske prijavljen u Admin vidi samo podatke za tržište Hrvatske.

View File

@@ -0,0 +1,75 @@
# Faza 07: Testiranje, Soft Opening i Priprema za Korporativni Web
**Referenca ugovora:** Tačka 14, 19, 22, 23, 24 i 25 (Pojašnjenje ponude 2026-WEB-070 v3.0)
---
## 1. Cilj Faze
1. **Sprovođenje rigorozne check-liste testiranja (Tačka 25)** prije zvanične primopredaje.
2. **Soft Opening HR Webshopa (15. 01. 2027.)**: Puštanje `shop.suman.hr` u rad za prve stvarne narudžbe, uz praćenje rada sistema i brze ispravke.
3. **Korisničko testiranje (UAT) i Primopredaja (do 15. 02. 2027.)**: Zajednički prolazak kroz protokol primopredaje sa SUMAN timom i potpisivanje zapisnika.
4. **Priprema za Fazu 2 (Korporativni web do 31. 03. 2027.)**: Višejezični sajt na 4 jezika (BS, HR, DE, EN).
---
## 2. Checklista Testiranja Cijelog Kupovnog Toka (Tačka 25)
Prije primopredaje, obavezno se prolazi sljedeća verifikacija:
- [ ] **2D Konfiguracija suncobrana**:
- Promjena platna, konstrukcije i postolja ažurira 2D prikaz bez greške.
- Pravila kompatibilnosti onemogućavaju nedozvoljene spojeve.
- Cijena se tačno računa i prenosi u korpu.
- [ ] **Košarica i Checkout**:
- Stavke nose sve odabrane opcije, SKU kod i specifikaciju.
- Miješana korpa (artikli sa zalihe i po narudžbi) ispravno prikazuje rokove isporuke za svaku stavku.
- [ ] **Dostavne zone i preuzimanje**:
- Tačan obračun dostave za HR Kopno, HR Otoci i 0 EUR za Lično preuzimanje u Zagrebu.
- [ ] **Pravna lica (R1 račun)**:
- Validacija OIB-a (11 cifara) u Hrvatskoj; ispravan unos JIB/PDV u BiH.
- Podaci firme ispisani na potvrdi narudžbe.
- [ ] **Plaćanja**:
- Kartično plaćanje testirano stvarnom transakcijom (uz automatski povrat/refund).
- Plaćanje pouzećem uredno evidentirano.
- Plaćanje uplatom na račun generiše tačan IBAN i poziv na broj.
- [ ] **Email obavijesti**:
- Kupac i komercijala odmah dobijaju email potvrde sa slikom i stavkama.
- [ ] **Medusa Admin obrada**:
- Narudžba vidljiva administratoru odgovarajućeg tržišta.
- Zaliha u magacinu (Zagreb ili Gračanica) se automatski umanjuje / rezerviše.
- Promjena statusa (*U proizvodnji → Spremno → Isporučeno*) šalje email kupcu.
- Stavke se sabiraju u Nabavnom pregledu i izvoze u CSV.
- [ ] **Responsivnost i brzina**:
- Testirano na iPhone (Safari), Android (Chrome) i Desktop računarima.
---
## 3. Korporativni Web (Faza 2 — Rok: 31. 03. 2027.)
Nakon što se HR webshop uspješno pusti u rad 15. 02. 2027., pristupa se dovršetku korporativnog weba:
1. **Domene i jezici**:
- `suman.ba`: Bosanski (BS) i Engleski (EN)
- `suman.hr`: Hrvatski (HR) i Njemački (DE)
2. **Sadržaj**:
- Prezentacija kompanije (30+ godina tradicije, reference, proizvodni pogoni u Gračanici, certifikati kvaliteta ISO/CE).
- Katalog svih sistema zaštite od sunca (uključujući zimske bašte, fasadne brisoleje, pergole i tende).
- B2B portal za arhitekte i projektante (DWG / BIM fajlovi).
---
## 4. Održavanje i Sigurnosne Kopije (Hosting & SLA)
Prema Tačkama 22 i 23 ugovora:
- **Server**: Ubuntu Cloud server u EU (2 vCPU, 8 GB RAM, 80 GB NVMe, SSL certifikati).
- **Sigurnosne kopije (Backup)**: Dnevni backup baze i slika na odvojenu lokaciju (čuvanje 30 dana) + sedmični snapshot cijelog servera.
- **SLA rokovi reakcije**:
- Kritičan kvar (webshop ili plaćanje ne rade): reakcija unutar **4 radna sata**, otklanjanje najkasnije **1 radni dan**.
- Visok prioritet: reakcija **1 radni dan**, otklanjanje **3 radna dana**.
---
## 5. Kriteriji Uspješnosti (DoD)
1. 15. 01. 2027. uspješno pokrenut Soft Opening za `shop.suman.hr`.
2. Do 15. 02. 2027. uspješno otklonjene sve uočene greške i potpisan zapisnik o primopredaji.
3. Klijentu predan kompletan Git repozitorij, baza podataka i administratorski pristupi (Tačka 24).

View File

@@ -0,0 +1,33 @@
# Plan Implementacije po Fazama: SUMAN d.o.o. E-Commerce Platforma
**Zasnovano na zvaničnom dokumentu: "Pojašnjenje ponude 2026-WEB-070 v3.0"**
*Prioritet 1: HR Webshop (`shop.suman.hr`) | Rok: 15. 01. 2027. (Soft opening) / 15. 02. 2027. (Primopredaja)*
---
## 📌 Pregled Faza i Roadmap
Implementacija je podijeljena u **7 samostalnih faza**, gdje svaka faza ima definisane ciljeve, fajlove koji se mijenjaju, arhitekturu i kriterije uspješnosti:
| Faza | Naziv Faze | Glavni Fokus | Prioritet & Rok | Dokument |
| :---: | :--- | :--- | :---: | :--- |
| **01** | **HR Webshop & Multi-Channel Sinhronizacija** | Prenos UI dizajna na `suman-hrvatska`, HR jezik, EUR valuta, povezivanje kanala i magacina Zagreb | **Hitno (Faza 1)** | [FAZA-01.md](./FAZA-01-hr-webshop-sinhronizacija.md) |
| **02** | **Tri Prodajna Scenarija & Medusa Modul za Upite** | Novi Medusa v2 modul za upite, widget za označavanje proizvoda na upit, Remote Links sa katalogom/kanalima, forma za tende/pergole | **Visok** | [FAZA-02.md](./FAZA-02-prodajni-scenariji-i-upiti.md) |
| **03** | **Dinamički 2D Konfigurator Suncobrana** | Medusa-driven opcije (boje platna, konstrukcija, stalak, oprema), živi 2D slojeviti preview, pravila kompatibilnosti i direktna kupovina | **Visok (do 01.12.)** | [FAZA-03.md](./FAZA-03-dinamicki-2d-konfigurator-suncobrana.md) |
| **04** | **Dostavne Zone, Preuzimanje i R1 Pravna Lica** | HR Kopno vs Otoci, Lično preuzimanje (Zagreb/Gračanica 0 EUR), R1 checkout (OIB / JIB) i PDV | **Srednji** | [FAZA-04.md](./FAZA-04-dostava-licno-preuzimanje-i-r1-pravna-lica.md) |
| **05** | **Plaćanja: Kartice, Pouzeće i Virman** | Integracija platnog procesora (Monri/Corvus/WSPay/Stripe), Gotovina pri preuzimanju, Virmanska uplatnica sa IBAN podacima | **Srednji (do 20.12.)** | [FAZA-05.md](./FAZA-05-placanja-kartice-virman-pouzece.md) |
| **06** | **Medusa Admin: Nabavka, Upiti i Izolacija** | Zbirni pregled stavki po narudžbi (procurement view) sa CSV izvozom, modul za upite, RBAC prava pristupa | **Srednji** | [FAZA-06.md](./FAZA-06-medusa-admin-nabavka-i-izolacija.md) |
| **07** | **Testiranje, Soft Opening i Korporativni Web** | UAT testiranje stvarnih narudžbi (15. 1.), primopredaja (15. 2.), priprema za Korporativni web (do 31. 3.) | **Krajnji cilj** | [FAZA-07.md](./FAZA-07-testiranje-soft-opening-i-korporativni-web.md) |
---
## 🧭 Ključna Pravila za Sve Faze
1. **Prioritet u razvoju ima `apps/suman-hrvatska` (`shop.suman.hr`)**, a `apps/suman-bosna` (`shop.suman.ba`) je njegova direktna preslika.
2. **2D Konfigurator je 100% dinamičan i responsive**:
- Sve opcije (platna, konstrukcija, postolja, cijene) čitaju se iz Medusa baze. Administratori mogu u svakom trenutku u Medusa Adminu dodati novu boju ili model bez diranja programskog koda.
- Prikaz na mobilnim uređajima i desktopu mora biti besprijekorno responzivan.
3. **Tende i pergole nemaju korpu**:
- Prikazuju se isključivo kao proizvodi "Na upit" sa namjenskim obrascem.
4. **Pravna lica i R1 račun**:
- Checkout mora omogućiti unos Naziva kompanije i OIB-a (11 cifara) za Hrvatsku, odnosno JIB-a i PDV broja za Bosnu i Hercegovinu.

View File

@@ -0,0 +1,58 @@
# Master Plan Implementacije E-Commerce Platforme za Proizvođača Suncobrana
Ovaj master plan detaljno opisuje implementaciju multi-tenant e-commerce platforme bazirane na **Medusa.js (v2)**, **Next.js (App Router)** i **Turborepo** monorepo arhitekturi.
## Osnovni Principi Arhitekture
1. **Pravilo #1 (Maksimalno korištenje zvaničnog ekosistema):**
- Koristi se zvanični `@medusajs/nextjs-starter-template` za oba storefronta bez pisanja korpe, checkouta ili pretrage od nule.
- Koristi se ugrađeni Medusa Admin v2 dashboard proširen isključivo zvaničnim mehanizmima (Admin Widgets i UI Routes).
- **Stroga zabrana izmišljanja UI elemenata**: Sve admin ekstenzije moraju koristiti isključivo zvanični `@medusajs/ui` dizajn sistem i komponente (`Container`, `Heading`, `Text`, `Badge`, `Button`, `Input`, `Textarea`, `Select`, `Table`, `toast`) uz semantičke klase (`bg-ui-bg-base`, `text-ui-fg-subtle`, itd.).
2. **Dva Webshopa iz Jedne Baze:**
- Dva odvojena prodajna kanala (**Sales Channels**): Tržište DE i Tržište AT.
- Dva javna API ključa (**Publishable API Keys**): Svaki vezan za svoj prodajni kanal, čime Medusa automatski filtrira katalog, zalihe i cijene.
- Lokalizacija jezika putem `next-intl` unutar postojećeg Medusa starter template App Routera.
3. **Admin Izolacija:**
- Zadržava se jedan zvanični Medusa Admin.
- Pomoću backend middleware interceptora (`src/api/middlewares.ts`), admin korisnik vezan za `sales_channel_id` vidi isključivo narudžbe i kupce svoje države.
4. **B2B / HoReCa CRM Podaci:**
- Veleprodajni cjenovnici putem Medusinih modula `Customer Groups` i `Price Lists`.
- PIB/OIB, status verifikacije i bilješke agenta spremaju se u nativno `customer.metadata` polje.
- Admin widget na stranici kupca za direktno ažuriranje CRM podataka preko Medusa JS SDK.
- Webhook subscriber na `order.placed` za eksterni CRM (HubSpot / Brevo).
---
## Indeks Faza Implementacije
Plan je podijeljen u 7 detaljno razrađenih faza. Svaka faza posjeduje sopstveni `.md` dokument:
| Faza | Naziv Dokumenta | Opis i Fokus |
| :--- | :--- | :--- |
| **Faza 1** | [`phase-01-infrastructure-and-monorepo.md`](./phase-01-infrastructure-and-monorepo.md) | Docker Compose (Postgres 16, Redis 7), Turborepo struktura, radni prostori, varijable okruženja. |
| **Faza 2** | [`phase-02-multichannel-core-and-seeding.md`](./phase-02-multichannel-core-and-seeding.md) | Prodajni kanali (DE/AT), skladišta (Stock Locations link), Publishable API ključevi, automatizovana seed skripta. |
| **Faza 3** | [`phase-03-admin-isolation-by-country.md`](./phase-03-admin-isolation-by-country.md) | Sigurnosna izolacija admin korisnika po državama putem Medusa HTTP Middleware interceptora bez novog admin panela. |
| **Faza 4** | [`phase-04-crm-b2b-and-admin-widgets.md`](./phase-04-crm-b2b-and-admin-widgets.md) | B2B CRM podaci u `customer.metadata`, Admin UI Widget na stranici kupca (isključivo `@medusajs/ui`), event subscriber za webhook. |
| **Faza 5** | [`phase-05-storefronts-and-next-intl.md`](./phase-05-storefronts-and-next-intl.md) | Dva Next.js storefronta iz monorepoa, povezivanje Publishable API ključeva, integracija `next-intl` rječnika. |
| **Faza 6** | [`phase-06-umbrella-catalog-and-specs.md`](./phase-06-umbrella-catalog-and-specs.md) | Katalog suncobrana: Opcije (Dimenzija, Boja, Konstrukcija), varijante, tehničke specifikacije u `metadata`, B2B Price Lists. |
| **Faza 7** | [`phase-07-testing-verification-and-deployment.md`](./phase-07-testing-verification-and-deployment.md) | Kompletan QA protokol, verifikacija izolacije po kanalima, build i produkcijski deployment pipeline. |
---
## Redoslijed Izvršavanja
```
[Faza 1: Baza i Monorepo]
↓
[Faza 2: Multi-Channel & Seeding]
↓
[Faza 3: Admin Izolacija] ────→ [Faza 4: CRM & Admin Widget]
↓ ↓
[Faza 5: Storefronts & i18n] ──→ [Faza 6: Katalog Suncobrana]
↓
[Faza 7: Testiranje & Produkcija]
```

View File

@@ -0,0 +1,191 @@
# Faza 1: Infrastruktura, Monorepo i Baza Podataka
## 1.1. Svrha i Ciljevi Faze
Cilj prve faze je postavljanje stabilnog, lokalnog i produkcijski orijentisanog razvojnog okruženja. Uspostavlja se baza podataka PostgreSQL 16 i Redis 7 kroz Docker Compose, te konfiguriše Turborepo monorepo koji orkestrira Medusa v2 backend i dva odvojena Next.js storefronta.
---
## 1.2. Zvanični Paketi i Alati
Sistem se oslanja isključivo na provjereni softverski stek:
- **Node.js**: verzija `>= 22.0.0`
- **Package Manager**: `pnpm` (preporučeno) ili `npm` (verzija `>= 10.0.0`)
- **Docker & Docker Compose**: za pokretanje PostgreSQL 16 i Redis 7
- **Turborepo**: verzija `^2.0.0` za orkestraciju monorepo taskova (`dev`, `build`, `lint`)
---
## 1.3. Konfiguracija Baze i Keša (`docker-compose.yml`)
Kreirajte ili ažurirajte datoteku `docker-compose.yml` u korijenu repozitorijuma (`suman-doo/docker-compose.yml`):
```yaml
version: "3.8"
services:
postgres:
image: postgres:16-alpine
container_name: umbrella_postgres
restart: always
environment:
POSTGRES_USER: ${POSTGRES_USER:-medusa_user}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-medusa_password}
POSTGRES_DB: ${POSTGRES_DB:-medusa_umbrella}
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U medusa_user -d medusa_umbrella"]
interval: 5s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
container_name: umbrella_redis
restart: always
ports:
- "6379:6379"
volumes:
- redisdata:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 5s
retries: 5
volumes:
pgdata:
redisdata:
```
---
## 1.4. Turborepo Konfiguracija
### Root `package.json`
U korijenu monorepoa definisani su radni prostori (`workspaces`) i skripte za simultano pokretanje servisa:
```json
{
"name": "umbrella-platform",
"private": true,
"packageManager": "pnpm@9.15.0",
"engines": {
"node": ">=22.0.0"
},
"scripts": {
"dev": "turbo dev",
"build": "turbo build",
"lint": "turbo lint",
"backend:dev": "turbo dev --filter=@dtc/backend",
"backend:seed": "turbo seed --filter=@dtc/backend",
"store-de:dev": "turbo dev --filter=@umbrella/storefront-de",
"store-at:dev": "turbo dev --filter=@umbrella/storefront-at"
},
"devDependencies": {
"prettier": "^3.3.0",
"turbo": "^2.0.14"
},
"workspaces": [
"apps/*"
]
}
```
### Root `turbo.json`
Optimizovana definicija taskova sa cachingom i varijablama okruženja:
```json
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "!.next/cache/**", ".medusa/**", "dist/**"],
"env": [
"DATABASE_URL",
"REDIS_URL",
"MEDUSA_BACKEND_URL",
"NEXT_PUBLIC_MEDUSA_BACKEND_URL",
"NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY"
]
},
"dev": {
"cache": false,
"persistent": true
},
"lint": {
"dependsOn": ["^lint"]
},
"seed": {
"cache": false
}
}
}
```
---
## 1.5. Konfiguracija Backend Okruženja (`apps/backend/.env`)
U datoteci `apps/backend/.env` definisani su konekcioni stringovi i sigurnosni tokeni:
```env
# Port na kojem se izvršava Medusa v2 Backend i Admin
PORT=9000
# Baza podataka (PostgreSQL 16)
DATABASE_URL=postgres://medusa_user:medusa_password@localhost:5432/medusa_umbrella
# Redis za Event Bus i Keširanje sesija
REDIS_URL=redis://localhost:6379
# JWT i Cookie Tajne (Za produkciju generisati jake ključeve sa: openssl rand -base64 32)
JWT_SECRET=super_secret_jwt_key_suncobrani_2026_production_grade
COOKIE_SECRET=super_secret_cookie_key_suncobrani_2026_production_grade
# CORS Konfiguracija - dozvola pristupa za Admin i oba Storefronta
STORE_CORS=http://localhost:8000,http://localhost:8001
ADMIN_CORS=http://localhost:9000,http://localhost:7001
AUTH_CORS=http://localhost:9000,http://localhost:8000,http://localhost:8001
# Eksterni CRM Webhook (HubSpot / Brevo)
CRM_WEBHOOK_URL=https://api.hubspot.com/v1/webhook/umbrella-orders
CRM_API_KEY=pat-eu1-dummy-key-for-crm-sync
```
---
## 1.6. Korak-po-Korak Instrukcije za Izvršavanje
1. **Pokretanje Docker kontejnera:**
```bash
docker compose up -d
```
2. **Provjera statusa kontejnera:**
```bash
docker compose ps
```
*Oba servisa (`umbrella_postgres` i `umbrella_redis`) moraju imati status `healthy` ili `running`.*
3. **Instalacija zavisnosti u monorepou:**
```bash
pnpm install
```
4. **Pokretanje migracija na backendu:**
```bash
cd apps/backend
npx medusa db:migrate
```
---
## 1.7. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] PostgreSQL kontejner uspješno odgovara na portu `5432` i baza `medusa_umbrella` je kreirana.
- [ ] Redis kontejner uspješno odgovara na komandu `redis-cli ping` sa `PONG`.
- [ ] Medusa v2 migracije (`npx medusa db:migrate`) prolaze sa izlaznim kodom `0` bez grešaka.
- [ ] Turborepo komanda `pnpm dev` uspješno detektuje radne prostore u `apps/*`.

View File

@@ -0,0 +1,245 @@
# Faza 2: Backend Arhitektura, Sales Channels i Automatizovani Seeding
## 2.1. Svrha i Ciljevi Faze
U ovoj fazi se postavlja temelj multi-tenant arhitekture u Medusa v2 backendu bez pisanja custom baza podataka.
Medusa v2 koristi **Multichannel** koncept gdje svaki webshop predstavlja jedan **Sales Channel** povezan sa sopstvenim skladištem (**Stock Location**) i autentifikovan putem jedinstvenog javnog ključa (**Publishable API Key**).
> [!CRITICAL]
> **Prevencija "Out of Stock" blokade:** U Medusa v2, ukoliko prodajni kanal nije eksplicitno povezan sa barem jednom skladišnom lokacijom putem Remote Link mehanizma (`Modules.STOCK_LOCATION` <-> `Modules.SALES_CHANNEL`), svi artikli na storefrontu će imati status "Out of stock" i neće se moći dodati u korpu.
---
## 2.2. Zvanični Moduli i Workflows
U ovoj fazi se koriste isključivo gotovi servisi i workflows iz Medusa v2 jezgra:
- `createSalesChannelsWorkflow` iz `@medusajs/medusa/core-flows`
- `createStockLocationsWorkflow` iz `@medusajs/medusa/core-flows`
- `createApiKeysWorkflow` & `linkSalesChannelsToApiKeyWorkflow` iz `@medusajs/medusa/core-flows`
- `createCustomerGroupsWorkflow` iz `@medusajs/medusa/core-flows`
- `createUserWorkflow` iz `@medusajs/medusa/core-flows`
- `createProductsWorkflow` iz `@medusajs/medusa/core-flows`
- `ContainerRegistrationKeys.REMOTE_LINK` za povezivanje modula
---
## 2.3. Izvršna Skripta za Inicijalizaciju (`setup-umbrella-platform.ts`)
Kreirajte datoteku `apps/backend/src/scripts/setup-umbrella-platform.ts`:
```typescript
import { ExecArgs } from "@medusajs/framework/types"
import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
import {
createSalesChannelsWorkflow,
createStockLocationsWorkflow,
linkSalesChannelsToApiKeyWorkflow,
createApiKeysWorkflow,
createCustomerGroupsWorkflow,
createProductsWorkflow,
createUserWorkflow,
} from "@medusajs/medusa/core-flows"
export default async function setupUmbrellaPlatform({ container }: ExecArgs) {
const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
logger.info("==================================================")
logger.info("Pokrećem automatizovano postavljanje platforme...")
logger.info("==================================================")
// 1. KREIRANJE DVA PRODAJNA KANALA (Sales Channels)
const { result: salesChannels } = await createSalesChannelsWorkflow(container).run({
input: {
salesChannelsData: [
{
name: "Suncobrani DE (Njemačka)",
description: "Zvanični prodajni kanal za njemačko tržište",
},
{
name: "Suncobrani AT (Austrija)",
description: "Zvanični prodajni kanal za austrijsko tržište",
},
],
},
})
const [channelDE, channelAT] = salesChannels
logger.info(`Kreiran kanal DE: ${channelDE.name} [ID: ${channelDE.id}]`)
logger.info(`Kreiran kanal AT: ${channelAT.name} [ID: ${channelAT.id}]`)
// 2. KREIRANJE SKLADIŠNIH LOKACIJA (Stock Locations)
const { result: stockLocations } = await createStockLocationsWorkflow(container).run({
input: {
locations: [
{ name: "Centralni Magacin Minhen (DE)" },
{ name: "Distributivni Centar Beč (AT)" },
],
},
})
const [locDE, locAT] = stockLocations
logger.info(`Kreirana lokacija DE: ${locDE.name} [ID: ${locDE.id}]`)
logger.info(`Kreirana lokacija AT: ${locAT.name} [ID: ${locAT.id}]`)
// 3. POVEZIVANJE SKLADIŠTA SA PRODAJNIM KANALIMA (Remote Link)
const remoteLink = container.resolve(ContainerRegistrationKeys.REMOTE_LINK)
await remoteLink.create([
{
[Modules.STOCK_LOCATION]: { stock_location_id: locDE.id },
[Modules.SALES_CHANNEL]: { sales_channel_id: channelDE.id },
},
{
[Modules.STOCK_LOCATION]: { stock_location_id: locAT.id },
[Modules.SALES_CHANNEL]: { sales_channel_id: channelAT.id },
},
])
logger.info("Uspješno povezana skladišta sa prodajnim kanalima.")
// 4. KREIRANJE PUBLISHABLE API KLJUČEVA I DODJELA KANALIMA
const { result: apiKeys } = await createApiKeysWorkflow(container).run({
input: {
api_keys: [
{ title: "Storefront DE Public Key", type: "publishable" },
{ title: "Storefront AT Public Key", type: "publishable" },
],
},
})
const [keyDE, keyAT] = apiKeys
await linkSalesChannelsToApiKeyWorkflow(container).run({
input: {
id: keyDE.id,
add: [channelDE.id],
},
})
await linkSalesChannelsToApiKeyWorkflow(container).run({
input: {
id: keyAT.id,
add: [channelAT.id],
},
})
// 5. KREIRANJE B2B CUSTOMER GRUPE (Za HoReCa kupce)
const { result: customerGroups } = await createCustomerGroupsWorkflow(container).run({
input: {
customerGroupsData: [
{
name: "HoReCa B2B Partneri",
metadata: {
description: "Verifikovani hoteli, restorani i kafići sa veleprodajnim cijenama",
},
},
],
},
})
logger.info(`Kreirana B2B grupa: ${customerGroups[0].name} [ID: ${customerGroups[0].id}]`)
// 6. KREIRANJE REGIONALNIH ADMIN KORISNIKA SA IZOLACIJOM
await createUserWorkflow(container).run({
input: {
userData: {
email: "admin.de@suncobrani.com",
first_name: "Klaus",
last_name: "Schmidt (DE Admin)",
metadata: { sales_channel_id: channelDE.id },
},
},
})
await createUserWorkflow(container).run({
input: {
userData: {
email: "admin.at@suncobrani.com",
first_name: "Stefan",
last_name: "Weber (AT Admin)",
metadata: { sales_channel_id: channelAT.id },
},
},
})
logger.info("Kreirani regionalni admin nalozi.")
// 7. SEED PRIMJERA SUNCOBRANA SA METADATA SPECIFIKACIJAMA
await createProductsWorkflow(container).run({
input: {
products: [
{
title: "Teleskopski Ugostiteljski Suncobran 'Gastro Master'",
subtitle: "Ekstremno otporan na vjetar sa integrisanim teleskopskim zatvaranjem iznad stolova",
handle: "gastro-master-suncobran",
status: "published",
sales_channels: [{ id: channelDE.id }, { id: channelAT.id }],
metadata: {
uv_protection: "UPF 50+ (EN 13758-1 standard)",
wind_resistance: "Klasa 6 Beaufort (do 60 km/h u otvorenom stanju)",
fabric_weight: "320 g/m² 100% obojeni akril sa Nano-teflon zaštitom",
water_column: "1200 mm",
mast_diameter: "Ø 60 mm debljina stijenke 3.5 mm ojačani aluminijum",
warranty_years: "5 godina garancije na mehanizam i postojanost boje",
},
options: [
{ title: "Dimenzija", values: ["3x3m", "4x4m"] },
{ title: "Boja platna", values: ["Antracit Siva (RAL 7016)", "Prirodna Bež"] },
],
variants: [
{
title: "3x3m / Antracit Siva",
sku: "GM-33-ANT",
options: { Dimenzija: "3x3m", "Boja platna": "Antracit Siva (RAL 7016)" },
prices: [{ currency_code: "eur", amount: 550.00 }],
},
{
title: "4x4m / Antracit Siva",
sku: "GM-44-ANT",
options: { Dimenzija: "4x4m", "Boja platna": "Antracit Siva (RAL 7016)" },
prices: [{ currency_code: "eur", amount: 790.00 }],
},
{
title: "3x3m / Prirodna Bež",
sku: "GM-33-BEZ",
options: { Dimenzija: "3x3m", "Boja platna": "Prirodna Bež" },
prices: [{ currency_code: "eur", amount: 550.00 }],
},
{
title: "4x4m / Prirodna Bež",
sku: "GM-44-BEZ",
options: { Dimenzija: "4x4m", "Boja platna": "Prirodna Bež" },
prices: [{ currency_code: "eur", amount: 790.00 }],
},
],
},
],
},
})
logger.info("==================================================")
logger.info("KONFIGURACIJA ZA VAŠE STOREFRONT .ENV FAJLOVE:")
logger.info(`Kanal DE Publishable Key: ${keyDE.token}`)
logger.info(`Kanal AT Publishable Key: ${keyAT.token}`)
logger.info("==================================================")
}
```
---
## 2.4. Korak-po-Korak Instrukcije za Izvršavanje
1. Pokrenite Medusa backend razvojni server ukoliko nije pokrenut:
```bash
pnpm backend:dev
```
2. U zasebnom terminalu unutar `apps/backend` pokrenite skriptu:
```bash
cd apps/backend
npx medusa exec ./src/scripts/setup-umbrella-platform.ts
```
3. Kopirajte generisane tokene ključeva (`pk_...`) koji će biti ispisani u konzoli u `.env` datoteke storefrontova.
---
## 2.5. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Skripta se uspješno izvršava bez grešaka i ispisuje dva različita tokena ključeva.
- [ ] Izvršavanjem cURL komande sa ključem DE:
```bash
curl -H "x-publishable-api-key: <KEY_DE>" http://localhost:9000/store/products
```
vraća se proizvod "Gastro Master".
- [ ] Skladišta su mapirana na odgovarajuće kanale i varijante nisu označene kao "Out of stock".

View File

@@ -0,0 +1,163 @@
# Faza 3: Admin Izolacija po Državama (Backend Middleware Interceptor)
## 3.1. Svrha i Ciljevi Faze
Zvanični Medusa Admin v2 je zamišljen kao centralizovani panel sa globalnim uvidom u sve podatke.
Cilj ove faze je implementacija **potpune izolacije podataka po državama** bez pravljenja novog admin panela ili račvanja (forkovanja) koda zvaničnog dashboarda.
Rješenje se implementira na backend nivou kroz **Medusa HTTP Middleware Interceptore** koji presreću administratorske API zahtjeve i filtriraju narudžbe i kupce prema prodajnom kanalu dodijeljenom ulogovanom korisniku.
---
## 3.2. Sigurnosna Arhitektura
```
[Admin Korisnik (Klaus - DE Admin)]
↓
[Zahtjev: GET /admin/orders]
↓
[Medusa Autentifikacija: Session / Bearer Token]
↓
[Custom Middleware: isolateSalesChannelMiddleware]
├── Provjerava req.auth_context.actor_id
├── Učitava user.metadata.sales_channel_id
├── Ako postoji restricirani ID:
│ ├── GET /admin/orders → Injektuje req.query.sales_channel_id = [id]
│ └── GET /admin/orders/:id → Ako narudžba ne pripada kanalu → 403 Forbidden
└── Ako je null (Super Admin) → Propušta zahtjev bez izmjena
↓
[Medusa Core API Handler] → [Vraća samo narudžbe za DE]
```
---
## 3.3. Implementacija Middleware Interceptora
Uredite ili kreirajte datoteku `apps/backend/src/api/middlewares.ts`:
```typescript
import {
defineMiddlewares,
AuthenticatedMedusaRequest,
MedusaResponse,
MedusaNextFunction,
} from "@medusajs/framework/http"
import { ContainerRegistrationKeys, MedusaError } from "@medusajs/framework/utils"
/**
* Middleware koji provjerava da li admin korisnik ima restrikciju
* na specifičan prodajni kanal i nameće filtriranje.
*/
async function enforceAdminSalesChannelIsolation(
req: AuthenticatedMedusaRequest,
res: MedusaResponse,
next: MedusaNextFunction
) {
const userId = req.auth_context?.actor_id
// Ako korisnik nije autentifikovan, standardni guard će ga odbiti
if (!userId) {
return next()
}
const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
// 1. Dobavljanje korisničkih metapodataka
const {
data: [user],
} = await query.graph({
entity: "user",
fields: ["id", "metadata"],
filters: { id: userId },
})
const restrictedChannelId = user?.metadata?.sales_channel_id as string | undefined
// Ako korisnik ima dodijeljen prodajni kanal (Regionalni Admin)
if (restrictedChannelId) {
// A) Zahtjev za listu narudžbi (GET /admin/orders)
if (req.method === "GET" && !req.params.id) {
// Forsiramo filtriranje po sales channelu
req.query.sales_channel_id = [restrictedChannelId]
}
// B) Zahtjev za pojedinačnu narudžbu (GET /admin/orders/:id)
if (req.method === "GET" && req.params.id) {
const {
data: [order],
} = await query.graph({
entity: "order",
fields: ["id", "sales_channel_id"],
filters: { id: req.params.id },
})
if (order && order.sales_channel_id !== restrictedChannelId) {
throw new MedusaError(
MedusaError.Types.NOT_ALLOWED,
"Zabranjen pristup: Nemate ovlaštenje za pregled narudžbi iz ovog prodajnog kanala."
)
}
}
}
// Super Admini (bez sales_channel_id u metadata) vide sve narudžbe
return next()
}
export default defineMiddlewares({
routes: [
{
matcher: "/admin/orders*",
method: ["GET"],
middlewares: [enforceAdminSalesChannelIsolation],
},
],
})
```
---
## 3.4. Dodjela i Ažuriranje Kanala Korisnicima u Bazi
Regionalnom adminu se kanal može dodijeliti programski ili kroz skriptu `setup-umbrella-platform.ts`. Ukoliko želite postojećem korisniku dodijeliti ili promijeniti kanal, koristi se zvanični `updateUserWorkflow`:
```typescript
// Primjer skripte za dodjelu kanala korisniku:
await updateUserWorkflow(container).run({
input: {
id: "usr_01J...",
user: {
metadata: {
sales_channel_id: "sc_germany_01J...",
},
},
},
})
```
---
## 3.5. Korak-po-Korak Testiranje i Verifikacija
1. **Kreirajte dvije testne narudžbe:**
- Jednu narudžbu preko Storefronta DE (kanal `channelDE.id`).
- Drugu narudžbu preko Storefronta AT (kanal `channelAT.id`).
2. **Prijavite se u Medusa Admin (`http://localhost:9000/app`) sa nalogom `admin.de@suncobrani.com`:**
- Otvorite sekciju **Orders**.
- **Provjera 1:** U tabeli narudžbi se prikazuje isključivo narudžba iz Njemačke. Narudžba iz Austrije se uopšte ne pojavljuje.
3. **Pokušaj direktnog pristupa austrijskoj narudžbi preko URL-a:**
- U browseru unesite direktan link austrijske narudžbe: `http://localhost:9000/app/orders/order_austria_id`.
- **Provjera 2:** Backend odbija zahtjev sa statusom `403 NOT_ALLOWED` i porukom o zabrani pristupa.
4. **Prijavite se sa nalogom Super Admina:**
- Otvorite **Orders**.
- **Provjera 3:** Super Admin vidi narudžbe iz obje države.
---
## 3.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Middleware se uspješno kompajlira bez TypeScript grešaka (`pnpm --filter @dtc/backend build`).
- [ ] Regionalni admin Njemačke ne može vidjeti listu narudžbi niti detalje pojedinačne narudžbe iz Austrije.
- [ ] Zvanični Medusa Admin interfejs ostaje netaknut i stabilan (nema grešaka u konzoli niti rušenja aplikacije).

View File

@@ -0,0 +1,323 @@
# Faza 4: CRM Ekstenzije za Kupce i B2B Integracija (Isključivo Medusa UI)
## 4.1. Svrha i Ciljevi Faze
Za poslovanje sa ugostiteljima (HoReCa sektor - restorani, hoteli, kafići) potrebno je evidentirati specifične B2B podatke:
- Naziv pravnog lica / firme
- PIB / OIB / PDV broj
- Status B2B verifikacije (`pending`, `verified`, `rejected`)
- Interne bilješke prodajnog agenta (dogovoreni rabati, kontakt na lokaciji, itd.)
Kako se ne bi mijenjale osnovne tabele baze podataka ili pisala custom rješenja, ovi podaci se pohranjuju u standardno Medusino polje `metadata` na entitetu `Customer`.
> [!IMPORTANT]
> **Strogo pravilo za Admin UI:** Zabranjeno je uvođenje bilo kakvih nestandardnih ili izmišljenih UI komponenti i stilova. Widget se gradi **isključivo** pomoću zvaničnih komponenti iz paketa `@medusajs/ui` (`Container`, `Heading`, `Text`, `Badge`, `Button`, `Input`, `Textarea`, `Select`, `toast`) i `@medusajs/admin-sdk`, prateći zvanične semantičke klase Medusa dizajn sistema (`text-ui-fg-subtle`, `divide-ui-border-base`).
---
## 4.2. Arhitektura Admin SDK Klijenta
U Medusa v2 admin ekstenzijama **nikada se ne koristi obični `fetch()`**, jer ne posjeduje administratorske sesijske kolačiće i autorizacijska zaglavlja. Koristi se zvanični `@medusajs/js-sdk`.
Kreirajte datoteku `apps/backend/src/admin/lib/client.ts`:
```typescript
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
debug: import.meta.env.DEV,
auth: {
type: "session",
},
})
```
---
## 4.3. Implementacija CRM Widgeta na Stranici Kupca
Widget se injektuje u zonu detalja kupca (`customer.details`). Koristi ugrađene Medusa UI komponente i `@tanstack/react-query` za perzistenciju i osvježavanje keša.
Kreirajte datoteku `apps/backend/src/admin/widgets/customer-crm-widget.tsx`:
```tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
import {
Container,
Heading,
Text,
Button,
Input,
Textarea,
Select,
Badge,
toast,
} from "@medusajs/ui"
import { useMutation, useQueryClient } from "@tanstack/react-query"
import { useState } from "react"
import { sdk } from "../lib/client"
type CustomerMetadata = {
pib?: string
company_name?: string
verification_status?: "pending" | "verified" | "rejected"
agent_notes?: string
}
const CustomerCrmWidget = ({ data: customer }: DetailWidgetProps<HttpTypes.AdminCustomer>) => {
const queryClient = useQueryClient()
const metadata = (customer.metadata || {}) as CustomerMetadata
// Lokalno stanje forme inicijalizovano iz postojećeg metadata objekta
const [companyName, setCompanyName] = useState<string>(metadata.company_name || "")
const [pib, setPib] = useState<string>(metadata.pib || "")
const [status, setStatus] = useState<string>(metadata.verification_status || "pending")
const [notes, setNotes] = useState<string>(metadata.agent_notes || "")
// Zvanična Medusa SDK mutacija za ažuriranje kupca
const updateCustomerMutation = useMutation({
mutationFn: async () => {
return await sdk.admin.customer.update(customer.id, {
metadata: {
...customer.metadata,
company_name: companyName,
pib: pib,
verification_status: status,
agent_notes: notes,
},
})
},
onSuccess: () => {
// Osvježavanje podataka kupca u dashboardu
queryClient.invalidateQueries({ queryKey: ["customer", customer.id] })
toast.success("Uspjeh", {
description: "B2B CRM podaci kupca su uspješno ažurirani.",
})
},
onError: (err: any) => {
toast.error("Greška", {
description: err.message || "Došlo je do greške pri ažuriranju podataka.",
})
},
})
// Boja bedža u skladu sa Medusa UI statusnim bojama
const getBadgeColor = (st: string) => {
switch (st) {
case "verified":
return "green"
case "rejected":
return "red"
default:
return "orange"
}
}
return (
<Container className="p-6 divide-y divide-ui-border-base">
{/* Zaglavlje sekcije */}
<div className="flex items-center justify-between pb-4">
<div>
<Heading level="h2">B2B / CRM Podaci o Kupcu</Heading>
<Text size="small" leading="compact" className="text-ui-fg-subtle">
Podaci o pravnom licu, status verifikacije za veleprodajne cijene i interne bilješke agenta.
</Text>
</div>
<Badge color={getBadgeColor(status)} size="small">
{status.toUpperCase()}
</Badge>
</div>
{/* Forma sa poljima */}
<div className="pt-4 grid grid-cols-2 gap-4">
<div>
<Text size="small" leading="compact" weight="plus" className="mb-1">
Naziv Pravnog Lica / Firme
</Text>
<Input
size="small"
value={companyName}
onChange={(e) => setCompanyName(e.target.value)}
placeholder="Npr. Hotel Dubrovnik d.o.o."
/>
</div>
<div>
<Text size="small" leading="compact" weight="plus" className="mb-1">
PIB / OIB / PDV Broj
</Text>
<Input
size="small"
value={pib}
onChange={(e) => setPib(e.target.value)}
placeholder="Npr. 12345678901"
/>
</div>
<div>
<Text size="small" leading="compact" weight="plus" className="mb-1">
Status B2B Verifikacije
</Text>
<Select value={status} onValueChange={(val) => setStatus(val)} size="small">
<Select.Trigger>
<Select.Value />
</Select.Trigger>
<Select.Content>
<Select.Item value="pending">Na čekanju (Pending)</Select.Item>
<Select.Item value="verified">Verifikovan (B2B Odobren)</Select.Item>
<Select.Item value="rejected">Odbijen (Standardni B2C)</Select.Item>
</Select.Content>
</Select>
</div>
<div className="col-span-2">
<Text size="small" leading="compact" weight="plus" className="mb-1">
Interne Bilješke Agenta (CRM)
</Text>
<Textarea
value={notes}
onChange={(e) => setNotes(e.target.value)}
rows={3}
placeholder="Unesite dogovoreni rabat, kontakt podatke voditelja terase, zahtjeve za brendiranje platna suncobrana..."
/>
</div>
<div className="col-span-2 flex justify-end pt-2">
<Button
size="small"
isLoading={updateCustomerMutation.isPending}
disabled={updateCustomerMutation.isPending}
onClick={() => updateCustomerMutation.mutate()}
>
Sačuvaj CRM Podatke
</Button>
</div>
</div>
</Container>
)
}
// Registracija widgeta na zoni detalja kupca
export const config = defineWidgetConfig({
zone: "customer.details",
})
export default CustomerCrmWidget
```
---
## 4.4. Event Subscriber za CRM Sinkronizaciju (HubSpot / Brevo Webhook)
Kada kupac napravi narudžbu na bilo kojem storefrontu, Medusin Event Bus emituje događaj `order.placed`. Subscriber provjerava da li kupac posjeduje B2B status i automatski prosljeđuje payload na eksterni CRM.
Kreirajte datoteku `apps/backend/src/subscribers/b2b-order-crm.ts`:
```typescript
import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
export default async function b2bOrderCrmHandler({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
const orderService = container.resolve(Modules.ORDER)
const customerService = container.resolve(Modules.CUSTOMER)
try {
const order = await orderService.retrieveOrder(data.id, {
relations: ["customer", "items", "shipping_address"],
})
if (!order.customer_id) {
return
}
const customer = await customerService.retrieveCustomer(order.customer_id)
const metadata = (customer.metadata || {}) as Record<string, any>
// Sinkronizacija se vrši ako je kupac unio podatke o firmi ili ima status verifikacije
const isB2BCustomer = Boolean(metadata.pib || metadata.verification_status === "verified")
if (isB2BCustomer) {
logger.info(`Sinkronizujem B2B narudžbu ${order.id} prema eksternom CRM sistemu...`)
const crmWebhookUrl = process.env.CRM_WEBHOOK_URL
if (!crmWebhookUrl) {
logger.warn("CRM_WEBHOOK_URL nije definisan u .env datoteci.")
return
}
const payload = {
event: "b2b_order_placed",
order_id: order.id,
sales_channel_id: order.sales_channel_id,
total_amount: order.total,
currency_code: order.currency_code,
customer: {
id: customer.id,
email: customer.email,
company_name: metadata.company_name || null,
pib_oib: metadata.pib || null,
verification_status: metadata.verification_status || "pending",
agent_notes: metadata.agent_notes || null,
},
items: order.items.map((item) => ({
title: item.title,
sku: item.variant_sku,
quantity: item.quantity,
unit_price: item.unit_price,
})),
created_at: new Date().toISOString(),
}
const response = await fetch(crmWebhookUrl, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.CRM_API_KEY || ""}`,
},
body: JSON.stringify(payload),
})
if (response.ok) {
logger.info(`B2B narudžba ${order.id} uspješno poslana na CRM webhook.`)
} else {
logger.error(`CRM webhook je vratio status ${response.status}: ${await response.text()}`)
}
}
} catch (error: any) {
logger.error(`Greška u b2bOrderCrmHandler: ${error.message}`)
}
}
export const config: SubscriberConfig = {
event: "order.placed",
}
```
---
## 4.5. Korak-po-Korak Testiranje i Verifikacija
1. **Provjera Widgeta u Medusa Adminu:**
- Otvorite `http://localhost:9000/app` i prijavite se.
- Idite na **Customers** i kliknite na bilo kojeg kupca.
- **Provjera 1:** Na dnu stranice detalja kupca prikazuje se widget **"B2B / CRM Podaci o Kupcu"** sa nativnim Medusa UI stilovima.
- Unesite naziv firme (npr. *Restoran Obala d.o.o.*), PIB (*12345678901*), odaberite status *Verifikovan* i kliknite **Sačuvaj CRM Podatke**.
- **Provjera 2:** Prikazuje se zelena Medusa `toast` notifikacija o uspjehu, a bedž prelazi u zeleni `VERIFIED` status. Osvježite stranicu u browseru — podaci moraju ostati sačuvani.
2. **Provjera CRM Subscribera:**
- Napravite narudžbu sa emailom verifikovanog kupca.
- **Provjera 3:** U terminalu backend servera se ispisuje log: `Sinkronizujem B2B narudžbu ... prema eksternom CRM sistemu...`.
---
## 4.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Widget je izgrađen isključivo sa komponentama `@medusajs/ui` bez eksternih CSS biblioteka.
- [ ] Izmjene na kupcu se spremaju isključivo kroz `sdk.admin.customer.update` u `metadata`.
- [ ] Event subscriber reaguje na `order.placed` i filtrira B2B kupce na osnovu `metadata.pib`.

View File

@@ -0,0 +1,214 @@
# Faza 5: Storefronts - Multi-Storefront i Multi-Language (`next-intl`)
## 5.1. Svrha i Ciljevi Faze
U ovoj fazi se uspostavljaju dva odvojena webshopa:
- **Webshop DE (`apps/storefront-de`)**: Namijenjen tržištu Njemačke (valuta EUR, primarni jezik njemački).
- **Webshop AT (`apps/storefront-at`)**: Namijenjen tržištu Austrije (valuta EUR, primarni jezik njemački, sa specifičnim cijenama i skladištem).
Oba webshopa se baziraju na zvaničnom `@medusajs/nextjs-starter-template`.
> [!IMPORTANT]
> **Pravilo gotovih rješenja:** Strogo je zabranjeno pisati korpu, checkout, korisnički nalog (auth) ili pretragu od nule. Koriste se gotove komponente, server actions i Medusa JS SDK kuke koje dolaze sa zvaničnim starterom.
Svaki storefront dobija svoj `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY`, čime Medusa backend automatski servira samo proizvode, cijene i zalihe vezane za odgovarajući **Sales Channel**.
---
## 5.2. Postavljanje Storefront Aplikacija u Monorepou
Iz korijena monorepoa kloniramo zvanični starter za oba webshopa:
```bash
# Storefront za Njemačku
npx create-next-app -e https://github.com/medusajs/nextjs-starter-template apps/storefront-de
# Storefront za Austriju
npx create-next-app -e https://github.com/medusajs/nextjs-starter-template apps/storefront-at
# Instalacija next-intl paketa u oba storefronta
pnpm --filter @umbrella/storefront-de add next-intl
pnpm --filter @umbrella/storefront-at add next-intl
```
---
## 5.3. Konfiguracija Environment Varijabli
### Storefront DE (`apps/storefront-de/.env.local`)
```env
# Medusa Backend URL
MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
# Publishable API ključ dodijeljen Sales Channelu za Njemačku (dobijen iz Faze 2)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_de_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Podrazumijevana regija za starter
NEXT_PUBLIC_DEFAULT_REGION=de
PORT=8000
```
### Storefront AT (`apps/storefront-at/.env.local`)
```env
# Medusa Backend URL
MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
# Publishable API ključ dodijeljen Sales Channelu za Austriju (dobijen iz Faze 2)
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_at_yyyyyyyyyyyyyyyyyyyyyyyyyyyy
# Podrazumijevana regija za starter
NEXT_PUBLIC_DEFAULT_REGION=at
PORT=8001
```
---
## 5.4. Integracija `next-intl` Multi-Language Sistema
Zvanični starter koristi App Router sa parametrom regije (npr. `/[countryCode]`). Za uvođenje višejezičnosti (npr. njemački i engleski unutar istog webshopa), konfigurišemo `next-intl`:
### 1. Ruting Konfiguracija (`apps/storefront-de/src/i18n/routing.ts`)
```typescript
import { defineRouting } from "next-intl/routing"
import { createNavigation } from "next-intl/navigation"
export const routing = defineRouting({
locales: ["de", "en"],
defaultLocale: "de",
localePrefix: "as-needed",
})
export const { Link, redirect, usePathname, useRouter } = createNavigation(routing)
```
### 2. Request Konfiguracija (`apps/storefront-de/src/i18n/request.ts`)
```typescript
import { getRequestConfig } from "next-intl/server"
import { routing } from "./routing"
export default getRequestConfig(async ({ requestLocale }) => {
let locale = await requestLocale
if (!locale || !routing.locales.includes(locale as any)) {
locale = routing.defaultLocale
}
return {
locale,
messages: (await import(`../../messages/${locale}.json`)).default,
}
})
```
### 3. Rječnici Prevoda (`apps/storefront-de/messages/de.json`)
```json
{
"General": {
"search": "Pretraži suncobrane...",
"cart": "Korpa",
"account": "Moj Račun"
},
"Product": {
"specificationsTitle": "Tehničke Specifikacije Suncobrana",
"uvProtection": "UV Zaštita",
"windResistance": "Otpornost na vjetar",
"fabricWeight": "Gramaža platna",
"waterproof": "Vodoodbojni stub",
"mastDiameter": "Promjer nosivog stuba",
"warranty": "Fabrička garancija",
"inStock": "Dostupno na stanju",
"outOfStock": "Trenutno rasprodano",
"addToCart": "Dodaj u korpu",
"b2bInquiry": "Zatražite B2B / HoReCa ponudu"
}
}
```
### 4. Rječnici Prevoda (`apps/storefront-de/messages/en.json`)
```json
{
"General": {
"search": "Search parasols...",
"cart": "Cart",
"account": "My Account"
},
"Product": {
"specificationsTitle": "Technical Parasol Specifications",
"uvProtection": "UV Protection",
"windResistance": "Wind Resistance",
"fabricWeight": "Fabric Density",
"waterproof": "Water Column",
"mastDiameter": "Mast Diameter",
"warranty": "Manufacturer Warranty",
"inStock": "In Stock",
"outOfStock": "Out of Stock",
"addToCart": "Add to Cart",
"b2bInquiry": "Request B2B / HoReCa Quote"
}
}
```
### 5. Kombinovani Middleware (`apps/storefront-de/src/middleware.ts`)
Povezujemo `next-intl` obradu sa slanjem `x-publishable-api-key` zaglavlja:
```typescript
import { NextRequest, NextResponse } from "next/server"
import createIntlMiddleware from "next-intl/middleware"
import { routing } from "./i18n/routing"
const intlMiddleware = createIntlMiddleware(routing)
export async function middleware(request: NextRequest) {
const { pathname } = request.nextUrl
// Propuštanje statičkih resursa i Next.js internih fajlova
if (
pathname.startsWith("/_next") ||
pathname.startsWith("/api") ||
pathname.includes(".")
) {
return NextResponse.next()
}
// 1. Obrada višejezičnog URL-a
const response = intlMiddleware(request)
// 2. Prosljeđivanje Publishable API ključa Medusa klijentu
const publishableApiKey = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY || ""
response.headers.set("x-publishable-api-key", publishableApiKey)
return response
}
export const config = {
matcher: ["/((?!api|_next|.*\\..*).*)"],
}
```
---
## 5.5. Korak-po-Korak Pokretanje i Testiranje
1. **Pokretanje oba storefronta u paraleli:**
```bash
pnpm dev
```
- Storefront DE se pokreće na `http://localhost:8000`
- Storefront AT se pokreće na `http://localhost:8001`
2. **Provjera kataloga po prodajnom kanalu:**
- Otvorite `http://localhost:8000/de`.
- Proizvodi se učitavaju koristeći njemački prodajni kanal i valutu EUR.
3. **Provjera višejezičnosti:**
- Otvorite `http://localhost:8000/en`.
- Provjerite da li se interfejs prikazuje na engleskom jeziku sa istim proizvodima.
---
## 5.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Oba storefronta se pokreću bez konflikata na definisanim portovima (8000 i 8001).
- [ ] Svaki storefront šalje svoj `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` u zaglavlju svakog zahtjeva prema backendu.
- [ ] `next-intl` omogućava prebacivanje jezika `/de` i `/en` bez gubitka artikala u korpi.
- [ ] Standardni Medusa checkout, login i korpa funkcionišu bez ikakvih modifikacija koda startera.

View File

@@ -0,0 +1,154 @@
# Faza 6: Katalog Suncobrana - Opcije, Varijante i Tehničke Specifikacije
## 6.1. Svrha i Ciljevi Faze
Katalog suncobrana zahtijeva specifičnu strukturu modeliranja podataka koja obuhvata:
1. **Promjenjive opcije (Medusa Product Options & Variants):**
- Dimenzije (npr. *3x3m, 4x4m, Ø 4m*)
- Boja platna (npr. *Antracit Siva, Prirodna Bež, Bordo Crvena*)
- Materijal konstrukcije (npr. *Pojačani Aluminijum RAL 7016, Tikovina*)
- Svaka kombinacija je zaseban `ProductVariant` sa sopstvenim SKU-om, cijenom i zalihama.
2. **Fiksne tehničke specifikacije (Medusa `product.metadata`):**
- Karakteristike koje vrijede za model suncobrana bez obzira na boju (npr. *UV zaštita, otpornost na vjetar po Beaufort skali, vodoodbojnost, garancija*).
3. **B2B Cjenovnici (Medusa Price Lists):**
- Veleprodajne cijene za HoReCa sektor povezane sa `Customer Groups`.
> [!IMPORTANT]
> **Pravilo minimalne intervencije u UI:** Ne mijenjamo postojeći raspored ili elemente zvaničnog startera. Prikaz tehničkih specifikacija dodajemo kao čistu deklarativnu komponentu unutar postojeće stranice proizvoda, oslanjajući se isključivo na `product.metadata`.
---
## 6.2. Model Podataka u Medusa Backend-u
### 1. Opcije i Varijante
U Medusa Adminu (ili kroz našu seed skriptu iz Faze 2), proizvod se kreira sa tri dimenzije opcija:
- **Opcija 1: Dimenzija** → Vrijednosti: `3x3m`, `4x4m`, `Ø 3.5m`
- **Opcija 2: Boja platna** → Vrijednosti: `Antracit Siva`, `Prirodna Bež`, `Bordo Crvena`
- **Opcija 3: Konstrukcija** → Vrijednosti: `Ojačani Aluminijum`, `Tikovina Drvo`
### 2. Tehničke Specifikacije u `product.metadata`
U Medusa Adminu na formi proizvoda (sekcija **Metadata**) unose se ključevi:
```json
{
"uv_protection": "UPF 50+ (blokira preko 99% UV zračenja)",
"wind_resistance": "Klasa 6 Beaufort (izdržava vjetar do 60 km/h)",
"fabric_weight": "320 g/m² 100% spin-obojeni akril / Olefin",
"water_column": "1200 mm (vodeni stub sa teflonskim premazom)",
"mast_diameter": "Ø 60 mm debljina stijenke 3.5 mm ojačani aluminijum",
"warranty_years": "5 godina fabričke garancije na konstrukciju i platno"
}
```
---
## 6.3. Prikaz Specifikacija u Zvaničnom Storefront Starteru
Kreiramo čistu komponentu koja čita ove podatke direktno iz `product.metadata`.
Kreirajte datoteku `apps/storefront-de/src/modules/products/components/product-specs/index.tsx`:
```tsx
import { HttpTypes } from "@medusajs/framework/types"
type ProductSpecsProps = {
product: HttpTypes.StoreProduct
}
type SpecItem = {
label: string
value: string | undefined
}
export default function ProductSpecs({ product }: ProductSpecsProps) {
const metadata = (product.metadata || {}) as Record<string, string | undefined>
const specifications: SpecItem[] = [
{ label: "UV Zaštita", value: metadata.uv_protection },
{ label: "Otpornost na vjetar", value: metadata.wind_resistance },
{ label: "Gramaža i sastav platna", value: metadata.fabric_weight },
{ label: "Vodoodbojnost (stub)", value: metadata.water_column },
{ label: "Nosivi profil (stub)", value: metadata.mast_diameter },
{ label: "Fabrička garancija", value: metadata.warranty_years },
].filter((spec) => Boolean(spec.value))
// Ako proizvod nema tehničke specifikacije u metadata, ne prikazujemo praznu sekciju
if (specifications.length === 0) {
return null
}
return (
<div className="mt-8 border-t border-gray-200 pt-6">
<h3 className="text-base font-semibold text-gray-900 mb-4">
Tehničke Specifikacije Modela
</h3>
<dl className="grid grid-cols-1 gap-x-4 gap-y-4 sm:grid-cols-2">
{specifications.map((spec, index) => (
<div key={index} className="border-b border-gray-100 pb-3">
<dt className="text-xs text-gray-500 font-medium uppercase tracking-wider">
{spec.label}
</dt>
<dd className="mt-1 text-sm font-medium text-gray-900">
{spec.value}
</dd>
</div>
))}
</dl>
</div>
)
}
```
### Uključivanje u Stranicu Proizvoda
U postojećoj datoteci `src/app/[countryCode]/(main)/products/[handle]/page.tsx` unutar zvaničnog startera, dodajte komponentu ispod opisa proizvoda:
```tsx
import ProductSpecs from "@modules/products/components/product-specs"
// ... unutar ProductTemplate komponente:
<ProductInfo product={product} />
<ProductSpecs product={product} />
<ProductActions product={product} region={region} />
```
---
## 6.4. Postavljanje B2B Veleprodajnih Cjenovnika (Price Lists)
Medusa v2 ima ugrađen sistem pravila za cjenovnike koji eliminiše potrebu za pisanjem custom B2B logike:
1. **Kreiranje B2B grupe kupaca:**
- U adminu otvorite **Customers -> Customer Groups**.
- Kreirajte grupu `HoReCa B2B Partneri`.
2. **Kreiranje B2B Cjenovnika:**
- Otvorite **Pricing -> Price Lists** i kliknite **Create Price List**.
- **Title:** `HoReCa Veleprodajni Cjenovnik - DE`.
- **Type:** `Override` (zamjenjuje standardne maloprodajne cijene).
- **Customer Groups Rule:** Odaberite grupu `HoReCa B2B Partneri`.
- **Sales Channel:** Odaberite prodajni kanal `Suncobrani DE`.
- **Unos Cijena:** Za svaki SKU suncobrana unesite ugovorenu veleprodajnu cijenu (npr. umjesto 550.00 EUR unesite 390.00 EUR).
3. **Automatsko Primjenjivanje na Storefrontu:**
- Kada se kupac koji pripada ovoj grupi uloguje na storefrontu, Medusa SDK automatski šalje njegov auth token, a backend vraća B2B cijene u katalogu i u korpi.
---
## 6.5. Korak-po-Korak Testiranje i Verifikacija
1. **Provjera opcija i varijanti:**
- Otvorite proizvod na `http://localhost:8000/de/products/gastro-master-suncobran`.
- Promijenite dimenziju sa *3x3m* na *4x4m*.
- **Provjera 1:** Cijena se automatski mijenja sa 550,00 EUR na 790,00 EUR.
2. **Provjera tehničkih specifikacija:**
- **Provjera 2:** Prikazana je lista specifikacija (UV zaštita UPF 50+, Otpornost na vjetar Klasa 6 Beaufort, itd.).
3. **Provjera B2B cjenovnika:**
- Prijavite se na webshopu sa B2B nalogom koji se nalazi u grupi `HoReCa B2B Partneri`.
- **Provjera 3:** Na istoj stranici cijena suncobrana 3x3m se automatski prikazuje kao 390,00 EUR.
---
## 6.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Sve varijante suncobrana (dimenzija, boja) imaju ispravne cijene i SKU kodove.
- [ ] Tehničke specifikacije iz `product.metadata` se čisto renderuju bez grešaka ako nedostaju pojedinačna polja.
- [ ] B2B kupac dobija veleprodajnu cijenu bez promjene checkout logike.

View File

@@ -0,0 +1,110 @@
# Faza 7: Testiranje, Sigurnosna Verifikacija i Produkcijski Deployment
## 7.1. Svrha i Ciljevi Faze
Završna faza obuhvata rigoroznu verifikaciju svih sistema prije puštanja u rad, provjeru sigurnosnih pravila izolacije podataka, build validaciju monorepoa i pripremu za produkcijski deployment.
---
## 7.2. Detaljna QA Matrica Testiranja
| # | Scenarij Testiranja | Koraci za Testiranje | Očekivani Rezultat | Status |
| :- | :--- | :--- | :--- | :-: |
| **1** | **Multi-Storefront Izolacija Kataloga** | Pozvati `GET /store/products` sa `pk_de` ključem i uporediti sa pozivom preko `pk_at` ključa. | Svaki ključ vraća samo proizvode objavljene na njegovom kanalu i u pripadajućoj valuti. | [ ] |
| **2** | **Provjera Zaliha (Stock Availability)** | Dodati suncobran u korpu na Storefrontu DE i proći korak dostave. | Artikal ima status "In Stock" jer je skladište Minhen povezano sa kanalom DE. | [ ] |
| **3** | **Admin Izolacija Narudžbi (Klaus - DE Admin)** | Prijaviti se u Admin sa `admin.de@suncobrani.com` i otvoriti `/admin/orders`. | Prikazuju se isključivo narudžbe napravljene na njemačkom webshopu. | [ ] |
| **4** | **Zabrana Pristupa Tuđim Narudžbama** | Klaus pokušava otvoriti `GET /admin/orders/{id_austrijske_narudzbe}`. | Backend vraća HTTP status `403 NOT_ALLOWED` uz zabranu pristupa. | [ ] |
| **5** | **Super Admin Pristup** | Prijaviti se sa nalogom super admina (bez `sales_channel_id` u metadata). | Prikazuju se narudžbe iz obje države bez restrikcija. | [ ] |
| **6** | **CRM Widget na Stranici Kupca** | Otvoriti bilo kojeg kupca u Medusa Adminu, unijeti PIB i bilješku agenta, kliknuti Sačuvaj. | Podaci se perzistiraju u `customer.metadata` bez grešaka, prikazuje se success toast. | [ ] |
| **7** | **B2B Webhook Sinkronizacija** | Kreirati narudžbu sa nalogom koji ima popunjen PIB. | Event subscriber reaguje na `order.placed` i uspješno prosljeđuje JSON payload na eksterni CRM webhook. | [ ] |
| **8** | **Multi-Language Rute (`next-intl`)** | Otvoriti `/de/products/gastro-master-suncobran`, zatim promijeniti URL na `/en/...`. | Prikazuju se prevedene oznake specifikacija bez gubitka stanja korpe. | [ ] |
| **9** | **B2B Veleprodajni Cjenovnik** | Prijaviti se sa kupcem iz grupe `HoReCa B2B Partneri`. | Cijene suncobrana se automatski prikazuju sa uračunatim veleprodajnim popustom. | [ ] |
---
## 7.3. Build Validacija Monorepoa
Prije postavljanja na server, cjelokupni monorepo se mora kompajlirati bez ijedne TypeScript ili ESLint greške.
Iz korijena monorepoa pokrenite:
```bash
# 1. Pokretanje lintera za backend i storefrontove
pnpm lint
# 2. Kompajliranje svih aplikacija kroz Turborepo
pnpm build
```
> [!TIP]
> Turborepo će keširati stabilne dijelove aplikacije. Svi paketi u `apps/*` moraju završiti sa statusom `SUCCESS`.
---
## 7.4. Produkcijski Docker Multi-Stage Build
Za produkciju, Medusa backend se pakuje u optimizovani Docker image.
Kreirajte datoteku `apps/backend/Dockerfile`:
```dockerfile
# 1. Faza izgradnje (Build stage)
FROM node:22-alpine AS builder
WORKDIR /app
# Instalacija alata za kompajliranje nativnih modula
RUN apk add --no-cache libc6-compat python3 make g++
COPY package.json pnpm-lock.yaml* ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
# 2. Faza izvršavanja (Production runner stage)
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=9000
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 medusa
COPY --from=builder /app/package.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/.medusa ./.medusa
COPY --from=builder /app/medusa-config.ts ./medusa-config.ts
USER medusa
EXPOSE 9000
CMD ["npx", "medusa", "start"]
```
---
## 7.5. Preporuke za Produkcijski Deployment
1. **Baza Podataka i Keš:**
- Preporučuje se korištenje upravljanih servisa (Managed Database): AWS RDS PostgreSQL 16 ili DigitalOcean Managed PostgreSQL.
- Za Redis: AWS ElastiCache ili Upstash Redis.
2. **Backend Hosting:**
- Medusa Cloud, Railway, AWS ECS ili Kubernetes kontejner.
- Obavezno podesiti automatsko pokretanje migracija: `npx medusa db:migrate` prije pokretanja servisa.
3. **Storefront Hosting:**
- Vercel ili Cloudflare Pages za oba Next.js storefronta (`storefront-de` i `storefront-at`).
- Na Vercelu se svaki storefront postavlja kao zaseban projekat povezan sa odgovarajućim root direktorijumom u monorepou (`apps/storefront-de` i `apps/storefront-at`) sa sopstvenim environment varijablama.
---
## 7.6. Kriterijumi Prihvatljivosti za Produkcijski Release
- [ ] Sve stavke iz QA matrice (1-9) su uspješno verifikovane i označene.
- [ ] Komanda `pnpm build` prolazi sa izlaznim kodom `0`.
- [ ] Svi tajni ključevi (`JWT_SECRET`, `COOKIE_SECRET`, `CRM_API_KEY`) su zamijenjeni kriptografski sigurnim vrijednostima.
- [ ] SSL/TLS certifikati su aktivni na svim domenima.