Shipping — Convex Component

Componente Convex per la gestione logistica di spedizioni, consegne, vettori e tracking interno a stati.

Progettato per essere condiviso tra PrimoUpCore (gestionale cliniche) e PrimoLabCore (gestionale laboratorio odontotecnico).

Obiettivo

Fornire un registro operativo logistico con:

• Gestione di mittenti e destinatari (cliniche, laboratori, soggetti esterni)
• Gestione vettori (corrieri API, corrieri manuali, padroncini interni)
• Creazione e tracciamento spedizioni con state machine esplicita
• Timeline eventi per ogni spedizione
• Allegati per spedizione
• Configurazione vettori preferiti per clinica/laboratorio

Non include: integrazione corrieri reali, tracking GPS, calcolo tariffe, generazione etichette, routing intelligente, notifiche.

Concetti di Dominio

| Concetto | Descrizione | |---|---| | LogisticParty | Mittente o destinatario: clinica, laboratorio o soggetto esterno. Supporta externalId opzionale per collegamento con anagrafiche esterne (PrimoUpCore / PrimoLabCore) | | TransportProvider | Chi trasporta: corriere con API, corriere manuale, padroncino interno | | Shipment | La spedizione, con stato, direzione, mittente, destinatario, vettore | | ShipmentEvent | Evento nella timeline della spedizione (creazione, cambio stato, nota...) | | ShipmentAttachment | File allegato alla spedizione (etichetta, documento, foto) | | PreferredProviderConfig | Fino a 3 vettori preferiti per ogni clinica o laboratorio |

Direzioni Spedizione

• outbound — spedizione in uscita
• inbound_expected — spedizione attesa in ingresso
• internal_transfer — trasferimento interno

Stati Spedizione (State Machine)

draft → ready → assigned → picked_up → in_transit → out_for_delivery → delivered
                                    ↘ failed           ↘ delivered
                                                       ↘ failed
Ogni stato può andare in → cancelled (tranne i terminali)
Stati terminali: delivered, failed, cancelled

Tipi Vettore

• external_api — corriere con integrazione API (es. DHL)
• external_manual — corriere senza integrazione (es. BRT)
• internal_driver — padroncino interno/assunto

Struttura Progetto

shipping/
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── README.md
├── src/
│   ├── component/                  # Backend Convex Component
│   │   ├── convex.config.ts        # Definizione componente
│   │   ├── schema.ts               # Schema tabelle (isolato)
│   │   ├── domain/
│   │   │   ├── enums.ts            # Enum e validators condivisi
│   │   │   ├── stateMachine.ts     # State machine transizioni
│   │   │   └── referenceCode.ts    # Generazione codici SHP-XXXXXX
│   │   ├── logisticParties.ts      # CRUD soggetti logistici
│   │   ├── transportProviders.ts   # CRUD vettori
│   │   ├── shipments.ts            # CRUD + logica spedizioni
│   │   ├── shipmentEvents.ts       # Query eventi timeline
│   │   ├── shipmentAttachments.ts  # CRUD allegati
│   │   └── preferredProviders.ts   # Config vettori preferiti
│   ├── client/
│   │   └── index.ts                # API wrapper per app consumatrici
│   └── test.ts                     # Helper per test con convex-test
├── example/
│   ├── convex/
│   │   ├── convex.config.ts        # App config con componente installato
│   │   ├── shipping.ts             # Re-export API pubblica
│   │   └── seed.ts                 # Dati demo
│   ├── src/
│   │   ├── main.tsx                # Entry point React
│   │   ├── App.tsx                 # Router e layout
│   │   ├── App.css                 # Stili
│   │   ├── pages/
│   │   │   ├── Dashboard.tsx       # Lista spedizioni con filtri
│   │   │   ├── CreateShipment.tsx  # Form creazione spedizione
│   │   │   ├── ShipmentDetail.tsx  # Dettaglio + timeline + azioni
│   │   │   ├── LogisticParties.tsx # Gestione soggetti
│   │   │   └── TransportProviders.tsx # Gestione vettori
│   │   └── components/
│   │       ├── StatusBadge.tsx      # Badge stato/tipo
│   │       └── Timeline.tsx         # Timeline eventi
│   ├── index.html
│   └── vite.config.ts

Come Avviare

Prerequisiti

• Node.js 18+
• Account Convex (gratuito su convex.dev)

Installazione

Dalla root del repo (installa anche l’example tramite workspace npm):

cd shipping
npm install

L’example dipende da @primocaredentgroup/shipping via file:.. così gli import restano uguali a un’installazione da npm.

Primo avvio (setup Convex)

Al primo avvio è necessario configurare il progetto Convex:

npx convex dev

Il CLI Convex chiederà di:

1. Fare login (se non già autenticato)
2. Creare un nuovo progetto Convex

Questo genera i file _generated/ e crea .env.local con le credenziali del deployment.

Sviluppo

Dopo il primo setup, avvia tutto con:

npm run dev

Questo comando avvia in parallelo:

1. Convex dev — backend con type-checking dei componenti
2. Vite — frontend example app su http://localhost:5173
3. Build watcher — ricompila il componente ad ogni modifica

Seed Dati Demo

Dopo il primo deploy, esegui il seed per popolare i dati di esempio:

npx convex run seed

Questo crea:

• 4 soggetti logistici (Clinica Torino Centro, Clinica Rivoli, PrimoLab Torino, Studio Esterno Milano)
• 3 vettori (DHL Express, BRT Corriere, Padroncino Mario)
• 8 spedizioni in stati diversi (bozza, assegnata, in transito, attesa in ingresso, consegnata, fallita, annullata, trasferimento interno)

Demo UI

Apri http://localhost:5173 per vedere:

1. Dashboard — lista spedizioni con filtri per stato e direzione
2. Nuova Spedizione — form di creazione completo
3. Dettaglio Spedizione — dati, timeline, azioni cambio stato, assegnazione vettore
4. Soggetti Logistici — CRUD cliniche, laboratori, soggetti esterni
5. Vettori — CRUD vettori con evidenza del tipo

Come Usare in un'App Esistente

1. Installa il componente

Se locale:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import shipping from "../path/to/shipping/dist/component/convex.config.js";

const app = defineApp();
app.use(shipping);
export default app;

2. Re-esporta l'API

// convex/shipping.ts
import { makeShippingAPI } from "@primocaredentgroup/shipping";
import { components } from "./_generated/api.js";

export const {
  listShipments,
  createShipment,
  updateShipmentStatus,
  // ... tutte le funzioni necessarie
} = makeShippingAPI(components.shipping);

3. Usa dal client React

import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

function MyComponent() {
  const shipments = useQuery(api.shipping.listShipments, { status: "in_transit" });
  const create = useMutation(api.shipping.createShipment);
  // ...
}

Regole Funzionali

1. Ogni nuova spedizione genera automaticamente un ShipmentEvent di tipo created
2. Ogni cambio stato genera un ShipmentEvent di tipo status_changed
3. Ogni assegnazione vettore genera un ShipmentEvent di tipo assigned_provider
4. Le transizioni di stato invalide vengono rifiutate con errore esplicito
5. Lo stato assigned richiede un providerId valorizzato
6. Non è possibile assegnare un vettore disattivato (isActive: false)
7. providerId, senderId, recipientId sono opzionali
8. PreferredProviderConfig accetta massimo 3 provider
9. I codici di riferimento seguono il formato SHP-XXXXXX (auto-incrementale)

Possibili Estensioni Future

• Adapter Pattern per corrieri: interfaccia comune per DHL, BRT, GLS con implementazioni specifiche
• Integrazione Sendcloud / ShippyPro: via adapter
• Tracking GPS padroncini: geolocalizzazione real-time
• Notifiche: webhook/email su cambio stato
• Calcolo tariffe: stima costi basata su peso, dimensioni, distanza
• Generazione etichette: PDF con barcode/QR
• Pianificazione giri: routing ottimizzato per padroncini
• Dashboard analytics: statistiche consegne, tempi medi, tassi di fallimento
• Multi-tenant: isolamento dati per clinica/laboratorio
• Webhook in ingresso: ricezione aggiornamenti da corrieri esterni

Pubblicazione su npm

Pacchetto scoped: @primocaredentgroup/shipping. Devi essere membro dell’organizzazione npm primocaredentgroup con permesso di publish.

publishConfig.access è impostato su public (pacchetto visibile e installabile senza login). Se invece deve essere solo per l’azienda (private), rimuovi publishConfig dal package.json root e usa npm publish con un piano npm che supporta pacchetti privati.

npm login
npm publish

Lo script prepublishOnly esegue typecheck e build prima della pubblicazione. Per un controllo senza pubblicare: npm pack --dry-run.