@rytass/bpm-core-nestjs-module 0.5.1 → 0.7.0

package/src/lib/workflow-engine/workflow-engine.service.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkflowEngineService = void 0;
+exports.WorkflowEngineService = exports.MANUAL_TRANSFER_DELEGATION_REASON = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
 const typeorm_1 = require("@nestjs/typeorm");
@@ -9,6 +9,7 @@ const attachment_service_1 = require("../attachment/attachment.service");
 const delegation_service_1 = require("../delegation/delegation.service");
 const form_definition_version_entity_1 = require("../form/form-definition-version.entity");
 const form_enums_1 = require("../form/form.enums");
+const sla_schedule_service_1 = require("../calendar/sla-schedule.service");
 const notification_service_1 = require("../notification/notification.service");
 const notification_entity_1 = require("../notification/notification.entity");
 const notification_enums_1 = require("../notification/notification.enums");
@@ -36,6 +37,11 @@ const workflow_token_entity_1 = require("./workflow-token.entity");
 const MAX_PROCESSING_STEPS = 500;
 const DEFAULT_APPROVAL_HISTORY_TASK_LIMIT = 50;
 const SYSTEM_DRY_RUN_INSTANCE_ID = 'dry-run-instance';
+/**
+ * Delegation-chain reason recorded for an approver-initiated transfer, as
+ * opposed to {@link SLA_ESCALATION_DELEGATION_REASON}.
+ */
+exports.MANUAL_TRANSFER_DELEGATION_REASON = 'MANUAL_TRANSFER';
 const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'bpm:*',
     'bpm.workflow.read_all',
@@ -43,7 +49,7 @@ const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'workflow.read_all',
 ]);
 let WorkflowEngineService = class WorkflowEngineService {
-    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, serviceTaskDispatcher = new workflow_service_task_dispatcher_token_1.DefaultWorkflowServiceTaskDispatcher()) {
+    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, serviceTaskDispatcher = new workflow_service_task_dispatcher_token_1.DefaultWorkflowServiceTaskDispatcher()) {
         this.approvalInstanceRepository = approvalInstanceRepository;
         this.workflowTokenRepository = workflowTokenRepository;
         this.taskRepository = taskRepository;
@@ -60,6 +66,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         this.delegationService = delegationService;
         this.notificationService = notificationService;
         this.signatureService = signatureService;
+        this.slaScheduleService = slaScheduleService;
         this.serviceTaskDispatcher = serviceTaskDispatcher;
     }
     async submitApprovalInstance(input) {
@@ -169,7 +176,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             await this.processRunningInstance(manager, instance);
         });
     }
-    async decideTask(input) {
+    async decideTask(input, options = {}) {
         return this.approvalInstanceRepository.manager.transaction(async (manager) => {
             const taskRepository = manager.getRepository(task_entity_1.TaskEntity);
             const taskCandidateRepository = manager.getRepository(task_candidate_entity_1.TaskCandidateEntity);
@@ -223,6 +230,14 @@ let WorkflowEngineService = class WorkflowEngineService {
             const returnToNodeId = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED
                 ? readReturnTargetNodeId(instance.workflowSnapshot, task.nodeId, input.returnToNodeId)
                 : null;
+            // Read from the instance snapshot, not the live template: templates
+            // that turn `requireComment` on later must not retroactively block
+            // in-flight instances started against the previous version.
+            if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED &&
+                !decisionComment &&
+                isReturnCommentRequired(instance.workflowSnapshot, task.nodeId)) {
+                throw new common_1.BadRequestException(`Return decision comment is required by workflow node ${task.nodeId}`);
+            }
             const decidedAt = new Date();
             const claimedTask = await taskRepository.save({
                 ...task,
@@ -261,7 +276,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                 transferToMemberId,
             }));
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.TRANSFERRED) {
-                await this.transferTask(manager, instance, claimedTask, decision, signature, transferToMemberId, decisionComment, decidedAt, claimedCandidate);
+                await this.transferTask(manager, instance, claimedTask, decision, signature, transferToMemberId, decisionComment, decidedAt, claimedCandidate, options.transferReason ?? exports.MANUAL_TRANSFER_DELEGATION_REASON);
                 await this.notificationService.resolveTaskNotifications({
                     actingMemberId: input.decidedByMemberId,
                     manager,
@@ -1895,6 +1910,10 @@ let WorkflowEngineService = class WorkflowEngineService {
         const candidates = await this.resolveRuntimeTaskCandidates(manager, instance, node);
         const primaryCandidate = candidates[0];
         const now = new Date();
+        const slaDueAt = await this.slaScheduleService.resolveTaskSlaDueAt({
+            node,
+            now,
+        });
         const task = await taskRepository.save(taskRepository.create({
             assigneeMemberId: candidates.length === 1 ? primaryCandidate.memberId : null,
             assignmentType: candidates.length === 1
@@ -1908,7 +1927,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             nodeId: node.id,
             openedAt: null,
             originalAssigneeMemberId: candidates.length === 1 ? primaryCandidate.originalMemberId : null,
-            slaDueAt: (0, notification_service_1.calculateTaskSlaDueAt)({ node, now }),
+            slaDueAt,
             status: workflow_engine_enums_1.TaskStatusEnum.PENDING,
             tokenId: token.id,
         }));
@@ -2006,7 +2025,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         return nextCandidates;
     }
-    async transferTask(manager, instance, task, decision, signature, transferToMemberId, decisionComment, decidedAt, actorCandidate) {
+    async transferTask(manager, instance, task, decision, signature, transferToMemberId, decisionComment, decidedAt, actorCandidate, transferReason) {
         if (!transferToMemberId) {
             throw new common_1.BadRequestException('Transfer target member is required');
         }
@@ -2021,7 +2040,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             ...readDelegationSteps(task.delegationChain),
             {
                 from: transferringMemberId,
-                reason: 'MANUAL_TRANSFER',
+                reason: transferReason,
                 ruleId: null,
                 to: transferToMemberId,
             },
@@ -2161,9 +2180,9 @@ let WorkflowEngineService = class WorkflowEngineService {
             return this.resolveOrgUnitPositionCandidates(manager, resolver.orgUnitId, resolver.positionId, Boolean(resolver.includeDescendants), label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
         }
         if (resolver.type === 'ORG_UNIT_MANAGER') {
-            return this.resolveOrgUnitManagerCandidates(manager, instance, resolver.orgUnitId, resolver.fallback, label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolveOrgUnitManagerCandidates(manager, instance, resolver.orgUnitId, resolver.fallback, label, resolver.preferClosestOrgUnit === true).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
         }
-        return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+        return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label, resolver.preferClosestOrgUnit === true).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
     }
     async resolvePositionCandidates(manager, positionId, label) {
         const today = toDateOnlyString(new Date());
@@ -2184,9 +2203,9 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         return uniqueTexts(activeMemberships.map((membership) => membership.memberId));
     }
-    async resolveInitiatorManagerCandidates(manager, instance, levelsUp, fallback, label) {
+    async resolveInitiatorManagerCandidates(manager, instance, levelsUp, fallback, label, preferClosestOrgUnit) {
         const normalizedLevelsUp = Math.max(Math.trunc(levelsUp), 1);
-        const resolvedManagerMemberIds = await this.resolveManagerMemberIdsFromOrganization(manager, instance.initiatorMemberId, normalizedLevelsUp);
+        const resolvedManagerMemberIds = await this.resolveManagerMemberIdsFromOrganization(manager, instance.initiatorMemberId, normalizedLevelsUp, preferClosestOrgUnit);
         if (resolvedManagerMemberIds.length) {
             return resolvedManagerMemberIds;
         }
@@ -2207,18 +2226,18 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         return fallback.memberId;
     }
-    async resolveManagerMemberIdsFromOrganization(manager, memberId, levelsUp) {
-        return this.resolveManagerMemberIdsAtLevel(manager, memberId, toDateOnlyString(new Date()), levelsUp);
+    async resolveManagerMemberIdsFromOrganization(manager, memberId, levelsUp, preferClosestOrgUnit) {
+        return this.resolveManagerMemberIdsAtLevel(manager, memberId, toDateOnlyString(new Date()), levelsUp, preferClosestOrgUnit);
     }
-    async resolveManagerMemberIdsAtLevel(manager, memberId, date, remainingLevels) {
-        const directManagerMemberIds = await this.resolveDirectManagerMemberIds(manager, memberId, date);
+    async resolveManagerMemberIdsAtLevel(manager, memberId, date, remainingLevels, preferClosestOrgUnit) {
+        const directManagerMemberIds = await this.resolveDirectManagerMemberIds(manager, memberId, date, preferClosestOrgUnit);
         if (remainingLevels <= 1 || directManagerMemberIds.length === 0) {
             return directManagerMemberIds;
         }
-        const nextLevelGroups = await Promise.all(directManagerMemberIds.map((managerMemberId) => this.resolveManagerMemberIdsAtLevel(manager, managerMemberId, date, remainingLevels - 1)));
+        const nextLevelGroups = await Promise.all(directManagerMemberIds.map((managerMemberId) => this.resolveManagerMemberIdsAtLevel(manager, managerMemberId, date, remainingLevels - 1, preferClosestOrgUnit)));
         return uniqueTexts(nextLevelGroups.flat());
     }
-    async resolveDirectManagerMemberIds(manager, memberId, date) {
+    async resolveDirectManagerMemberIds(manager, memberId, date, preferClosestOrgUnit) {
         const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
             where: { memberId },
         });
@@ -2227,11 +2246,11 @@ let WorkflowEngineService = class WorkflowEngineService {
         const positionIds = activeMemberships
             .map((membership) => membership.positionId)
             .filter((positionId) => Boolean(positionId));
-        const orgUnitIds = await this.readOrgUnitAndAncestorIds(manager, directOrgUnitIds);
+        const orgUnits = await this.readOrgUnitAndAncestors(manager, directOrgUnitIds);
         const candidatePairs = [
             { scopeId: memberId, scopeType: organization_enums_1.ManagerResolutionScopeTypeEnum.MEMBER },
-            ...orgUnitIds.map((scopeId) => ({
-                scopeId,
+            ...orgUnits.map((orgUnit) => ({
+                scopeId: orgUnit.id,
                 scopeType: organization_enums_1.ManagerResolutionScopeTypeEnum.ORG_UNIT,
             })),
             ...positionIds.map((scopeId) => ({
@@ -2239,17 +2258,15 @@ let WorkflowEngineService = class WorkflowEngineService {
                 scopeType: organization_enums_1.ManagerResolutionScopeTypeEnum.POSITION,
             })),
         ];
-        return this.resolveManagerResolutionCandidates(manager, candidatePairs, date);
+        return this.resolveManagerResolutionCandidates(manager, candidatePairs, date, readOrgUnitDepthMap(orgUnits), preferClosestOrgUnit);
     }
-    async resolveOrgUnitManagerCandidates(manager, instance, orgUnitId, fallback, label) {
+    async resolveOrgUnitManagerCandidates(manager, instance, orgUnitId, fallback, label, preferClosestOrgUnit) {
         const date = toDateOnlyString(new Date());
-        const orgUnitIds = await this.readOrgUnitAndAncestorIds(manager, [
-            orgUnitId,
-        ]);
-        const managerMemberIds = await this.resolveManagerResolutionCandidates(manager, orgUnitIds.map((scopeId) => ({
-            scopeId,
+        const orgUnits = await this.readOrgUnitAndAncestors(manager, [orgUnitId]);
+        const managerMemberIds = await this.resolveManagerResolutionCandidates(manager, orgUnits.map((orgUnit) => ({
+            scopeId: orgUnit.id,
             scopeType: organization_enums_1.ManagerResolutionScopeTypeEnum.ORG_UNIT,
-        })), date);
+        })), date, readOrgUnitDepthMap(orgUnits), preferClosestOrgUnit);
         if (!managerMemberIds.length) {
             return [
                 this.resolveFallbackAssignee(instance, fallback, label, `找不到指定組織的主管規則`),
@@ -2257,7 +2274,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         return managerMemberIds;
     }
-    async readOrgUnitAndAncestorIds(manager, orgUnitIds) {
+    async readOrgUnitAndAncestors(manager, orgUnitIds) {
         if (!orgUnitIds.length) {
             return [];
         }
@@ -2271,9 +2288,9 @@ let WorkflowEngineService = class WorkflowEngineService {
             .andWhere('orgUnit.path @> :path', { path: orgUnit.path })
             .getMany()));
         const byId = new Map([...directOrgUnits, ...ancestorGroups.flat()].map((orgUnit) => [orgUnit.id, orgUnit]));
-        return [...byId.keys()];
+        return [...byId.values()];
     }
-    async resolveManagerResolutionCandidates(manager, candidatePairs, date) {
+    async resolveManagerResolutionCandidates(manager, candidatePairs, date, orgUnitDepths, preferClosestOrgUnit) {
         const scopeIds = candidatePairs.map((pair) => pair.scopeId);
         if (!scopeIds.length) {
             return [];
@@ -2290,12 +2307,13 @@ let WorkflowEngineService = class WorkflowEngineService {
                 ]),
             },
         });
+        const depthLookup = preferClosestOrgUnit ? orgUnitDepths : undefined;
         const active = resolutions
             .filter((resolution) => candidatePairs.some((pair) => pair.scopeId === resolution.scopeId &&
             pair.scopeType === resolution.scopeType))
             .filter((resolution) => isDateRangeActive(resolution, date))
-            .sort(compareManagerResolution);
-        return uniqueTexts(active.map((resolution) => resolution.managerMemberId));
+            .sort((left, right) => compareManagerResolution(left, right, depthLookup));
+        return uniqueTexts(readTopPriorityResolutions(active, depthLookup).map((resolution) => resolution.managerMemberId));
     }
     async resolveOrgUnitMemberCandidates(manager, orgUnitId, includeDescendants, label) {
         const orgUnitIds = await this.readOrgUnitScopeIds(manager, orgUnitId, includeDescendants);
@@ -2716,8 +2734,8 @@ exports.WorkflowEngineService = WorkflowEngineService = tslib_1.__decorate([
     tslib_1.__param(8, (0, typeorm_1.InjectRepository)(approval_template_entity_1.ApprovalTemplateEntity)),
     tslib_1.__param(9, (0, typeorm_1.InjectRepository)(approval_template_version_entity_1.ApprovalTemplateVersionEntity)),
     tslib_1.__param(10, (0, typeorm_1.InjectRepository)(form_definition_version_entity_1.FormDefinitionVersionEntity)),
-    tslib_1.__param(16, (0, common_1.Optional)()),
-    tslib_1.__param(16, (0, common_1.Inject)(workflow_service_task_dispatcher_token_1.BPM_WORKFLOW_SERVICE_TASK_DISPATCHER)),
+    tslib_1.__param(17, (0, common_1.Optional)()),
+    tslib_1.__param(17, (0, common_1.Inject)(workflow_service_task_dispatcher_token_1.BPM_WORKFLOW_SERVICE_TASK_DISPATCHER)),
     tslib_1.__metadata("design:paramtypes", [typeorm_2.Repository,
         typeorm_2.Repository,
         typeorm_2.Repository,
@@ -2733,7 +2751,8 @@ exports.WorkflowEngineService = WorkflowEngineService = tslib_1.__decorate([
         condition_service_1.ConditionService,
         delegation_service_1.DelegationService,
         notification_service_1.NotificationService,
-        signature_service_1.SignatureService, Object])
+        signature_service_1.SignatureService,
+        sla_schedule_service_1.BPMSlaScheduleService, Object])
 ], WorkflowEngineService);
 function parseJsonObject(value, label) {
     try {
@@ -2917,6 +2936,11 @@ function readDefaultReturnTargetNodeId(workflow, currentNode) {
     }
     return previousNodeId;
 }
+function isReturnCommentRequired(workflow, nodeId) {
+    const node = readWorkflowNodeOrThrow(workflow, nodeId);
+    return (node.type === 'userTask' &&
+        node.data.returnBehavior.requireComment === true);
+}
 function readReturnResubmitStrategy(task, instance) {
     const node = readWorkflowNodeOrThrow(instance.workflowSnapshot, task.nodeId);
     if (node.type !== 'userTask') {
@@ -3289,7 +3313,10 @@ function readManagerMemberIdFromInitiatorSnapshot(initiatorMetadataSnapshot, lev
         return managerMemberIds[Math.max(levelsUp - 1, 0)];
     }
     const customFields = initiatorMetadataSnapshot.customFields;
-    if (isRecord(customFields)) {
+    // An empty `customFields` object must not swallow the top-level fallback:
+    // callers commonly send `{ customFields: {}, managerMemberId: '...' }`, and
+    // returning early there resolves no approver at all.
+    if (isRecord(customFields) && customFields.managerMemberId !== undefined) {
         return customFields.managerMemberId;
     }
     return initiatorMetadataSnapshot.managerMemberId;
@@ -3298,14 +3325,61 @@ function isDateRangeActive(value, date) {
     return (value.effectiveFrom <= date &&
         (!value.effectiveTo || value.effectiveTo >= date));
 }
-function compareManagerResolution(left, right) {
+/**
+ * Manager resolutions are sorted by priority and then by scope specificity, so
+ * every entry below the winning tier is a lower-precedence fallback that must
+ * not join the approver list — a company-wide catch-all rule would otherwise be
+ * appended to every member's direct manager. The organization module already
+ * resolves managers this way (`OrganizationService.resolveManagerMemberId`
+ * returns `active[0]`); this keeps the workflow engine consistent with it.
+ *
+ * Ties on the winning tier are preserved so a step can still be shared by
+ * several managers of equal precedence.
+ *
+ * When `orgUnitDepths` is provided and the winning scope is ORG_UNIT, only the
+ * deepest org units on the winning tier are kept so that ancestor-level
+ * catch-all rules do not dilute the approver list. This is opt-in via the
+ * resolver's `preferClosestOrgUnit` flag because org-tree depth does not always
+ * reflect authority (e.g. project offices attached to executive roles).
+ */
+function readTopPriorityResolutions(resolutions, orgUnitDepths) {
+    const [top] = resolutions;
+    if (!top) {
+        return [];
+    }
+    const sameTier = resolutions.filter((resolution) => resolution.priority === top.priority &&
+        resolution.scopeType === top.scopeType);
+    if (orgUnitDepths &&
+        top.scopeType === organization_enums_1.ManagerResolutionScopeTypeEnum.ORG_UNIT) {
+        const maxDepth = Math.max(...sameTier.map((resolution) => orgUnitDepths.get(resolution.scopeId) ?? 0));
+        return sameTier.filter((resolution) => (orgUnitDepths.get(resolution.scopeId) ?? 0) === maxDepth);
+    }
+    return sameTier;
+}
+function compareManagerResolution(left, right, orgUnitDepths) {
     const priorityDiff = right.priority - left.priority;
     if (priorityDiff !== 0) {
         return priorityDiff;
     }
-    return (readManagerResolutionScopeRank(right.scopeType) -
-        readManagerResolutionScopeRank(left.scopeType) ||
-        right.effectiveFrom.localeCompare(left.effectiveFrom));
+    const scopeRankDiff = readManagerResolutionScopeRank(right.scopeType) -
+        readManagerResolutionScopeRank(left.scopeType);
+    if (scopeRankDiff !== 0) {
+        return scopeRankDiff;
+    }
+    if (orgUnitDepths) {
+        const depthDiff = (orgUnitDepths.get(right.scopeId) ?? 0) -
+            (orgUnitDepths.get(left.scopeId) ?? 0);
+        if (depthDiff !== 0) {
+            return depthDiff;
+        }
+    }
+    return right.effectiveFrom.localeCompare(left.effectiveFrom);
+}
+function readOrgUnitDepthMap(orgUnits) {
+    return new Map(orgUnits.map((orgUnit) => [
+        orgUnit.id,
+        orgUnit.path.split('.').length,
+    ]));
 }
 function readManagerResolutionScopeRank(scopeType) {
     const ranks = {