Files
Suman/docs/implementation-plan/phase-04-crm-b2b-and-admin-widgets.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

11 KiB

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:

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:

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:

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.