first commit
This commit is contained in:
323
docs/implementation-plan/phase-04-crm-b2b-and-admin-widgets.md
Normal file
323
docs/implementation-plan/phase-04-crm-b2b-and-admin-widgets.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# 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`.
|
||||
|
||||
Reference in New Issue
Block a user