Componente Signatures per PrimoUpCore

Convex component per la gestione di firme elettroniche con canali multipli (drawn, stored riusabili, OTP, QR code, link via email).

Pratiche documentali

• Una pratica identifica un solo documento e una sua revisione, con PDF sorgente e hash calcolato dallo storage del componente.
• Ogni firmatario ha uno slot e sessioni individuali; le firme possono avvenire in momenti diversi, in ordine libero o sequenziale.
• Le evidenze legano documento, pratica, slot, sessione, firmatario, canale, blob della firma e timestamp.
• Quando tutti i firmatari obbligatori hanno concluso, il componente applica le firme al PDF e conserva l'artefatto finale con hash e audit di completamento.
• Solo la finalizzazione interna può dichiarare completata una pratica; il Core accede tramite il client tipizzato e applica Auth0/RBAC nei propri wrapper.

Caratteristiche

• Drawn: firma disegnata via canvas (data URL → Convex storage)
• Stored reusable: firma salvata una volta e riutilizzabile (es. firma del medico)
• OTP: verifica via codice OTP (SMS/Email)
• QR code: link tramite QR per firma da altro device
• Email link: link temporaneo via email
• Convex storage: tutte le immagini firma vivono come blob in Convex storage con URL firmati on-demand
• Audit log: tutti gli eventi (creazione sessione, invio link, firma, ecc.) sono tracciati
• Scope-agnostic: il componente non sa chi firma, l'host (PrimoUpCore) gestisce ownership

Struttura progetto

.
├── signatures/             # Componente installabile
│   ├── convex.config.ts
│   ├── schema.ts
│   ├── domain/
│   ├── functions/
│   └── permissions.ts
├── convex/                 # App Convex per testing isolato
│   ├── convex.config.ts
│   └── signaturesApi.ts
├── ui-example/             # Demo Vite/React
└── package.json

Quick start

1. Install dependencies:

   npm install

2. Configura Convex (prima volta):

   npx convex dev

   Segui il wizard per creare/collegare un deployment dev dedicato.

Installazione in un app host (es. PrimoUpCore)

yalc add @primocaredentgroup/signatures-component
npm install

In convex/convex.config.ts:

import signatures from "@primocaredentgroup/signatures-component/convex.config.js";
app.use(signatures, { name: "signatures" });

Verifica

npm run test
npm run typecheck

Le API legacy di firma singola restano disponibili durante la migrazione del Core; i nuovi flussi devono usare le pratiche documentali.