324 lines
11 KiB
Markdown
324 lines
11 KiB
Markdown
# 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`.
|
|
|