@topconsultnpm/sdkui-react 6.22.0-t1 → 6.22.0-t3

package/lib/hooks/useWorkflowApprove.js

@@ -1,5 +1,25 @@
 import { useState, useEffect, useCallback } from 'react';
 import { SDK_Globals } from '@topconsultnpm/sdk-ts';
+const WORKFLOW_APPROVE_CHANGED_EVENT = 'onWorkflowApproveChange';
+/** Totale dei documenti da approvare: somma dei dcmtsFound delle singole categorie. */
+const calcTotalDcmtsFound = (data) => {
+    return data.reduce((sum, item) => sum + (item.dcmtsFound || 0), 0);
+};
+/**
+ * Fetch in corso.
+ *
+ * La WFAppr non porta un contatore ma l'intera lista di approvazione con le righe
+ * dei documenti, ed è chiesta da più istanze del hook a ridosso l'una dell'altra
+ * (coda del login, pagina di approvazione, widget della home). Chi arriva mentre
+ * è già in volo aspetta la stessa risposta invece di aprire una seconda richiesta.
+ */
+let inFlight;
+/** Ricarica i dati e notifica tutte le istanze del hook. */
+const load = async () => {
+    const result = await SDK_Globals.tmSession?.NewWorkflowEngine().WFApprAsync(1);
+    SDK_Globals.currentWorkflowApproveData = result ?? [];
+    window.dispatchEvent(new CustomEvent(WORKFLOW_APPROVE_CHANGED_EVENT));
+};
 /**
  * Hook per gestire i dati di approvazione del workflow.
  * Fornisce il dataSource, lo stato di caricamento e una funzione per aggiornare i dati.
@@ -7,13 +27,10 @@ import { SDK_Globals } from '@topconsultnpm/sdk-ts';
 export const useWorkflowApprove = () => {
     const [workflowApproveData, setWorkflowApproveData] = useState(SDK_Globals.currentWorkflowApproveData);
     const [isLoading, setIsLoading] = useState(false);
-    const [totalDcmtsFound, setTotalDcmtsFound] = useState(0);
-    /**
-     * Calcola il numero totale di dcmtsFound dai dati del workflow.
-     */
-    const calculateTotalDcmtsFound = useCallback((data) => {
-        return data.reduce((sum, item) => sum + (item.dcmtsFound || 0), 0);
-    }, []);
+    // Seminato dai dati già in cache: un'istanza montata a login concluso parte dal
+    // totale reale e non da zero, altrimenti chi confronta questo valore con il
+    // contatore della home vede una differenza inesistente e ricarica a vuoto.
+    const [totalDcmtsFound, setTotalDcmtsFound] = useState(() => calcTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
     /**
      * Ottiene tutti i work items che corrispondono a un determinato DID.
      * Restituisce un array di oggetti { tid, did }.
@@ -40,12 +57,10 @@ export const useWorkflowApprove = () => {
         }
         setIsLoading(true);
         try {
-            const result = await SDK_Globals.tmSession.NewWorkflowEngine().WFApprAsync(1);
-            SDK_Globals.currentWorkflowApproveData = result ?? [];
-            // Aggiorna anche il totale dei dcmtsFound
-            setTotalDcmtsFound(calculateTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
-            // Notifica tutte le istanze del hook che i dati sono cambiati.
-            window.dispatchEvent(new CustomEvent('onWorkflowApproveChange'));
+            if (!inFlight) {
+                inFlight = load().finally(() => { inFlight = undefined; });
+            }
+            await inFlight;
         }
         catch (error) {
             console.error("Errore durante il fetch dei dati di approvazione workflow:", error);
@@ -53,18 +68,19 @@ export const useWorkflowApprove = () => {
         finally {
             setIsLoading(false);
         }
-    }, [calculateTotalDcmtsFound]); // useCallback con array vuoto perché non ha dipendenze esterne a React
+    }, []);
     // Questo useEffect serve a sincronizzare lo stato tra diverse istanze del hook.
     // Se il componente A chiama refreshWorkflowApprove, il componente B (che usa lo stesso hook)
     // riceverà l'evento e aggiornerà il suo stato locale.
     useEffect(() => {
         const handleUpdate = () => {
             setWorkflowApproveData(SDK_Globals.currentWorkflowApproveData);
+            setTotalDcmtsFound(calcTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
         };
-        window.addEventListener('onWorkflowApproveChange', handleUpdate);
+        window.addEventListener(WORKFLOW_APPROVE_CHANGED_EVENT, handleUpdate);
         return () => {
-            window.removeEventListener('onWorkflowApproveChange', handleUpdate);
+            window.removeEventListener(WORKFLOW_APPROVE_CHANGED_EVENT, handleUpdate);
         };
-    }, [calculateTotalDcmtsFound]);
+    }, []);
     return { workflowApproveData, isLoading, refreshWorkflowApprove, totalDcmtsFound, getWorkItemsByDID };
 };

package/lib/index.d.ts

@@ -8,7 +8,9 @@ export * from './hooks/useQueryParametersDialog';
 export * from './hooks/useDcmtOperations';
 export * from './hooks/useResizeObserver';
 export * from './hooks/useWorkflowApprove';
+export * from './hooks/useCaseFlowApprove';
 export * from './hooks/useRelatedDocuments';
 export * from './hooks/useSettingsFeedback';
 export * from './hooks/useBetaFeatures';
+export * from './hooks/useShowDossiersV5';
 export * from './services';

package/lib/index.js

@@ -8,10 +8,13 @@ export * from './hooks/useQueryParametersDialog';
 export * from './hooks/useDcmtOperations';
 export * from './hooks/useResizeObserver';
 export * from './hooks/useWorkflowApprove';
+export * from './hooks/useCaseFlowApprove';
 export * from './hooks/useRelatedDocuments';
 export * from './hooks/useSettingsFeedback';
 export * from './hooks/useBetaFeatures';
+export * from './hooks/useShowDossiersV5';
 export * from './services';
 import config from 'devextreme/core/config';
-// DevExtreme License Key (valid for v25.2 and earlier versions)
-config({ licenseKey: 'ewogICJmb3JtYXQiOiAxLAogICJjdXN0b21lcklkIjogIjE1ODg1NDc4LTNjNTItNGUzYy1hNDI1LTU5NjAzMzQ0ZDVjMyIsCiAgIm1heFZlcnNpb25BbGxvd2VkIjogMjUyCn0=.ClI5PeQ2vnl48q0hwdwPHM6oDArs6XTeZ9u4JfN6kxaHoKgszVywO996SluAQfPdFhtzWz6OZsyDdenKv28UU2dOF5wppP88hGEJ17PAg+N/OpUkL1L/CMFNXlOIsYd2517GWA==' });
+import { licenseKey } from './devextreme-license';
+// DevExtreme License Key
+config({ licenseKey });

package/lib/services/caseflow/CaseFlowService.d.ts

@@ -0,0 +1,277 @@
+import { BlogPost, BlogPostAttachment, CaseFlowDcmt, CaseFlowGuestPermissions, CaseFlowInstanceDescriptor, CaseFlowParticipant, CaseFlowTemplateDescriptor, CaseFlowWorkItem, DcmtTypeDescriptor, CF_ParticipantRoles, CF_States } from '@topconsultnpm/sdk-ts';
+type PendingGroup = Array<{
+    caseflow: CaseFlowInstanceDescriptor;
+    workItems: CaseFlowWorkItem[];
+}>;
+/** Criteri di ricerca delle istanze (pannello Ricerca e Process Mining). */
+export interface CaseFlowSearchCriteria {
+    templateId?: number;
+    name?: string;
+    description?: string;
+    state?: CF_States;
+    dateFrom?: string;
+    dateTo?: string;
+    metadataFilters?: Array<{
+        mid: number;
+        value: string;
+    }>;
+    /** Ricerca libera: cerca il valore in tutti i metadati di qualsiasi template */
+    freeTextMetadata?: string;
+}
+/** Documento non cancellato durante l'eliminazione di un'istanza (orfano). */
+export interface CaseFlowDeleteOrphan {
+    tid: number;
+    did: number;
+    /** Motivo del fallimento (tipicamente "Document not accessible by this user"). */
+    reason: string;
+}
+/** Esito dell'eliminazione di un'istanza di CaseFlow. */
+export interface CaseFlowDeleteResult {
+    instanceDID: number;
+    /** true se tutti i documenti individuati sono stati cancellati. */
+    complete: boolean;
+    /** Documenti non cancellati perché non accessibili all'utente (vista parametrica/CdV). */
+    orphaned: CaseFlowDeleteOrphan[];
+}
+export declare class CaseFlowService {
+    /** Elenco dei template reali (via CaseFlowTemplateCacheService). */
+    static getTemplates(): Promise<CaseFlowTemplateDescriptor[]>;
+    /**
+     * Singolo template per id. Usa GetAsync (non un find su GetAllAsync): così i
+     * template di cui l'utente NON può creare istanze — ma di cui è destinatario
+     * di un workitem (es. Completamento dati) — vengono risolti on-demand via
+     * RetrieveAsync mirata invece di restituire undefined.
+     */
+    static getTemplate(id: number): Promise<CaseFlowTemplateDescriptor | undefined>;
+    /** Invalida la cache dei template (dopo creazione/modifica/eliminazione). */
+    static invalidateTemplatesCache(): void;
+    /** DcmtTypeDescriptor (copertina) per il TID indicato. */
+    static getDcmtTypeAsync(tid: number): Promise<DcmtTypeDescriptor | undefined>;
+    /** Tutte le istanze visibili all'utente (unione di tutti i template). */
+    static getCaseflows(): Promise<CaseFlowInstanceDescriptor[]>;
+    /**
+     * Singola istanza COMPLETA per id. `RetrieveAllAsync` (usata dalla dashboard)
+     * porta i dati necessari alle card, ma per il dettaglio completo
+     * (documenti/bacheca/timeline) serve comunque una `RetrieveAsync(cftid, id)`
+     * che idrata l'istanza. Il `cftid` va passato quando noto (evita una
+     * scansione); in mancanza viene risolto dalla lista.
+     *
+     * ATTENZIONE sui `workItems` della RetrieveAll: contengono i soli workitem
+     * ANCORA APERTI, non lo storico. Una pratica conclusa arriva con
+     * `workItems: []`, perché non ha più nulla di pendente. Chi deve ricostruire
+     * la STORIA di una pratica (chi ha fatto cosa e quando) non può quindi basarsi
+     * sull'elenco: serve la Retrieve completa, e la fonte dei passaggi già
+     * avvenuti sono i messaggi di sistema della bacheca (`blogPosts` con
+     * allegato di riferimento all'azione).
+     */
+    static getCaseflow(id: number, cftid?: number): Promise<CaseFlowInstanceDescriptor | undefined>;
+    /**
+     * Come {@link getCaseflow} ma PROPAGA l'errore invece di inghiottirlo.
+     * Da usare nei punti in cui l'utente apre esplicitamente l'istanza (apertura
+     * scheda, deep link): il fallimento della Retrieve deve essere notificato,
+     * non mascherato da una vista incompleta ("non sei un partecipante").
+     */
+    static retrieveCaseflow(id: number, cftid?: number): Promise<CaseFlowInstanceDescriptor | undefined>;
+    /** Istanze di cui l'utente indicato è proprietario. */
+    static getMyCaseflows(userId: number): Promise<CaseFlowInstanceDescriptor[]>;
+    /** Ricerca avanzata sulle istanze applicando i filtri indicati. */
+    static searchCaseflows(criteria: CaseFlowSearchCriteria): Promise<CaseFlowInstanceDescriptor[]>;
+    /** WorkItem pendenti assegnati all'utente, raggruppati per istanza. */
+    static getMyPendingWorkItems(userId: number): Promise<PendingGroup>;
+    /**
+     * Richieste di "maggiori informazioni" INVIATE dall'utente e ancora in
+     * attesa di risposta, raggruppate per istanza.
+     *
+     * Non basta filtrare `toUserID === userId && state === MoreInfo` (il solo
+     * workitem "padre" bloccato intestato a me): a seconda di come il backend
+     * materializza la richiesta, l'unico workitem visibile può essere quello
+     * INVIATO al destinatario (`fromUserID === userId`, categoria MoreInfo,
+     * ancora Pending). In quel caso il filtro su `toUserID` non lo intercetta e
+     * l'istanza sparisce da TUTTE le sezioni di "Per te" (non è più Pending per
+     * me, non è MoreInfo intestato a me, e non ne sono owner). Consideriamo
+     * quindi entrambe le rappresentazioni, preferendo il figlio inviato (che
+     * porta il destinatario) ed evitando di mostrare padre + figlio della
+     * stessa richiesta.
+     */
+    static getMyMoreInfoRequests(userId: number): Promise<PendingGroup>;
+    private static collectWorkItemsByState;
+    /**
+     * Crea una nuova istanza a partire da un template tramite CreateAsync.
+     * I metadati di copertina (metadataValues: mid -> valore) vengono passati
+     * nel campo `cover`. Il backend materializza azioni/stati/partecipanti dal
+     * template identificato da `cftid`.
+     * @returns id della nuova istanza.
+     */
+    static CreateCaseFlowInstance(template: CaseFlowTemplateDescriptor, instanceName: string, instanceDescription: string | undefined, metadataValues: Record<number, string>): Promise<number>;
+    /**
+     * Avvia un'istanza tramite StartAsync(cftid, id): il backend porta la pratica
+     * da `New` a `InProgress` e materializza i workitem della prima azione.
+     *
+     * NON va chiamata dopo `CreateCaseFlowInstance`: la Create dell'API REST
+     * esegue già lo start internamente, quindi un'istanza appena creata è
+     * ancora `New` solo nel descrittore inviato, non lato server. Questa resta
+     * per le istanze che si trovano davvero in `New` (avvio differito); sulle
+     * altre il backend rifiuta.
+     */
+    static startCaseflow(caseFlowId: number, cftid?: number): Promise<void>;
+    /**
+     * Elimina un'istanza tramite DeleteAsync(cftid, id). Il cftid è preso dal
+     * template fornito (se disponibile) oppure risolto dall'istanza.
+     */
+    static DeleteCaseFlowInstance(instanceId: number, template?: CaseFlowTemplateDescriptor): Promise<CaseFlowDeleteResult>;
+    /** Aggiorna un'istanza esistente tramite UpdateAsync. */
+    static saveCaseflow(caseflow: CaseFlowInstanceDescriptor): Promise<void>;
+    /**
+     * Aggiunge un post in bacheca tramite BlogPostAddAsync(cftid, id, bp). Il
+     * cftid è passato quando noto (evita una Retrieve) oppure risolto dall'istanza.
+     * @returns il post creato (transitorio: la ricarica leggerà quelli reali).
+     */
+    static addBlogPost(caseFlowId: number, text: string, authorId: number, authorName: string, attachments?: BlogPostAttachment[], cftid?: number): Promise<BlogPost>;
+    /**
+     * Elimina (o ripristina) un post in bacheca tramite
+     * BlogPostDeleteOrUndeleteAsync(cftid, id, postID, del).
+     */
+    static deleteOrUndeleteBlogPost(caseFlowId: number, postId: number, del: boolean, cftid?: number): Promise<void>;
+    /**
+     * Aggancia un documento (nuovo archiviato o già presente in archivio)
+     * all'istanza tramite DcmtAddOrRemoveAsync(remove=false).
+     * @returns descrittore transitorio del documento agganciato (la ricarica
+     *          dell'istanza leggerà quello reale).
+     */
+    static addDcmtToInstance(caseFlowId: number, tid: number, did: number, cftid?: number): Promise<CaseFlowDcmt | undefined>;
+    /** Sgancia un documento dall'istanza tramite DcmtAddOrRemoveAsync(remove=true). */
+    static removeDcmtFromInstance(caseFlowId: number, tid: number, did: number, cftid?: number): Promise<void>;
+    /** Aggiunge o aggiorna (upsert) la regola documenti del TID sulla sola istanza. */
+    static saveDcmtRule(caseFlowId: number, tid: number, min: number, max: number, cftid?: number): Promise<void>;
+    /** Rimuove la regola documenti del TID dalla sola istanza. */
+    static removeDcmtRule(caseFlowId: number, tid: number, cftid?: number): Promise<void>;
+    /**
+     * Chiama DcmtRuleAddOrRemoveAsync(cftid, id, tid, min, max, remove)
+     * risolvendo il cftid quando non passato (come per bacheca e partecipanti).
+     */
+    private static dcmtRuleAddOrRemove;
+    /**
+     * Chiama DcmtAddOrRemoveAsync(cftid, id, tid, did, remove) risolvendo il
+     * cftid quando non passato (come per bacheca e partecipanti).
+     */
+    private static dcmtAddOrRemove;
+    /**
+     * Allega un file alla pratica tramite AttachAddAsync(cftid, id, ...).
+     * @returns il DID dell'allegato appena archiviato.
+     */
+    static addAttachment(caseFlowId: number, file: File, name?: string, description?: string, cftid?: number): Promise<number | undefined>;
+    /**
+     * Toglie l'allegato dalla pratica tramite AttachRemoveAsync(cftid, id, attachDID).
+     * A differenza dello sgancio di un documento d'archivio, qui il file viene
+     * anche cancellato: un allegato fuori dalla sua pratica non ha più senso.
+     */
+    static removeAttachment(caseFlowId: number, attachDID: number, cftid?: number): Promise<void>;
+    /**
+     * Aggiunge un partecipante all'istanza (o ne aggiorna ruolo/permessi se già
+     * presente) tramite ParticipantsAddOrRemoveAsync(remove=false).
+     */
+    static addParticipant(caseFlowId: number, userId: number, userName: string, role: CF_ParticipantRoles, guestPermissions?: CaseFlowGuestPermissions, cftid?: number): Promise<CaseFlowParticipant | undefined>;
+    /** Rimuove un partecipante dall'istanza tramite ParticipantsAddOrRemoveAsync(remove=true). */
+    static removeParticipant(caseFlowId: number, userId: number, cftid?: number): Promise<void>;
+    /**
+     * Cambia il ruolo di un partecipante ri-applicando l'upsert col nuovo ruolo
+     * (non esiste un'Update dedicata). Passando a Guest si conservano/impostano i
+     * relativi permessi.
+     */
+    static changeParticipantRole(caseFlowId: number, userId: number, role: CF_ParticipantRoles, guestPermissions?: CaseFlowGuestPermissions, cftid?: number): Promise<void>;
+    /** Aggiorna i permessi Guest di un partecipante (upsert col ruolo Guest). */
+    static updateParticipantGuestPermissions(caseFlowId: number, userId: number, permissions: CaseFlowGuestPermissions, cftid?: number): Promise<void>;
+    /**
+     * Chiama ParticipantsAddOrRemoveAsync(cftid, id, d, remove) risolvendo il
+     * cftid quando non passato (come per la bacheca).
+     */
+    private static participantsAddOrRemove;
+    /** Istanze marcate come preferite dall'utente corrente. */
+    static getFavorites(): Promise<CaseFlowInstanceDescriptor[]>;
+    /**
+     * Aggiunge o rimuove l'istanza dai preferiti dell'utente corrente tramite
+     * FavoritesAddOrRemoveAsync(cftid, id, remove).
+     */
+    static setFavorite(caseFlowId: number, favorite: boolean, cftid?: number): Promise<void>;
+    /**
+     * Inizia o smette di seguire l'istanza tramite
+     * FollowAddOrRemoveAsync(cftid, id, remove).
+     */
+    static setFollow(caseFlowId: number, follow: boolean, cftid?: number): Promise<void>;
+    /**
+     * Stato "l'utente corrente segue questa pratica" letto dal descrittore.
+     *
+     * `isFollow` fa ormai parte del contratto (`CaseFlowInstanceDescriptor`):
+     * arriva valorizzato da `usp_Cfi_RetrieveAll`/`usp_Cfi_Retrieve`. Resta
+     * `undefined` solo quando il descrittore proviene da una sorgente che non
+     * popola il campo.
+     *
+     * Da NON dedurre dalla bacheca Home come fanno pratiche-dossier e gruppi di
+     * lavoro (filtro su `HomeBlogPost.classID`): quella query prende `TOP 30`
+     * righe e il solo ultimo post non di sistema per oggetto, quindi chi segue
+     * un oggetto senza post risulta "non seguace"; per le istanze di CaseFlow,
+     * poi, non esiste nemmeno un ramo nella UNION.
+     */
+    static readFollowFlag(cf: CaseFlowInstanceDescriptor): boolean | undefined;
+    /** Completa (approva) un workitem. La nota facoltativa viene pubblicata in bacheca dal backend. */
+    static completeWorkItem(caseFlowId: number, workItemId: number, response?: string, cftid?: number): Promise<void>;
+    /**
+     * Completa un workitem di "Completamento dati": i metadati valorizzati
+     * (mid -> valore) viaggiano in `metadataValues`; il backend li applica al
+     * documento master dell'istanza e completa il workitem.
+     */
+    static completeDataCompletionWorkItem(caseFlowId: number, workItemId: number, metadataValues: Record<number, string>, response?: string, cftid?: number): Promise<void>;
+    /** Rifiuta un workitem. Il motivo viene pubblicato in bacheca dal backend. */
+    static rejectWorkItem(caseFlowId: number, workItemId: number, response?: string, cftid?: number): Promise<void>;
+    /**
+     * Prende in carico un'azione per se stessi (operazione Claim): il backend
+     * crea il workitem intestato al chiamante e porta l'azione in lavorazione.
+     *
+     * Non e' un caso particolare di `createWorkItemForAction`: assegnare e'
+     * riservato a Owner e Supervisore, prendere in carico e' di chiunque lavori
+     * alla pratica. Passando dall'operazione Assign, un Partecipante si vedeva
+     * rifiutare la presa in carico (TMC-2789).
+     */
+    static claimAction(caseFlowId: number, actionID: number, cftid?: number): Promise<void>;
+    /**
+     * Rilascia un workitem preso in carico (operazione ReleaseClaim): il backend
+     * lo cancella e, se per quell'azione non restano altri destinatari, la riporta
+     * disponibile per la presa in carico.
+     *
+     * Stessa chiamata per due gesti diversi, e' la guardia della SP a distinguerli:
+     * il detentore rilascia il proprio workitem, un Owner/Supervisore annulla
+     * l'assegnazione di un altro. Chi chiama non deve dire quale dei due sta facendo.
+     */
+    static releaseClaim(caseFlowId: number, workItemId: number, cftid?: number): Promise<void>;
+    /** Assegna un'azione a un ALTRO utente creando il relativo workitem (operazione Assign). */
+    static createWorkItemForAction(caseFlowId: number, actionID: number, toUserID: number, description?: string, cftid?: number): Promise<void>;
+    /** Forza il completamento di un'azione (supervisor). */
+    static forceCompleteAction(caseFlowId: number, actionID: number, reason?: string, cftid?: number): Promise<void>;
+    /** Forza il rifiuto di un'azione (supervisor). Il motivo è obbligatorio. */
+    static forceRejectAction(caseFlowId: number, actionID: number, reason: string, cftid?: number): Promise<void>;
+    /**
+     * Richiede maggiori informazioni a un altro utente: il backend crea il
+     * workitem MoreInfo figlio assegnato a `targetUserId` e registra la richiesta.
+     */
+    static requestMoreInfo(caseFlowId: number, workItemId: number, targetUserId: number, message?: string, cftid?: number): Promise<void>;
+    /** Risponde a una richiesta di informazioni completando il workitem MoreInfo. */
+    static respondToMoreInfo(caseFlowId: number, moreInfoWorkItemId: number, response: string, cftid?: number): Promise<void>;
+    /**
+     * Chiama ExecuteWorkItemOperationAsync(cftid, id, operation) risolvendo il
+     * cftid quando non passato (come per bacheca, documenti e partecipanti).
+     */
+    private static executeWorkItemOperation;
+    private static _inFlightInstances?;
+    private static loadAllInstances;
+    private static doLoadAllInstances;
+    /**
+     * Fallback di TRANSIZIONE: enumera le istanze template per template usando
+     * l'elenco dei template visibili all'utente. Non copre le istanze di template
+     * NON visibili (partecipante a livello di istanza): per quelle serve la
+     * RetrieveAll cross-template (cftid=0). Da rimuovere quando cftid=0 è stabile.
+     */
+    private static loadInstancesPerTemplate;
+    /** Valorizza `ownerName` sulle istanze (best-effort, via cache utenti). */
+    private static resolveUserNames;
+}
+export {};