first commit

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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