Files
Suman/docs/implementation-plan/phase-02-multichannel-core-and-seeding.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

246 lines
9.0 KiB
Markdown

# 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".