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

9.0 KiB

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:

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:
    pnpm backend:dev
    
  2. U zasebnom terminalu unutar apps/backend pokrenite skriptu:
    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:
    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".