first commit
This commit is contained in:
299
docs/TEHNICKA_DOKUMENTACIJA.md
Normal file
299
docs/TEHNICKA_DOKUMENTACIJA.md
Normal 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.
|
||||
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
179
docs/faze-implementacije/FAZA-02-prodajni-scenariji-i-upiti.md
Normal file
179
docs/faze-implementacije/FAZA-02-prodajni-scenariji-i-upiti.md
Normal 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`.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
33
docs/faze-implementacije/README.md
Normal file
33
docs/faze-implementacije/README.md
Normal 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.
|
||||
|
||||
58
docs/implementation-plan/README.md
Normal file
58
docs/implementation-plan/README.md
Normal 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]
|
||||
```
|
||||
|
||||
191
docs/implementation-plan/phase-01-infrastructure-and-monorepo.md
Normal file
191
docs/implementation-plan/phase-01-infrastructure-and-monorepo.md
Normal 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/*`.
|
||||
|
||||
@@ -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".
|
||||
|
||||
163
docs/implementation-plan/phase-03-admin-isolation-by-country.md
Normal file
163
docs/implementation-plan/phase-03-admin-isolation-by-country.md
Normal 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).
|
||||
|
||||
323
docs/implementation-plan/phase-04-crm-b2b-and-admin-widgets.md
Normal file
323
docs/implementation-plan/phase-04-crm-b2b-and-admin-widgets.md
Normal 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`.
|
||||
|
||||
214
docs/implementation-plan/phase-05-storefronts-and-next-intl.md
Normal file
214
docs/implementation-plan/phase-05-storefronts-and-next-intl.md
Normal 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.
|
||||
|
||||
154
docs/implementation-plan/phase-06-umbrella-catalog-and-specs.md
Normal file
154
docs/implementation-plan/phase-06-umbrella-catalog-and-specs.md
Normal 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user