medusa-plugin-b2b-sales-agent

Plugin Medusa v2 per la gestione di agenti B2B (dashboard, permessi, API custom).

Obiettivo

• Agenti vedono solo clienti/ordini assegnati.
• Dashboard agenti con KPI, clienti, ordini e bozze.
• Creazione cliente e draft order direttamente dalla dashboard.
• Admin puo' creare agenti e assegnare clienti.

Ruoli e modello dati

Metadati su User:

{
  "role": "sales_agent | admin",
  "assigned_customer_ids": ["cus_..."]
}

• sales_agent: accesso limitato.
• admin: accesso completo + puo' operare per conto di un agente.
• se role non e' presente, fallback = admin.

Flusso operativo (MVP)

1. Admin registra un agente.
2. Admin assegna clienti all'agente.
3. Agente accede a /app/agents e lavora sui propri clienti e ordini.
4. Agente puo' creare clienti e draft orders (assegnati ai suoi clienti).

Admin UI (Dashboard agenti)

• File UI: src/admin/routes/agents/page.jsx
• Menu: voce "Agenti"
• Sezioni principali:
  • KPI (clienti, ordini, fatturato, valori mese)
  • Clienti assegnati (metriche aggregate)
  • Ordini bozza (lista separata)
  • Ordini (non draft)
• Azioni:
  • Crea cliente (assegnato all'agente)
  • Crea ordine bozza (apre dettaglio bozza)

API Admin (custom)

Tutte le route sono protette da authenticate("user").

Autenticazione

Supportate due modalita:

• JWT (Bearer): utile per script/automazioni.
• Cookie di sessione: utile dal browser.

Esempio login JWT:

curl -X POST http://medusajs.localhost/auth/user/emailpass \
  -H "content-type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Esempio chiamata con JWT:

curl -X POST http://medusajs.localhost/admin/agents/register \
  -H "content-type: application/json" \
  -H "authorization: Bearer <JWT>" \
  -d '{"email":"[email protected]","first_name":"Mario","last_name":"Rossi","password":"StrongPass123!","assigned_customer_ids":["cus_..."]}'

POST /admin/agents/register

Crea un agente (solo admin).

{
  "email": "[email protected]",
  "first_name": "Mario",
  "last_name": "Rossi",
  "password": "StrongPass123!",
  "assigned_customer_ids": ["cus_..."]
}

Note:

• imposta metadata.role = "sales_agent".
• se l'email esiste gia', ritorna 409.
• senza password, l'agente non puo' fare login.

POST /admin/agents/:agent_id/assign

Assegna un cliente a un agente (solo admin).

{ "customer_id": "cus_..." }

POST /admin/agents/:agent_id/unassign

Rimuove un cliente da un agente (solo admin).

{ "customer_id": "cus_..." }

GET /admin/agents/dashboard

Statistiche aggregate per l'agente autenticato (o ?agent_id= se admin).

GET /admin/agents/customers

Lista clienti assegnati (o ?agent_id= se admin).

POST /admin/agents/customers

Crea un cliente assegnato all'agente autenticato (solo sales_agent).

{
  "email": "[email protected]",
  "first_name": "Mario",
  "last_name": "Rossi",
  "company_name": "ACME",
  "phone": "+39..."
}

GET /admin/agents/orders

Lista ordini dei clienti assegnati. Query supportate:

• limit, offset
• status
• customer_id
• draft_only=1 (solo bozze)
• include_drafts=1 (include anche bozze)

Risposta include campi utili per UI: payment_status, fulfillment_status, total, created_at, ecc.

Sicurezza (middleware)

File: src/api/middlewares.js

Se l'utente e' sales_agent abilita solo alcune route, tra cui:

• GET /admin/agents/*
• GET /admin/orders
• GET /admin/regions
• GET /admin/price-lists
• GET /admin/sales-channels
• GET /admin/users/me
• GET /admin/stores
• POST /admin/agents/customers
• POST /admin/draft-orders
• POST /admin/draft-orders/:id/convert-to-order

Controlli extra:

• POST /admin/draft-orders: blocca se customer_id non e' assegnato.
• POST /admin/draft-orders/:id/convert-to-order: verifica che la bozza appartenga a un cliente assegnato.

UI agenti (menu limitato)

• File: src/admin/utils/agent-ui.js
• Nasconde voci non consentite e blocca navigazioni non permesse.
• Bootstrap UI: src/admin/widgets/agent-ui-guard.jsx

Percorsi permessi:

• /app/agents
• /app/orders/:id
• /app/draft-orders/:id
• /app/login

Struttura progetto (mappa rapida)

• src/api/admin/agents/_shared.js - helper ruoli/assegnazioni
• src/api/admin/agents/*/route.js - API custom agenti
• src/api/middlewares.js - guard API sales_agent
• src/admin/routes/agents/page.jsx - dashboard agenti
• src/admin/utils/agent-ui.js - menu limitato + guard UI
• src/admin/widgets/agent-ui-guard.jsx - bootstrap UI agente

Sviluppo locale

Da questa cartella:

npx medusa plugin:build

npx medusa plugin:develop

Per i dev (publish + add locale)

Build e publish locale del plugin:

pnpm medusa plugin:publish

Installazione locale nell'app Medusa:

pnpm medusa plugin:add [email protected]

Uso nell'app Medusa

Nel medusa-config.ts dell'app:

plugins: [
  {
    resolve: "../medusa-plugin-b2b-sales-agent",
  },
],

Aggiorna il path se necessario.

Debug rapido

• 403 su API: controlla src/api/middlewares.js.
• Menu completo per agenti: controlla src/admin/utils/agent-ui.js e src/admin/widgets/agent-ui-guard.jsx.
• Problemi con draft order: controlla i guard su POST /admin/draft-orders e convert-to-order.