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

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`.