@rytass/bpm-core-nestjs-module 0.14.0 → 0.15.0

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

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkflowEngineService = exports.MANUAL_TRANSFER_DELEGATION_REASON = void 0;
+exports.WorkflowEngineService = exports.MANUAL_TRANSFER_DELEGATION_REASON = exports.MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH = void 0;
 const tslib_1 = require("tslib");
+const class_validator_1 = require("class-validator");
 const form_1 = require("@rytass/bpm-core-shared/form");
 const workflow_graph_1 = require("@rytass/bpm-core-shared/workflow-graph");
 const workflow_webhook_delivery_service_1 = require("../workflow-webhook/workflow-webhook-delivery.service");
@@ -13,6 +14,7 @@ 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 form_data_source_errors_1 = require("../form-data-source/form-data-source.errors");
+const form_member_value_validator_1 = require("../form/form-member-value.validator");
 const form_data_source_types_1 = require("../form-data-source/form-data-source.types");
 const sla_schedule_service_1 = require("../calendar/sla-schedule.service");
 const notification_service_1 = require("../notification/notification.service");
@@ -25,6 +27,7 @@ const membership_entity_1 = require("../organization/membership.entity");
 const org_unit_entity_1 = require("../organization/org-unit.entity");
 const position_entity_1 = require("../organization/position.entity");
 const organization_enums_1 = require("../organization/organization.enums");
+const organization_time_zone_1 = require("../organization/organization-time-zone");
 const approval_template_version_entity_1 = require("../template/approval-template-version.entity");
 const approval_template_entity_1 = require("../template/approval-template.entity");
 const template_enums_1 = require("../template/template.enums");
@@ -32,6 +35,7 @@ const activity_log_entity_1 = require("./activity-log.entity");
 const adhoc_directive_entity_1 = require("./adhoc-directive.entity");
 const adhoc_enums_1 = require("./adhoc.enums");
 const approval_instance_entity_1 = require("./approval-instance.entity");
+const instance_submitter_1 = require("./instance-submitter");
 const task_decision_entity_1 = require("./task-decision.entity");
 const task_candidate_entity_1 = require("./task-candidate.entity");
 const task_entity_1 = require("./task.entity");
@@ -42,6 +46,8 @@ const workflow_service_task_dispatcher_token_1 = require("./workflow-service-tas
 const workflow_token_entity_1 = require("./workflow-token.entity");
 const bpm_root_options_1 = require("../bpm/bpm-root-options");
 const MAX_PROCESSING_STEPS = 500;
+exports.MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH = 200;
+const APPROVAL_INSTANCE_BUSINESS_KEY_INDEX = 'approval_instances_business_key_key';
 // Guards ORG_MANAGER_CHAIN against misconfigured manager rules that never end.
 const ORG_MANAGER_CHAIN_MAX_HOPS = 20;
 const DEFAULT_APPROVAL_HISTORY_TASK_LIMIT = 50;
@@ -92,9 +98,27 @@ let WorkflowEngineService = class WorkflowEngineService {
             injectedServiceTaskDispatcher ??
                 rootOptions?.workflowServiceTaskDispatcher ??
                 new workflow_service_task_dispatcher_token_1.DefaultWorkflowServiceTaskDispatcher();
+        this.organizationTimeZone = (0, organization_time_zone_1.resolveBPMOrganizationTimeZone)(rootOptions?.organizationTimeZone);
+    }
+    /**
+     * Today's date as the organization sees it (`organizationTimeZone`), for
+     * comparing against the date-only `effectiveFrom` / `effectiveTo` of
+     * memberships and manager resolutions. Not for timestamp columns, which are
+     * compared as instants.
+     */
+    readOrganizationToday() {
+        return (0, organization_time_zone_1.formatDateOnlyInTimeZone)(new Date(), this.organizationTimeZone);
     }
     async submitApprovalInstance(input, authContext) {
+        if (input.submittedByMemberId !== undefined &&
+            input.submittedByMemberId !== null &&
+            (typeof input.submittedByMemberId !== 'string' ||
+                input.submittedByMemberId.trim() === '')) {
+            throw new common_1.BadRequestException('submittedByMemberId must be a non-empty string');
+        }
         const formData = parseJsonObject(input.formDataJson, 'formDataJson');
+        const businessKey = normalizeBusinessKey(input.businessKey);
+        const submittedByMemberId = input.submittedByMemberId ?? input.initiatorMemberId;
         const template = await this.getTemplateOrThrow(input.templateId);
         if (!template.isActive) {
             throw new common_1.ConflictException('Approval template is deactivated');
@@ -117,6 +141,12 @@ let WorkflowEngineService = class WorkflowEngineService {
         if (!this.conditionService.evaluateBoolean(templateVersion.initiatorPolicyCel, buildInitiatorPolicyContext(initiatorMetadataSnapshot), 'initiatorPolicyCel')) {
             throw new common_1.ConflictException('Current member is not allowed to start this approval template');
         }
+        // Named here, before the transaction, so the completion notice that later
+        // says "由 X 代為送出" reads it from the started activity instead of
+        // asking the identity source while an approval holds the instance's locks.
+        const submittedByName = submittedByMemberId === input.initiatorMemberId
+            ? null
+            : await this.notificationService.readMemberDisplayName(submittedByMemberId);
         const startedAt = new Date();
         const startNode = templateVersion.workflowDefinition.nodes.find((node) => node.type === 'startEvent');
         if (!startNode) {
@@ -136,10 +166,12 @@ let WorkflowEngineService = class WorkflowEngineService {
                     uiSchema: formDefinitionVersion.uiSchema,
                     version: formDefinitionVersion.version,
                 },
+                businessKey,
                 initiatorMemberId: input.initiatorMemberId,
                 initiatorMetadataSnapshot,
                 startedAt,
                 state: workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING,
+                submittedByMemberId,
                 templateId: template.id,
                 templateVersionId: templateVersion.id,
                 title: input.title?.trim() || template.name,
@@ -163,6 +195,8 @@ let WorkflowEngineService = class WorkflowEngineService {
                     instanceId: instance.id,
                     nodeId: startNode.id,
                     payload: {
+                        submittedByMemberId,
+                        ...(submittedByName === null ? {} : { submittedByName }),
                         templateId: template.id,
                         templateVersionId: templateVersion.id,
                     },
@@ -181,6 +215,28 @@ let WorkflowEngineService = class WorkflowEngineService {
             ]);
             await this.processRunningInstance(manager, instance);
             return instance;
+        }).catch((error) => 
+        // The insert decides, not a pre-check: two concurrent submits would both
+        // pass a check, and only the unique index sees them as one.
+        throwBusinessKeyConflictOrRethrow(error, businessKey));
+    }
+    /**
+     * The instance a host submitted for `businessKey` on `templateId`, whatever
+     * its state (a cancelled or rejected instance still holds its key), or
+     * `null`. The key is trimmed the way submit trims it, so a lookup finds what
+     * a submit stored.
+     */
+    async findApprovalInstanceByBusinessKey(templateId, businessKey) {
+        const normalizedKey = businessKey.trim();
+        // A template id that is not a uuid cannot match a row, and handing it to
+        // Postgres would raise 22P02 (a 500) instead of "not found".
+        if (!(0, class_validator_1.isUUID)(templateId) ||
+            normalizedKey === '' ||
+            countCodePoints(normalizedKey) > exports.MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH) {
+            return null;
+        }
+        return this.approvalInstanceRepository.findOne({
+            where: { businessKey: normalizedKey, templateId },
         });
     }
     async resolveFormDataOptionSnapshots({ authContext, formData, previousFormData, previousSnapshots, revalidateAll, schema, }) {
@@ -324,6 +380,27 @@ let WorkflowEngineService = class WorkflowEngineService {
                 transferToMemberId === instance.initiatorMemberId) {
                 throw new common_1.ConflictException(`簽核節點「${taskNode.data.label}」不允許申請人自簽，不能將任務轉交給申請人本人`);
             }
+            if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.TRANSFERRED &&
+                options.transferReason === undefined &&
+                isInitiatorExcluded(taskNode) &&
+                transferToMemberId !== null &&
+                transferToMemberId === (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance)) {
+                throw new common_1.ConflictException(`簽核節點「${taskNode.data.label}」不允許代送人簽核，不能將任務轉交給代為送出此單的人`);
+            }
+            // Same carve-out: a human picking the target on a manager-chain node
+            // must pick someone at least as senior as the member being replaced.
+            if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.TRANSFERRED &&
+                options.transferReason === undefined &&
+                transferToMemberId !== null &&
+                !task.isAdhoc &&
+                isOrgManagerChainNode(taskNode)) {
+                await this.assertTransferTargetGrade(manager, {
+                    actorMemberId: input.decidedByMemberId,
+                    delegationChain: actorCandidate?.delegationChain ?? task.delegationChain,
+                    label: taskNode.data.label,
+                    targetMemberId: transferToMemberId,
+                });
+            }
             const returnToNodeId = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED
                 ? readReturnTargetNodeId(instance.workflowSnapshot, task.nodeId, input.returnToNodeId)
                 : null;
@@ -850,6 +927,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         })));
         task.candidateMemberIds = savedCandidates.map((candidate) => candidate.memberId);
         task.openCandidateMemberIds = task.candidateMemberIds;
+        task.nodeLabel = readWorkflowNodeLabel(instance.workflowSnapshot, node.id);
         await activityRepository.save(activityRepository.create({
             actorMemberId: directive.createdByMemberId,
             eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.TASK_CREATED,
@@ -882,14 +960,18 @@ let WorkflowEngineService = class WorkflowEngineService {
         return task;
     }
     async resolveAdhocTaskCandidates(manager, instance, node, label, targetValue) {
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`);
-        const delegatedCandidates = await this.delegateResolvedCandidates(instance, node.id, resolvedCandidates);
-        const candidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), instance.initiatorMemberId);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', isInitiatorExcluded(node) ? readInitiatorAndSubmitter(instance) : []);
+        // Ad-hoc approvers are picked by a person, not walked up a manager chain,
+        // so the chain's grade rule does not apply to them.
+        const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, false);
+        const candidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance));
         if (candidates.length > 0) {
             return candidates;
         }
         throw new common_1.ConflictException(delegatedCandidates.length > 0
-            ? `${label}「${node.data.label}」 無法建立任務：指定對象只有申請人本人，此節點不允許申請人簽核。`
+            ? (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) === null
+                ? `${label}「${node.data.label}」 無法建立任務：指定對象只有申請人本人，此節點不允許申請人簽核。`
+                : `${label}「${node.data.label}」 無法建立任務：指定對象只有申請人或代為送出此單的人，此節點不允許申請人或代送人簽核。`
             : `${label}「${node.data.label}」 did not resolve to any member id`);
     }
     async spawnCountersignTasksForNode(manager, instance, token, node, now) {
@@ -1277,7 +1359,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             return;
         }
         try {
-            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象');
+            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象', '通知對象');
             await this.notificationService.createAdhocWorkflowNotifications({
                 channels: directive.channels,
                 instance,
@@ -1395,6 +1477,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             : null;
         const assigneeMemberId = assignment?.assigneeMemberId ?? null;
         const skippedByExclusion = assignment?.outcome === 'SKIPPED';
+        const stoppedByAssignment = assignment?.outcome === 'STOPPED';
         const nextLastDecision = entryConditionMet && node.type === 'userTask' && !skippedByExclusion
             ? {
                 action: workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED,
@@ -1402,6 +1485,15 @@ let WorkflowEngineService = class WorkflowEngineService {
                 nodeId: node.id,
             }
             : input.lastDecision;
+        // A node that stops on its assignment, an asynchronous NOTIFY node (at
+        // runtime it consumes its token and never advances) and an end event do
+        // not route any further.
+        const routes = !stoppedByAssignment &&
+            !(0, workflow_graph_1.isAsyncNotifyServiceTask)(node) &&
+            node.type !== 'endEvent';
+        const outgoing = routes
+            ? this.readDryRunOutgoing(input, node, nextLastDecision, entryConditionMet && !skippedByExclusion)
+            : { edges: [], stopMessage: null };
         const nextSteps = [
             ...input.steps,
             createDryRunStep({
@@ -1411,39 +1503,16 @@ let WorkflowEngineService = class WorkflowEngineService {
                 edgeReason: readDryRunEdgeReason(input.incomingEdge),
                 entryCondition,
                 entryConditionMet,
-                message: assignment?.message ?? readDryRunStepMessage(node, entryConditionMet),
+                message: readDryRunStepResultMessage(assignment?.message ?? null, outgoing.stopMessage, readDryRunStepMessage(node, entryConditionMet), !entryConditionMet || skippedByExclusion),
                 node,
-                status: assignment?.outcome ?? readDryRunStepStatus(node, entryConditionMet),
+                status: outgoing.stopMessage === null
+                    ? (assignment?.outcome ??
+                        readDryRunStepStatus(node, entryConditionMet))
+                    : 'STOPPED',
                 stepIndex: input.steps.length,
             }),
         ];
-        // The initiator is the only approver and the node cannot proceed: this
-        // branch ends here, as it would fail at runtime.
-        if (assignment?.outcome === 'STOPPED') {
-            return nextSteps;
-        }
-        // A NOTIFY node is an asynchronous branch: at runtime it consumes its
-        // token and never advances, so its branch ends here rather than failing
-        // for want of an outgoing edge it is not allowed to have.
-        if ((0, workflow_graph_1.isAsyncNotifyServiceTask)(node)) {
-            return nextSteps;
-        }
-        if (!entryConditionMet || skippedByExclusion || node.type === 'endEvent') {
-            if (node.type === 'endEvent') {
-                return nextSteps;
-            }
-            return readOutgoingEdgesOrThrow(input.workflowDefinition, node.id).reduce((steps, edge) => this.simulateWorkflowPath({
-                ...input,
-                depth: input.depth + 1,
-                incomingEdge: edge,
-                lastDecision: nextLastDecision,
-                nodeId: edge.target,
-                steps,
-                visitedNodeIds: nextVisitedNodeIds,
-            }), nextSteps);
-        }
-        const outgoingEdges = this.readDryRunAvailableOutgoingEdges(input, node, nextLastDecision);
-        return outgoingEdges.reduce((steps, edge) => this.simulateWorkflowPath({
+        return outgoing.edges.reduce((steps, edge) => this.simulateWorkflowPath({
             ...input,
             depth: input.depth + 1,
             incomingEdge: edge,
@@ -1453,28 +1522,45 @@ let WorkflowEngineService = class WorkflowEngineService {
             visitedNodeIds: nextVisitedNodeIds,
         }), nextSteps);
     }
-    readDryRunAvailableOutgoingEdges(input, node, lastDecision) {
-        if (node.type === 'endEvent') {
-            return [];
+    /**
+     * The edges a dry-run step continues along. A node a designer has left
+     * unfinished (nothing drawn out of it, or no branch of a gateway taken) ends
+     * its branch with a readable message instead of failing the whole dry run.
+     */
+    readDryRunOutgoing(input, node, lastDecision, evaluatesConditions) {
+        const nodeName = readDryRunNodeName(node);
+        const outgoingEdges = input.workflowDefinition.edges.filter((edge) => edge.source === node.id);
+        if (outgoingEdges.length === 0) {
+            return {
+                edges: [],
+                stopMessage: `節點「${nodeName}」沒有連到下一個節點，請在流程設計器為此節點接上連線`,
+            };
+        }
+        if (!evaluatesConditions) {
+            return { edges: outgoingEdges, stopMessage: null };
         }
-        const outgoingEdges = readOutgoingEdgesOrThrow(input.workflowDefinition, node.id);
         const conditionalEdges = outgoingEdges.filter((edge) => !edge.data.isDefault && edgeHasCondition(edge));
         if (conditionalEdges.length === 0) {
-            return outgoingEdges;
+            return { edges: outgoingEdges, stopMessage: null };
         }
         const matchingEdges = conditionalEdges.filter((edge) => this.evaluateDryRunEdge(input, edge, lastDecision));
         if (matchingEdges.length > 0) {
-            return node.type === 'exclusiveGateway'
-                ? [matchingEdges[0]]
-                : matchingEdges;
+            return {
+                edges: node.type === 'exclusiveGateway' ? [matchingEdges[0]] : matchingEdges,
+                stopMessage: null,
+            };
         }
         const defaultEdges = outgoingEdges.filter((edge) => edge.data.isDefault);
         if (defaultEdges.length > 0) {
-            return node.type === 'exclusiveGateway'
-                ? [defaultEdges[0]]
-                : defaultEdges;
+            return {
+                edges: node.type === 'exclusiveGateway' ? [defaultEdges[0]] : defaultEdges,
+                stopMessage: null,
+            };
         }
-        throw new common_1.ConflictException(`Workflow node ${node.id} has no matching outgoing edge`);
+        return {
+            edges: [],
+            stopMessage: `節點「${nodeName}」的連出線條件都不符合，且沒有設定預設路徑，請檢查連出線的條件或補上預設路徑`,
+        };
     }
     evaluateDryRunEdge(input, edge, lastDecision) {
         const expression = edge.data.condition?.trim();
@@ -1491,14 +1577,28 @@ let WorkflowEngineService = class WorkflowEngineService {
      */
     resolveDryRunAssignment(input, node) {
         const resolver = node.data.approverResolver;
-        const label = `workflow.nodes.${node.id}.data.approverResolver`;
         const excludeInitiator = node.data.excludeInitiator;
-        const memberIds = excludeInitiator
-            ? this.readDryRunMemberIds(input, resolver, label)
-            : null;
-        if (!excludeInitiator || !memberIds?.includes(input.initiatorMemberId)) {
+        const memberIds = this.readDryRunMemberIds(input, resolver, `workflow.nodes.${node.id}.data.approverResolver`);
+        if (memberIds === null) {
+            return {
+                assigneeMemberId: readDryRunPlaceholderAssignee(resolver),
+                message: null,
+                outcome: null,
+            };
+        }
+        // Nobody to ask yet — typically a node whose approver has not been chosen.
+        // The branch ends here and says which node needs attention, rather than
+        // failing the whole dry run.
+        if (memberIds.length === 0) {
+            return {
+                assigneeMemberId: null,
+                message: readDryRunUnresolvedApproverMessage(resolver, readDryRunNodeName(node), input.initiatorMemberId),
+                outcome: 'STOPPED',
+            };
+        }
+        if (!excludeInitiator || !memberIds.includes(input.initiatorMemberId)) {
             return {
-                assigneeMemberId: this.resolveDryRunAssigneeMemberId(input, resolver, label),
+                assigneeMemberId: memberIds[0],
                 message: null,
                 outcome: null,
             };
@@ -1542,48 +1642,29 @@ let WorkflowEngineService = class WorkflowEngineService {
             outcome: 'STOPPED',
         };
     }
+    /**
+     * The member ids a dry run resolves for a user task: an empty list when the
+     * resolver names nobody, `null` for resolvers that only resolve to a
+     * placeholder in a dry run.
+     */
     readDryRunMemberIds(input, resolver, label) {
         if (resolver.type === 'DIRECT') {
-            return readMemberIdsFromValue(resolver.memberIds, label);
+            return findMemberIdsInValue(resolver.memberIds);
         }
         if (resolver.type === 'DYNAMIC_FORM') {
-            return readMemberIdsFromValue(readValueAtPath(input.formData, resolver.formPath), `${label}.formPath`);
+            return findMemberIdsInValue(readValueAtPath(input.formData, resolver.formPath));
         }
         if (resolver.type === 'EXPRESSION') {
-            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, buildDryRunExpressionContext(input, null), `${label}.expression`), `${label}.expression`);
+            return findMemberIdsInValue(this.conditionService.evaluateValue(resolver.expression, buildDryRunExpressionContext(input, null), `${label}.expression`));
         }
         if (resolver.type === 'ORG_MANAGER') {
-            return readMemberIdsFromValue(readManagerMemberIdFromInitiatorSnapshot(input.initiatorMetadataSnapshot, resolver.levelsUp), label);
+            const managerMemberIds = findMemberIdsInValue(readManagerMemberIdFromInitiatorSnapshot(input.initiatorMetadataSnapshot, resolver.levelsUp));
+            return managerMemberIds.length > 0
+                ? managerMemberIds
+                : readDryRunFallbackMemberIds(input, resolver.fallback);
         }
         return null;
     }
-    resolveDryRunAssigneeMemberId(input, resolver, label) {
-        if (resolver.type === 'DIRECT') {
-            return readMemberIdFromValue(resolver.memberIds, label);
-        }
-        if (resolver.type === 'DYNAMIC_FORM') {
-            return readMemberIdFromValue(readValueAtPath(input.formData, resolver.formPath), `${label}.formPath`);
-        }
-        if (resolver.type === 'EXPRESSION') {
-            return readMemberIdFromValue(this.conditionService.evaluateValue(resolver.expression, buildDryRunExpressionContext(input, null), `${label}.expression`), `${label}.expression`);
-        }
-        if (resolver.type === 'POSITION') {
-            return `position:${resolver.positionId}`;
-        }
-        if (resolver.type === 'ORG_UNIT_MEMBER') {
-            return `orgUnitMember:${resolver.orgUnitId}`;
-        }
-        if (resolver.type === 'ORG_UNIT_POSITION') {
-            return `orgUnitPosition:${resolver.orgUnitId}:${resolver.positionId}`;
-        }
-        if (resolver.type === 'ORG_UNIT_MANAGER') {
-            return `orgUnitManager:${resolver.orgUnitId}`;
-        }
-        if (resolver.type === 'ORG_MANAGER_CHAIN') {
-            return `orgManagerChain:${resolver.minPositionLevel}`;
-        }
-        return readMemberIdFromValue(readManagerMemberIdFromInitiatorSnapshot(input.initiatorMetadataSnapshot, resolver.levelsUp), label);
-    }
     async getApprovalInstance(id, scope) {
         const instance = await this.approvalInstanceRepository.findOne({
             where: { id },
@@ -1655,7 +1736,11 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         const view = options.view ?? workflow_engine_enums_1.ApprovalInstanceListViewEnum.ALL;
         if (view === workflow_engine_enums_1.ApprovalInstanceListViewEnum.SENT) {
-            queryBuilder.andWhere('"approvalInstance"."initiator_member_id" = :readableMemberId', {
+            // The assistant who filed on someone's behalf finds it here too.
+            queryBuilder.andWhere(`(
+          "approvalInstance"."initiator_member_id" = :readableMemberId
+          OR "approvalInstance"."submitted_by_member_id" = :readableMemberId
+        )`, {
                 readableMemberId: scope.memberId,
             });
             return true;
@@ -1679,6 +1764,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         queryBuilder.andWhere(`
         (
           "approvalInstance"."initiator_member_id" = :readableMemberId
+          OR "approvalInstance"."submitted_by_member_id" = :readableMemberId
           OR EXISTS (
             SELECT 1
             FROM "tasks" "readableTask"
@@ -1909,13 +1995,54 @@ let WorkflowEngineService = class WorkflowEngineService {
             ]);
             return nextMap;
         }, new Map());
+        const nodeLabels = await this.readTaskNodeLabels(tasks);
         return tasks.map((task) => Object.assign(new task_entity_1.TaskEntity(), task, {
             candidateMemberIds: candidatesByTaskId.get(task.id) ?? [],
+            nodeLabel: nodeLabels.get(readNodeLabelKey(task.instanceId, task.nodeId)) ??
+                null,
             openCandidateMemberIds: openCandidatesByTaskId.get(task.id) ?? [],
         }));
     }
+    /**
+     * The display names of the nodes a page of tasks sits on, keyed by
+     * {@link readNodeLabelKey}. One query for the whole page, and Postgres picks
+     * the labels out of the snapshots: a workflow snapshot is a whole workflow
+     * definition, and every inbox, history and instance task list runs this, so
+     * shipping the snapshots to the app just to read one string each would cost
+     * page size × snapshot size on every refresh. A missing instance or node, a
+     * snapshot without a `nodes` array, and a blank or non-string label all
+     * leave the task without a label, as `readWorkflowNodeLabel` does.
+     */
+    async readTaskNodeLabels(tasks) {
+        // The table as the entity reads it, so a configured `schema` is honoured
+        // here exactly as it is by every repository read of the instance.
+        const { metadata } = this.approvalInstanceRepository;
+        const { driver } = this.approvalInstanceRepository.manager.connection;
+        const instanceTable = [metadata.schema, metadata.tableName]
+            .filter((part) => Boolean(part))
+            .map((part) => driver.escape(part))
+            .join('.');
+        const rows = await this.approvalInstanceRepository.query(`SELECT instance.id AS "instanceId",
+              node->>'id' AS "nodeId",
+              CASE WHEN jsonb_typeof(node->'data'->'label') = 'string'
+                   THEN node->'data'->>'label' END AS "label"
+         FROM ${instanceTable} AS instance
+        CROSS JOIN LATERAL jsonb_array_elements(
+              CASE WHEN jsonb_typeof(instance.workflow_snapshot->'nodes') = 'array'
+                   THEN instance.workflow_snapshot->'nodes'
+                   ELSE '[]'::jsonb END
+            ) AS node
+        WHERE instance.id = ANY($1::uuid[])
+          AND node->>'id' = ANY($2::text[])`, [
+            [...new Set(tasks.map((task) => task.instanceId))],
+            [...new Set(tasks.map((task) => task.nodeId))],
+        ]);
+        return new Map(rows.flatMap((row) => typeof row.label === 'string' && row.label.trim()
+            ? [[readNodeLabelKey(row.instanceId, row.nodeId), row.label]]
+            : []));
+    }
     async readDefaultInitiatorMetadataSnapshot(memberId) {
-        const today = toDateOnlyString(new Date());
+        const today = this.readOrganizationToday();
         const memberships = (await this.approvalInstanceRepository.manager
             .getRepository(membership_entity_1.MembershipEntity)
             .find({ where: { memberId } }))
@@ -1950,7 +2077,10 @@ let WorkflowEngineService = class WorkflowEngineService {
         return task;
     }
     async isApprovalInstanceReadableByMember(instance, memberId) {
-        if (instance.initiatorMemberId === memberId) {
+        // The member who filed the document on the applicant's behalf can read it
+        // back; resubmit and cancel stay with the initiator.
+        if (instance.initiatorMemberId === memberId ||
+            (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) === memberId) {
             return true;
         }
         const tasks = await this.taskRepository.find({
@@ -2157,6 +2287,12 @@ let WorkflowEngineService = class WorkflowEngineService {
         });
     }
     async skipNode(manager, instance, token, node, reason) {
+        // A NOTIFY node is an asynchronous branch that may not have an outgoing
+        // edge, so a skipped one ends its branch exactly as an executed one does:
+        // the token is consumed instead of advanced (advancing would throw "has no
+        // outgoing edge" and fail the whole submission). Instance completion is
+        // evaluated by `processRunningInstance` once no ACTIVE token remains.
+        const consumesToken = (0, workflow_graph_1.isAsyncNotifyServiceTask)(node);
         await manager.getRepository(activity_log_entity_1.ActivityLogEntity).save(manager.getRepository(activity_log_entity_1.ActivityLogEntity).create({
             actorMemberId: null,
             eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED,
@@ -2164,12 +2300,24 @@ let WorkflowEngineService = class WorkflowEngineService {
             nodeId: node.id,
             payload: {
                 ...reason,
+                ...(consumesToken ? { consumed: true } : {}),
                 tokenId: token.id,
             },
             taskId: null,
         }));
+        if (consumesToken) {
+            await this.consumeToken(manager, token);
+            return;
+        }
         await this.advanceTokenToOutgoingNodes(manager, instance, token, node);
     }
+    async consumeToken(manager, token) {
+        await manager.getRepository(workflow_token_entity_1.WorkflowTokenEntity).save({
+            ...token,
+            consumedAt: new Date(),
+            status: workflow_engine_enums_1.WorkflowTokenStatusEnum.CONSUMED,
+        });
+    }
     async readAvailableOutgoingEdges(manager, instance, node) {
         const outgoingEdges = readOutgoingEdgesOrThrow(instance.workflowSnapshot, node.id);
         const conditionalEdges = outgoingEdges.filter((edge) => !edge.data.isDefault && edgeHasCondition(edge));
@@ -2361,14 +2509,15 @@ let WorkflowEngineService = class WorkflowEngineService {
             });
             return;
         }
-        const candidates = await this.resolveRuntimeTaskCandidates(manager, instance, node);
+        const resolvedCandidates = await this.resolveRuntimeTaskCandidates(manager, instance, node);
         // The initiator was the only approver and the node asks to be skipped in
         // that case: no task, the token moves on. Pending countersign directives
         // stay pending for the next user task that actually gets created.
-        if (candidates === null) {
+        if (resolvedCandidates === null) {
             await this.skipNodeByInitiatorExclusion(manager, instance, token, node);
             return;
         }
+        const { candidates, skippedDelegations } = resolvedCandidates;
         const primaryCandidate = candidates[0];
         // Legacy snapshots may carry no policy at all; they behave as before.
         const decisionPolicy = node.data.decisionPolicy;
@@ -2441,6 +2590,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                         sequentialCandidateMemberIds: savedCandidates.map((candidate) => candidate.memberId),
                     }
                     : {}),
+                ...(skippedDelegations.length > 0 ? { skippedDelegations } : {}),
                 tokenId: token.id,
             },
             taskId: task.id,
@@ -2481,11 +2631,13 @@ let WorkflowEngineService = class WorkflowEngineService {
         const now = new Date();
         // Delegation was resolved when the task was created; the candidate may have
         // gained a delegate while waiting, so resolve it again for the new turn.
-        const delegation = await this.resolveActivationDelegation({
+        const { skippedDelegation, ...delegation } = await this.resolveActivationDelegation({
             candidate: nextCandidate,
             candidates,
             excludesInitiator: isInitiatorExcluded(node),
+            gradeGated: isGradeGatedCandidate(node, nextCandidate.sourceType),
             instance,
+            manager,
             nodeId: task.nodeId,
         });
         const activatedCandidate = await manager
@@ -2525,6 +2677,9 @@ let WorkflowEngineService = class WorkflowEngineService {
                 originalMemberId: activatedCandidate.originalMemberId,
                 previousMemberId,
                 sequence: activatedCandidate.sequence,
+                ...(skippedDelegation
+                    ? { skippedDelegations: [skippedDelegation] }
+                    : {}),
                 tokenId: task.tokenId,
             },
             taskId: task.id,
@@ -2542,29 +2697,31 @@ let WorkflowEngineService = class WorkflowEngineService {
      * are kept: (task_id, member_id) is unique, and that member signs from the
      * row they already have. On a node that excludes the initiator the stored
      * values are kept as well when the new delegation path would run through the
-     * initiator: creation already filtered such paths out, and a delegation added
-     * while the candidate waited must not bring them back.
+     * initiator or the submitter: creation already filtered such paths out, and a
+     * delegation added while the candidate waited must not bring them back.
      */
-    async resolveActivationDelegation({ candidate, candidates, excludesInitiator, instance, nodeId, }) {
+    async resolveActivationDelegation({ candidate, candidates, excludesInitiator, gradeGated, instance, manager, nodeId, }) {
         const stored = {
             delegationChain: candidate.delegationChain,
             memberId: candidate.memberId,
         };
-        const resolution = await this.delegationService.resolveAssignee(candidate.originalMemberId, this.buildDelegationContext(instance, nodeId));
+        const { skippedDelegation, ...resolution } = await this.resolveDelegation(manager, candidate.originalMemberId, this.buildDelegationContext(instance, nodeId), gradeGated);
         const collides = candidates.some((other) => other.id !== candidate.id &&
             other.memberId === resolution.finalAssigneeMemberId);
         if (collides ||
             (excludesInitiator &&
-                isInitiatorOnCandidatePath({
+                isExcludedMemberOnCandidatePath({
                     delegationChain: resolution.delegationChain,
                     memberId: resolution.finalAssigneeMemberId,
                     originalMemberId: candidate.originalMemberId,
-                }, instance.initiatorMemberId))) {
-            return stored;
+                }, readInitiatorAndSubmitter(instance)))) {
+            // The refusal happened even though the stored values are kept.
+            return { ...stored, ...(skippedDelegation ? { skippedDelegation } : {}) };
         }
         return {
             delegationChain: resolution.delegationChain,
             memberId: resolution.finalAssigneeMemberId,
+            ...(skippedDelegation ? { skippedDelegation } : {}),
         };
     }
     async markTaskCandidateDecision({ action, candidate, candidates, decidedAt, manager, task, }) {
@@ -2802,12 +2959,16 @@ let WorkflowEngineService = class WorkflowEngineService {
      */
     async resolveRuntimeTaskCandidates(manager, instance, node) {
         const label = `簽核節點「${node.data.label}」`;
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label);
-        const delegatedCandidates = await this.delegateResolvedCandidates(instance, node.id, resolvedCandidates);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', isInitiatorExcluded(node) ? readInitiatorAndSubmitter(instance) : []);
+        const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, isOrgManagerChainNode(node));
         const excludeInitiator = node.data.excludeInitiator;
-        const uniqueCandidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), instance.initiatorMemberId);
+        const hasSubmitter = (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) !== null;
+        const uniqueCandidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance));
         if (uniqueCandidates.length > 0) {
-            return uniqueCandidates;
+            return {
+                candidates: uniqueCandidates,
+                skippedDelegations: collectSkippedDelegations(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance)),
+            };
         }
         // Only the initiator was left — what the node does about it is configured.
         // Nothing resolved to begin with is the ordinary failure below.
@@ -2819,23 +2980,31 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         if (excludeInitiator.whenEmpty === 'INITIATOR_MANAGER') {
             const managerCandidates = await this.resolveInitiatorManagerReplacements(manager, instance, node);
-            if (managerCandidates.length > 0) {
+            if (managerCandidates.candidates.length > 0) {
                 return managerCandidates;
             }
-            throw new common_1.ConflictException(`${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人，此節點不允許申請人自簽，且找不到申請人的主管可改派。`);
+            throw new common_1.ConflictException(hasSubmitter
+                ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人，此節點不允許申請人或代送人簽核，且找不到申請人的主管可改派。`
+                : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人，此節點不允許申請人自簽，且找不到申請人的主管可改派。`);
         }
-        throw new common_1.ConflictException(`${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
+        throw new common_1.ConflictException(hasSubmitter
+            ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人（含委派後的代理人），且此節點不允許申請人或代送人簽核。`
+            : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
     }
     async resolveInitiatorManagerReplacements(manager, instance, node) {
-        // The initiator's own direct manager: the closest org unit only, and the
-        // initiator himself (a unit head) is skipped so resolution falls through
-        // to the next tier instead of ending on him.
-        const managerMemberIds = await this.resolveDirectManagerMemberIds(manager, instance.initiatorMemberId, toDateOnlyString(new Date()), true, instance.initiatorMemberId);
-        const delegatedCandidates = await this.delegateResolvedCandidates(instance, node.id, managerMemberIds.map((memberId) => ({
+        // The initiator's own direct manager: the closest org unit only. The
+        // initiator himself (a unit head) and the member who submitted for him are
+        // skipped before the tier is chosen, so resolution falls through to the
+        // next tier instead of ending on either of them.
+        const managerMemberIds = await this.resolveDirectManagerMemberIds(manager, instance.initiatorMemberId, this.readOrganizationToday(), true, readInitiatorAndSubmitter(instance));
+        const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, managerMemberIds.map((memberId) => ({
             memberId,
             sourceType: 'EXCLUDE_INITIATOR_MANAGER',
-        })));
-        return selectNodeCandidates(delegatedCandidates, true, instance.initiatorMemberId);
+        })), isOrgManagerChainNode(node));
+        return {
+            candidates: selectNodeCandidates(delegatedCandidates, true, readInitiatorAndSubmitter(instance)),
+            skippedDelegations: collectSkippedDelegations(delegatedCandidates, true, readInitiatorAndSubmitter(instance)),
+        };
     }
     buildDelegationContext(instance, nodeId) {
         return {
@@ -2852,48 +3021,86 @@ let WorkflowEngineService = class WorkflowEngineService {
     }
     // Not deduplicated: a node that excludes the initiator filters first, so a
     // first-seen entry that must be dropped cannot shadow a legitimate one.
-    async delegateResolvedCandidates(instance, nodeId, resolvedCandidates) {
+    async delegateResolvedCandidates(manager, instance, nodeId, resolvedCandidates, gradeGated) {
         const context = this.buildDelegationContext(instance, nodeId);
-        const delegatedCandidates = await Promise.all(resolvedCandidates.map(async (candidate) => {
-            const delegationResolution = await this.delegationService.resolveAssignee(candidate.memberId, context);
+        const resolved = await Promise.all(resolvedCandidates.map(async (candidate) => ({
+            candidate,
+            resolution: await this.delegationService.resolveAssignee(candidate.memberId, context),
+        })));
+        // One batch of grade lookups for the whole node, not two per delegate.
+        const levels = gradeGated
+            ? await this.readMemberPositionLevels(manager, resolved.flatMap(({ candidate, resolution }) => readGradeGateMemberIds(candidate.memberId, resolution)), this.readOrganizationToday())
+            : new Map();
+        return resolved.map(({ candidate, resolution }) => {
+            const { skippedDelegation, ...delegationResolution } = applyGradeGate(candidate.memberId, resolution, gradeGated, levels);
             return {
                 delegationChain: delegationResolution.delegationChain,
                 memberId: delegationResolution.finalAssigneeMemberId,
                 originalMemberId: candidate.memberId,
+                ...(skippedDelegation ? { skippedDelegation } : {}),
                 sourceType: candidate.sourceType,
             };
-        }));
-        return delegatedCandidates;
+        });
     }
-    async resolveApproverResolver(manager, instance, resolver, label) {
+    /** One member's delegation, grade-gated as {@link applyGradeGate} says. */
+    async resolveDelegation(manager, principalMemberId, context, gradeGated) {
+        const resolution = await this.delegationService.resolveAssignee(principalMemberId, context);
+        const memberIds = gradeGated
+            ? readGradeGateMemberIds(principalMemberId, resolution)
+            : [];
+        const levels = memberIds.length > 0
+            ? await this.readMemberPositionLevels(manager, memberIds, this.readOrganizationToday())
+            : new Map();
+        return applyGradeGate(principalMemberId, resolution, gradeGated, levels);
+    }
+    /**
+     * Manual transfer on a manager-chain node: the target must hold at least the
+     * grade of the member being replaced, i.e. the original principal of the
+     * deciding candidate (the first hop of its delegation chain when it was
+     * delegated, otherwise the actor). No grade on the principal means no
+     * constraint.
+     */
+    async assertTransferTargetGrade(manager, { actorMemberId, delegationChain, label, targetMemberId, }) {
+        const principalMemberId = readDelegationSteps(delegationChain)[0]?.from ?? actorMemberId;
+        const date = this.readOrganizationToday();
+        const requiredLevel = await this.readMemberPositionLevel(manager, principalMemberId, date);
+        if (requiredLevel === null) {
+            return;
+        }
+        const targetLevel = await this.readMemberPositionLevel(manager, targetMemberId, date);
+        if (targetLevel === null || targetLevel < requiredLevel) {
+            throw new common_1.ForbiddenException(`簽核節點「${label}」需由職等 ${requiredLevel} 以上的成員簽核，不能轉簽給職等不足的成員`);
+        }
+    }
+    async resolveApproverResolver(manager, instance, resolver, label, subject = '簽核人', skippedChainMemberIds = []) {
         if (resolver.type === 'DIRECT') {
-            return readMemberIdsFromValue(resolver.memberIds, label).map((memberId) => ({ memberId, sourceType: resolver.type }));
+            return readMemberIdsFromValue(resolver.memberIds, label, subject).map((memberId) => ({ memberId, sourceType: resolver.type }));
         }
         if (resolver.type === 'DYNAMIC_FORM') {
-            return readMemberIdsFromValue(readValueAtPath(instance.formData, resolver.formPath), `${label}.formPath`).map((memberId) => ({ memberId, sourceType: resolver.type }));
+            return readMemberIdsFromValue(readValueAtPath(instance.formData, resolver.formPath), label, subject, `依表單欄位「${resolver.formPath}」`).map((memberId) => ({ memberId, sourceType: resolver.type }));
         }
         if (resolver.type === 'EXPRESSION') {
-            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, buildWorkflowExpressionContext(instance), `${label}.expression`), `${label}.expression`).map((memberId) => ({ memberId, sourceType: resolver.type }));
+            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, buildWorkflowExpressionContext(instance), `${label}.expression`), label, subject, '依運算式').map((memberId) => ({ memberId, sourceType: resolver.type }));
         }
         if (resolver.type === 'POSITION') {
-            return this.resolvePositionCandidates(manager, resolver.positionId, label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolvePositionCandidates(manager, resolver.positionId, label, subject).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
         }
         if (resolver.type === 'ORG_UNIT_MEMBER') {
-            return this.resolveOrgUnitMemberCandidates(manager, resolver.orgUnitId, Boolean(resolver.includeDescendants), label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolveOrgUnitMemberCandidates(manager, resolver.orgUnitId, Boolean(resolver.includeDescendants), label, subject).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
         }
         if (resolver.type === 'ORG_UNIT_POSITION') {
-            return this.resolveOrgUnitPositionCandidates(manager, resolver.orgUnitId, resolver.positionId, Boolean(resolver.includeDescendants), label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolveOrgUnitPositionCandidates(manager, resolver.orgUnitId, resolver.positionId, Boolean(resolver.includeDescendants), label, subject).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, resolver.preferClosestOrgUnit === true).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolveOrgUnitManagerCandidates(manager, instance, resolver.orgUnitId, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
         }
         if (resolver.type === 'ORG_MANAGER_CHAIN') {
-            return this.resolveOrgManagerChainCandidates(manager, instance, resolver.minPositionLevel, resolver.fallback, label).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
+            return this.resolveOrgManagerChainCandidates(manager, instance, resolver.minPositionLevel, resolver.fallback, label, subject, skippedChainMemberIds).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 })));
+        return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject).then((memberIds) => memberIds.map((memberId) => ({ memberId, sourceType: resolver.type })));
     }
-    async resolvePositionCandidates(manager, positionId, label) {
-        const today = toDateOnlyString(new Date());
+    async resolvePositionCandidates(manager, positionId, label, subject) {
+        const today = this.readOrganizationToday();
         const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
             where: { positionId },
         });
@@ -2907,27 +3114,28 @@ let WorkflowEngineService = class WorkflowEngineService {
             return second.effectiveFrom.localeCompare(first.effectiveFrom);
         });
         if (!activeMemberships.length) {
-            throw new common_1.ConflictException(`${label} position ${positionId} has no active membership`);
+            throw new common_1.ConflictException(`${label} 找不到${subject}：職位「${await this.readPositionName(manager, positionId)}」目前沒有任何有效成員`);
         }
         return uniqueTexts(activeMemberships.map((membership) => membership.memberId));
     }
-    async resolveInitiatorManagerCandidates(manager, instance, levelsUp, fallback, label, preferClosestOrgUnit) {
+    async resolveInitiatorManagerCandidates(manager, instance, levelsUp, fallback, label, preferClosestOrgUnit, subject) {
         const normalizedLevelsUp = Math.max(Math.trunc(levelsUp), 1);
         const resolvedManagerMemberIds = await this.resolveManagerMemberIdsFromOrganization(manager, instance.initiatorMemberId, normalizedLevelsUp, preferClosestOrgUnit);
         if (resolvedManagerMemberIds.length) {
             return resolvedManagerMemberIds;
         }
         return [
-            this.resolveFallbackAssignee(instance, fallback, label, `找不到發起人的第 ${normalizedLevelsUp} 層主管`),
+            this.resolveFallbackAssignee(instance, fallback, label, subject, `找不到發起人的第 ${normalizedLevelsUp} 層主管`),
         ];
     }
     /**
      * Walks up the initiator's manager chain, nearest manager first, until a
      * manager whose position level reaches `minPositionLevel` is added. The
-     * list is returned nearest manager first.
+     * list is returned nearest manager first. Members in `skippedMemberIds` are
+     * walked past without joining the chain or counting as the stopping point.
      */
-    async resolveOrgManagerChainCandidates(manager, instance, minPositionLevel, fallback, label) {
-        const date = toDateOnlyString(new Date());
+    async resolveOrgManagerChainCandidates(manager, instance, minPositionLevel, fallback, label, subject, skippedMemberIds) {
+        const date = this.readOrganizationToday();
         const visitedMemberIds = new Set([instance.initiatorMemberId]);
         const chain = [];
         let currentMemberId = instance.initiatorMemberId;
@@ -2938,7 +3146,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             // excluded from his own candidates: a unit head belongs to the unit he
             // heads, so without this his unit rule would name himself and the walk
             // could never climb past him.
-            const directManagerMemberIds = await this.resolveDirectManagerMemberIds(manager, currentMemberId, date, true, currentMemberId);
+            const directManagerMemberIds = await this.resolveDirectManagerMemberIds(manager, currentMemberId, date, true, [currentMemberId]);
             if (directManagerMemberIds.length === 0) {
                 break;
             }
@@ -2952,6 +3160,12 @@ let WorkflowEngineService = class WorkflowEngineService {
             }
             visitedMemberIds.add(managerMemberId);
             currentMemberId = managerMemberId;
+            // A member the node keeps out (the person who filed the document) is
+            // climbed through, not stopped at: filtering him after the walk would
+            // lose the chain when he is the manager that reaches the level.
+            if (skippedMemberIds.includes(managerMemberId)) {
+                continue;
+            }
             const level = await this.readMemberPositionLevel(manager, managerMemberId, date);
             if (level === null ||
                 (lastAddedLevel !== null && level <= lastAddedLevel)) {
@@ -2963,45 +3177,60 @@ let WorkflowEngineService = class WorkflowEngineService {
                 return chain;
             }
         }
-        const fallbackMemberId = this.resolveFallbackAssignee(instance, fallback, label, `沿主管鏈找不到職等達 ${minPositionLevel} 的主管`);
+        const fallbackMemberId = this.resolveFallbackAssignee(instance, fallback, label, subject, `沿主管鏈找不到職等達 ${minPositionLevel} 的主管`);
         return chain.includes(fallbackMemberId)
             ? chain
             : [...chain, fallbackMemberId];
     }
     /** Highest position level over the member's active memberships, or `null`. */
     async readMemberPositionLevel(manager, memberId, date) {
-        const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
-            where: { memberId },
-        });
-        const positionIds = uniqueTexts(memberships
-            .filter((membership) => isDateRangeActive(membership, date))
-            .map((membership) => membership.positionId)
-            .filter((positionId) => Boolean(positionId)));
-        if (positionIds.length === 0) {
-            return null;
-        }
-        const positions = await manager.getRepository(position_entity_1.PositionEntity).find({
-            where: { id: (0, typeorm_2.In)([...positionIds]) },
-        });
-        return positions.length === 0
-            ? null
-            : Math.max(...positions.map((position) => position.level));
+        return ((await this.readMemberPositionLevels(manager, [memberId], date)).get(memberId) ?? null);
+    }
+    /**
+     * {@link readMemberPositionLevel} for several members in two queries: every
+     * requested member is in the map, `null` when they hold no graded position.
+     */
+    async readMemberPositionLevels(manager, memberIds, date) {
+        const uniqueMemberIds = uniqueTexts(memberIds);
+        if (uniqueMemberIds.length === 0) {
+            return new Map();
+        }
+        const memberships = (await manager.getRepository(membership_entity_1.MembershipEntity).find({
+            where: { memberId: (0, typeorm_2.In)([...uniqueMemberIds]) },
+        })).filter((membership) => Boolean(membership.positionId) && isDateRangeActive(membership, date));
+        const positionIds = uniqueTexts(memberships.map((membership) => membership.positionId ?? ''));
+        const positions = positionIds.length === 0
+            ? []
+            : await manager.getRepository(position_entity_1.PositionEntity).find({
+                where: { id: (0, typeorm_2.In)([...positionIds]) },
+            });
+        const levelByPositionId = new Map(positions.map((position) => [position.id, position.level]));
+        return new Map(uniqueMemberIds.map((memberId) => {
+            const levels = memberships
+                .filter((membership) => membership.memberId === memberId)
+                .flatMap((membership) => {
+                const level = levelByPositionId.get(membership.positionId ?? '');
+                return level === undefined ? [] : [level];
+            });
+            return [memberId, levels.length === 0 ? null : Math.max(...levels)];
+        }));
     }
-    resolveFallbackAssignee(instance, fallback, label, failureReason) {
+    resolveFallbackAssignee(instance, fallback, label, subject, failureReason) {
+        const failure = subject === '通知對象' ? '無法建立通知' : '無法建立待簽任務';
         if (!fallback || fallback.type === 'NONE') {
-            throw new common_1.ConflictException(`${label} 無法建立待簽任務：${failureReason}，且未設定改派固定人。請聯絡流程管理員調整主管規則或模板 fallback。`);
+            throw new common_1.ConflictException(`${label} ${failure}：${failureReason}，且未設定改派固定人。請聯絡流程管理員調整主管規則或模板 fallback。`);
         }
         if (!fallback.memberId.trim()) {
-            throw new common_1.ConflictException(`${label} 無法建立待簽任務：改派固定人未設定。`);
+            throw new common_1.ConflictException(`${label} ${failure}：改派固定人未設定。`);
         }
         if (fallback.memberId === instance.initiatorMemberId &&
             !fallback.allowInitiatorSelfApproval) {
-            throw new common_1.ConflictException(`${label} 無法建立待簽任務：改派固定人是申請人本人，且此節點未允許申請人自簽。`);
+            throw new common_1.ConflictException(`${label} ${failure}：改派固定人是申請人本人，且此節點未允許申請人自簽。`);
         }
         return fallback.memberId;
     }
     async resolveManagerMemberIdsFromOrganization(manager, memberId, levelsUp, preferClosestOrgUnit) {
-        return this.resolveManagerMemberIdsAtLevel(manager, memberId, toDateOnlyString(new Date()), levelsUp, preferClosestOrgUnit);
+        return this.resolveManagerMemberIdsAtLevel(manager, memberId, this.readOrganizationToday(), levelsUp, preferClosestOrgUnit);
     }
     async resolveManagerMemberIdsAtLevel(manager, memberId, date, remainingLevels, preferClosestOrgUnit) {
         const directManagerMemberIds = await this.resolveDirectManagerMemberIds(manager, memberId, date, preferClosestOrgUnit);
@@ -3011,7 +3240,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         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, preferClosestOrgUnit, excludedManagerMemberId) {
+    async resolveDirectManagerMemberIds(manager, memberId, date, preferClosestOrgUnit, excludedManagerMemberIds = []) {
         const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
             where: { memberId },
         });
@@ -3032,10 +3261,10 @@ let WorkflowEngineService = class WorkflowEngineService {
                 scopeType: organization_enums_1.ManagerResolutionScopeTypeEnum.POSITION,
             })),
         ];
-        return this.resolveManagerResolutionCandidates(manager, candidatePairs, date, readOrgUnitDepthMap(orgUnits), preferClosestOrgUnit, excludedManagerMemberId);
+        return this.resolveManagerResolutionCandidates(manager, candidatePairs, date, readOrgUnitDepthMap(orgUnits), preferClosestOrgUnit, excludedManagerMemberIds);
     }
-    async resolveOrgUnitManagerCandidates(manager, instance, orgUnitId, fallback, label, preferClosestOrgUnit) {
-        const date = toDateOnlyString(new Date());
+    async resolveOrgUnitManagerCandidates(manager, instance, orgUnitId, fallback, label, preferClosestOrgUnit, subject) {
+        const date = this.readOrganizationToday();
         const orgUnits = await this.readOrgUnitAndAncestors(manager, [orgUnitId]);
         const managerMemberIds = await this.resolveManagerResolutionCandidates(manager, orgUnits.map((orgUnit) => ({
             scopeId: orgUnit.id,
@@ -3043,7 +3272,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         })), date, readOrgUnitDepthMap(orgUnits), preferClosestOrgUnit);
         if (!managerMemberIds.length) {
             return [
-                this.resolveFallbackAssignee(instance, fallback, label, `找不到指定組織的主管規則`),
+                this.resolveFallbackAssignee(instance, fallback, label, subject, `找不到指定組織的主管規則`),
             ];
         }
         return managerMemberIds;
@@ -3064,7 +3293,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         const byId = new Map([...directOrgUnits, ...ancestorGroups.flat()].map((orgUnit) => [orgUnit.id, orgUnit]));
         return [...byId.values()];
     }
-    async resolveManagerResolutionCandidates(manager, candidatePairs, date, orgUnitDepths, preferClosestOrgUnit, excludedManagerMemberId) {
+    async resolveManagerResolutionCandidates(manager, candidatePairs, date, orgUnitDepths, preferClosestOrgUnit, excludedManagerMemberIds = []) {
         const scopeIds = candidatePairs.map((pair) => pair.scopeId);
         if (!scopeIds.length) {
             return [];
@@ -3088,58 +3317,78 @@ let WorkflowEngineService = class WorkflowEngineService {
             .filter((resolution) => isDateRangeActive(resolution, date))
             // Dropped before the top-priority tier is chosen, so resolution falls
             // through to the next tier instead of ending on the excluded member.
-            .filter((resolution) => excludedManagerMemberId === undefined ||
-            resolution.managerMemberId !== excludedManagerMemberId)
+            .filter((resolution) => !excludedManagerMemberIds.includes(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);
-        const today = toDateOnlyString(new Date());
+    async resolveOrgUnitMemberCandidates(manager, orgUnitId, includeDescendants, label, subject) {
+        const scope = await this.readOrgUnitScope(manager, orgUnitId, includeDescendants);
+        if (!scope) {
+            throw new common_1.ConflictException(readMissingOrgUnitMessage(label, subject, orgUnitId));
+        }
+        const today = this.readOrganizationToday();
         const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
-            where: { orgUnitId: (0, typeorm_2.In)([...orgUnitIds]) },
+            where: { orgUnitId: (0, typeorm_2.In)([...scope.orgUnitIds]) },
         });
         const memberIds = memberships
             .filter((membership) => isDateRangeActive(membership, today))
             .sort(compareMembership)
             .map((membership) => membership.memberId);
         if (memberIds.length === 0) {
-            throw new common_1.ConflictException(`${label} orgUnit ${orgUnitId} has no active member`);
+            throw new common_1.ConflictException(`${label} 找不到${subject}：組織「${scope.name}」目前沒有任何有效成員，請先將人員加入該組織`);
         }
         return uniqueTexts(memberIds);
     }
-    async resolveOrgUnitPositionCandidates(manager, orgUnitId, positionId, includeDescendants, label) {
-        const orgUnitIds = await this.readOrgUnitScopeIds(manager, orgUnitId, includeDescendants);
-        const today = toDateOnlyString(new Date());
+    async resolveOrgUnitPositionCandidates(manager, orgUnitId, positionId, includeDescendants, label, subject) {
+        const scope = await this.readOrgUnitScope(manager, orgUnitId, includeDescendants);
+        if (!scope) {
+            throw new common_1.ConflictException(readMissingOrgUnitMessage(label, subject, orgUnitId));
+        }
+        const today = this.readOrganizationToday();
         const memberships = await manager.getRepository(membership_entity_1.MembershipEntity).find({
-            where: { orgUnitId: (0, typeorm_2.In)([...orgUnitIds]), positionId },
+            where: { orgUnitId: (0, typeorm_2.In)([...scope.orgUnitIds]), positionId },
         });
         const memberIds = memberships
             .filter((membership) => isDateRangeActive(membership, today))
             .sort(compareMembership)
             .map((membership) => membership.memberId);
         if (memberIds.length === 0) {
-            throw new common_1.ConflictException(`${label} orgUnit ${orgUnitId} and position ${positionId} has no active membership`);
+            throw new common_1.ConflictException(`${label} 找不到${subject}：組織「${scope.name}」的職位「${await this.readPositionName(manager, positionId)}」目前沒有任何有效成員`);
         }
         return uniqueTexts(memberIds);
     }
-    async readOrgUnitScopeIds(manager, orgUnitId, includeDescendants) {
+    // Names only make an error readable, so a row that has gone missing falls
+    // back to its id instead of hiding the real problem.
+    async readPositionName(manager, positionId) {
+        const position = await manager
+            .getRepository(position_entity_1.PositionEntity)
+            .findOne({ where: { id: positionId } });
+        return position?.name ?? positionId;
+    }
+    /** The org unit's name and the ids it covers, or `null` once it is gone. */
+    async readOrgUnitScope(manager, orgUnitId, includeDescendants) {
         const orgUnitRepository = manager.getRepository(org_unit_entity_1.OrgUnitEntity);
         const orgUnit = await orgUnitRepository.findOne({
             where: { deletedAt: (0, typeorm_2.IsNull)(), id: orgUnitId },
         });
         if (!orgUnit) {
-            throw new common_1.ConflictException(`Org unit ${orgUnitId} was not found`);
+            return null;
         }
         if (!includeDescendants) {
-            return [orgUnit.id];
+            return { name: orgUnit.name, orgUnitIds: [orgUnit.id] };
         }
         const descendants = await orgUnitRepository
             .createQueryBuilder('orgUnit')
             .where('orgUnit.deleted_at IS NULL')
             .andWhere('orgUnit.path <@ :path', { path: orgUnit.path })
             .getMany();
-        return uniqueTexts([orgUnit.id, ...descendants.map((unit) => unit.id)]);
+        return {
+            name: orgUnit.name,
+            orgUnitIds: uniqueTexts([
+                orgUnit.id,
+                ...descendants.map((unit) => unit.id),
+            ]),
+        };
     }
     async processExclusiveGateway(manager, instance, token, node) {
         if (node.data.direction !== 'split') {
@@ -3221,7 +3470,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         const recipients = (0, workflow_graph_1.isNotifyRecipientsEmpty)(action.recipients) &&
             (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
             ? []
-            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`);
+            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`, '通知對象');
         const recipientMemberIds = uniqueTexts(recipients.map((recipient) => recipient.memberId));
         await this.notificationService.createServiceTaskNotifications({
             instance,
@@ -3249,11 +3498,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                 tokenId: token.id,
             }, action.webhooks)
             : [];
-        await manager.getRepository(workflow_token_entity_1.WorkflowTokenEntity).save({
-            ...token,
-            consumedAt: new Date(),
-            status: workflow_engine_enums_1.WorkflowTokenStatusEnum.CONSUMED,
-        });
+        await this.consumeToken(manager, token);
         await activityRepository.save(activityRepository.create({
             actorMemberId: null,
             eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED,
@@ -3780,6 +4025,58 @@ function buildDryRunExpressionContext(input, lastDecision) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+// The members whose grades decide a grade-gated delegation: none when the
+// delegation leaves the seat with its principal.
+function readGradeGateMemberIds(principalMemberId, resolution) {
+    return resolution.finalAssigneeMemberId === principalMemberId
+        ? []
+        : [principalMemberId, resolution.finalAssigneeMemberId];
+}
+/**
+ * On a manager-chain node the delegate must hold at least the grade of the
+ * member they replace: anything lower is not applied, the member stays and
+ * the refused delegation is returned so it can be recorded. Resolution does
+ * not walk further down the delegation chain once it has been refused. A
+ * member without a grade (or a delegate that stays the member) is never
+ * constrained. `levels` holds the grades of `readGradeGateMemberIds`.
+ */
+function applyGradeGate(principalMemberId, resolution, gradeGated, levels) {
+    if (!gradeGated || resolution.finalAssigneeMemberId === principalMemberId) {
+        return resolution;
+    }
+    const principalLevel = levels.get(principalMemberId) ?? null;
+    if (principalLevel === null) {
+        return resolution;
+    }
+    const agentLevel = levels.get(resolution.finalAssigneeMemberId) ?? null;
+    if (agentLevel !== null && agentLevel >= principalLevel) {
+        return resolution;
+    }
+    return {
+        delegationChain: [],
+        finalAssigneeMemberId: principalMemberId,
+        skippedDelegation: {
+            agentLevel,
+            agentMemberId: resolution.finalAssigneeMemberId,
+            principalLevel,
+            principalMemberId,
+            reason: 'AGENT_POSITION_LEVEL_TOO_LOW',
+        },
+    };
+}
+function readNodeLabelKey(instanceId, nodeId) {
+    return `${instanceId}\u0000${nodeId}`;
+}
+/**
+ * The node's display name from an instance's workflow snapshot, or `null`
+ * when the instance or node is missing, or the node carries no usable label
+ * (older snapshots).
+ */
+function readWorkflowNodeLabel(workflow, nodeId) {
+    const label = workflow?.nodes.find((candidate) => candidate.id === nodeId)
+        ?.data.label;
+    return typeof label === 'string' && label.trim() ? label : null;
+}
 function readWorkflowNodeOrThrow(workflow, nodeId) {
     const node = workflow.nodes.find((candidate) => candidate.id === nodeId);
     if (!node) {
@@ -3880,22 +4177,26 @@ function edgeHasCondition(edge) {
     return Boolean(edge.data.condition?.trim() ||
         (edge.data.conditionFieldKey && edge.data.conditionOperator));
 }
-function readMemberIdFromValue(value, label) {
-    return readMemberIdsFromValue(value, label)[0] ?? '';
+function readMissingOrgUnitMessage(label, subject, orgUnitId) {
+    return `${label} 找不到${subject}：組織（${orgUnitId}）已不存在，請在流程設計器重新選擇組織`;
 }
-function readMemberIdsFromValue(value, label) {
+function findMemberIdsInValue(value) {
     if (typeof value === 'string' && value.trim()) {
         return [value.trim()];
     }
     if (Array.isArray(value)) {
-        const memberIds = value
+        return uniqueTexts(value
             .filter((candidate) => typeof candidate === 'string' && Boolean(candidate.trim()))
-            .map((candidate) => candidate.trim());
-        if (memberIds.length > 0) {
-            return uniqueTexts(memberIds);
-        }
+            .map((candidate) => candidate.trim()));
+    }
+    return [];
+}
+function readMemberIdsFromValue(value, label, subject = '簽核人', source = '') {
+    const memberIds = findMemberIdsInValue(value);
+    if (memberIds.length === 0) {
+        throw new common_1.ConflictException(`${label} ${source}找不到${subject}`);
     }
-    throw new common_1.ConflictException(`${label} did not resolve to a member id`);
+    return memberIds;
 }
 function uniqueTexts(values) {
     return [...new Set(values.filter((value) => value.trim()))];
@@ -3921,20 +4222,62 @@ function isOrderedSequentialTask(task, candidates) {
 function isInitiatorExcluded(node) {
     return Boolean(node.data.excludeInitiator);
 }
+// Everyone a node that excludes the initiator keeps out of its approvers: the
+// applicant and, when someone filed the document for them, that person too
+// (authority rule: the creator must not approve what they created).
+function readInitiatorAndSubmitter(instance) {
+    const submitterMemberId = (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance);
+    return submitterMemberId === null
+        ? [instance.initiatorMemberId]
+        : [instance.initiatorMemberId, submitterMemberId];
+}
+function isOrgManagerChainNode(node) {
+    return node.data.approverResolver.type === 'ORG_MANAGER_CHAIN';
+}
+// Candidates of a manager-chain node that came from the chain (or replaced the
+// excluded initiator's seat); ad-hoc approvers are chosen by a person instead.
+function isGradeGatedCandidate(node, sourceType) {
+    return (isOrgManagerChainNode(node) &&
+        (sourceType === 'ORG_MANAGER_CHAIN' ||
+            sourceType === 'EXCLUDE_INITIATOR_MANAGER'));
+}
+// Source of the additive `skippedDelegations` payload field (absent when
+// nothing was refused, so existing payloads stay byte-identical). One record
+// per principal and delegate pair.
+function collectSkippedDelegations(delegatedCandidates, excludeInitiator, excludedMemberIds) {
+    const seen = new Set();
+    return delegatedCandidates.flatMap((candidate) => {
+        const skipped = candidate.skippedDelegation;
+        // A seat the initiator filter removes is not on the task, so a refusal on
+        // it has nothing to report. Rows only the dedupe drops are still on it.
+        if (!skipped ||
+            (excludeInitiator &&
+                isExcludedMemberOnCandidatePath(candidate, excludedMemberIds))) {
+            return [];
+        }
+        const key = `${skipped.principalMemberId}\u0000${skipped.agentMemberId}`;
+        if (seen.has(key)) {
+            return [];
+        }
+        seen.add(key);
+        return [skipped];
+    });
+}
 // A delegate acting for the initiator is still the initiator approving their
 // own document, so the initiator anywhere on the delegation path (the
 // pre-delegation member, any hop, or the final assignee) drops the candidate.
-function isInitiatorOnCandidatePath(candidate, initiatorMemberId) {
-    return (candidate.memberId === initiatorMemberId ||
-        candidate.originalMemberId === initiatorMemberId ||
-        candidate.delegationChain.some((step) => step.from === initiatorMemberId || step.to === initiatorMemberId));
+// The submitter is held to exactly the same rule.
+function isExcludedMemberOnCandidatePath(candidate, excludedMemberIds) {
+    return excludedMemberIds.some((excludedMemberId) => candidate.memberId === excludedMemberId ||
+        candidate.originalMemberId === excludedMemberId ||
+        candidate.delegationChain.some((step) => step.from === excludedMemberId || step.to === excludedMemberId));
 }
 // The initiator filter runs on the delegated list before the dedupe, so a
 // legitimate approver is never shadowed by an excluded entry for the same
 // final assignee. Without the exclusion this is the plain dedupe.
-function selectNodeCandidates(delegatedCandidates, excludeInitiator, initiatorMemberId) {
+function selectNodeCandidates(delegatedCandidates, excludeInitiator, excludedMemberIds) {
     return uniqueRuntimeCandidates(excludeInitiator
-        ? delegatedCandidates.filter((candidate) => !isInitiatorOnCandidatePath(candidate, initiatorMemberId))
+        ? delegatedCandidates.filter((candidate) => !isExcludedMemberOnCandidatePath(candidate, excludedMemberIds))
         : delegatedCandidates);
 }
 // A COUNT threshold above the people left would never be reached once the
@@ -4363,9 +4706,6 @@ function compareMembership(left, right) {
     }
     return right.effectiveFrom.localeCompare(left.effectiveFrom);
 }
-function toDateOnlyString(value) {
-    return value.toISOString().slice(0, 10);
-}
 function canReadAllWorkflows(scope) {
     return (scope.roles.includes('BPM_ADMIN') ||
         scope.permissions.some((permission) => WORKFLOW_READ_ALL_PERMISSIONS.has(permission)));
@@ -4396,9 +4736,26 @@ function validateSubmittedFormData(schema, formData) {
             .map((field) => field.label || field.fieldKey)
             .join(', ')}`);
     }
-    const tableErrors = visibleFields
-        .filter(form_1.isTableFieldDefinition)
-        .flatMap((field) => validateSubmittedTableValue(field, formData[field.fieldKey], isSubmittedFormFieldRequired(field, schema.fields, formData)));
+    // A `DYNAMIC_FORM` resolver reads a member value whether or not its field is
+    // visible, so a hidden field still holding a value must be well-formed too.
+    // Whether a hidden field is *required* stays a visibility question above.
+    const memberErrors = (0, form_member_value_validator_1.readSubmittedMemberValueErrors)(schema.fields.filter((field) => visibleFields.includes(field) ||
+        isSubmittedFieldValuePresent(formData[field.fieldKey])), formData);
+    if (memberErrors.length > 0) {
+        throw new common_1.BadRequestException(memberErrors.join('; '));
+    }
+    const tableErrors = [
+        ...visibleFields
+            .filter(form_1.isTableFieldDefinition)
+            .flatMap((field) => validateSubmittedTableValue(field, formData[field.fieldKey], isSubmittedFormFieldRequired(field, schema.fields, formData))),
+        // A hidden table is not "visible", but its stored value still has to be a
+        // well-formed table under the row cap: only the required / minimum checks
+        // are skipped, since nobody can fill the table in.
+        ...schema.fields
+            .filter(form_1.isTableFieldDefinition)
+            .filter((field) => field.hidden === true)
+            .flatMap((field) => validateSubmittedTableValue(field, formData[field.fieldKey], false, true)),
+    ];
     if (tableErrors.length > 0) {
         throw new common_1.BadRequestException(tableErrors.join('; '));
     }
@@ -4409,28 +4766,32 @@ function validateSubmittedFormData(schema, formData) {
  * required / shape / row count are enforced server side; `minimum`, `maxLength`
  * and friends stay a frontend hint.
  */
-function validateSubmittedTableValue(field, value, required) {
+function validateSubmittedTableValue(field, value, required, shapeOnly = false) {
     const path = `formData.${field.fieldKey}`;
     if (typeof value === 'undefined' || value === null) {
-        return required || readTableMinRows(field) > 0
-            ? [`${path} must include at least ${readTableRequiredRowCount(field)} row(s)`]
-            : [];
+        return shapeOnly
+            ? []
+            : required || readTableMinRows(field) > 0
+                ? [`${path} must include at least ${readTableRequiredRowCount(field)} row(s)`]
+                : [];
     }
     if (!Array.isArray(value)) {
         return [`${path} must be an array of rows`];
     }
-    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, `${path}[${index}]`));
+    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, `${path}[${index}]`, shapeOnly));
     // A malformed row cannot be counted against min/max meaningfully; report the
     // shape problem first so the submitter fixes the real cause.
     if (rowErrors.length > 0) {
         return rowErrors;
     }
-    return validateSubmittedTableRowCount(field, value.length, required, path);
+    return validateSubmittedTableRowCount(field, value.length, required, path, shapeOnly);
 }
-function validateSubmittedTableRowCount(field, rowCount, required, path) {
-    const minRows = required
-        ? Math.max(readTableMinRows(field), 1)
-        : readTableMinRows(field);
+function validateSubmittedTableRowCount(field, rowCount, required, path, shapeOnly = false) {
+    const minRows = shapeOnly
+        ? 0
+        : required
+            ? Math.max(readTableMinRows(field), 1)
+            : readTableMinRows(field);
     const maxRows = readTableMaxRows(field);
     return [
         ...(rowCount < minRows
@@ -4441,7 +4802,7 @@ function validateSubmittedTableRowCount(field, rowCount, required, path) {
             : []),
     ];
 }
-function validateSubmittedTableRow(field, row, path) {
+function validateSubmittedTableRow(field, row, path, shapeOnly = false) {
     if (!isRecord(row)) {
         return [`${path} must be an object`];
     }
@@ -4452,10 +4813,12 @@ function validateSubmittedTableRow(field, row, path) {
     const cellErrors = Object.entries(row)
         .filter(([columnKey, cellValue]) => columnsByKey.has(columnKey) && !(0, form_1.isFormTableCellValue)(cellValue))
         .map(([columnKey]) => `${path}.${columnKey} is not a valid cell value`);
-    const requiredErrors = field.columns
-        .filter((column) => isSubmittedTableColumnRequired(column) &&
-        !isSubmittedFieldValuePresent(readRowCellValue(row, column.fieldKey)))
-        .map((column) => `${path}.${column.fieldKey} is required`);
+    const requiredErrors = shapeOnly
+        ? []
+        : field.columns
+            .filter((column) => isSubmittedTableColumnRequired(column) &&
+            !isSubmittedFieldValuePresent(readRowCellValue(row, column.fieldKey)))
+            .map((column) => `${path}.${column.fieldKey} is required`);
     return [...unknownKeyErrors, ...cellErrors, ...requiredErrors];
 }
 /**
@@ -4500,6 +4863,11 @@ function isFormDefinitionSchema(value) {
         value.fields.every((field) => isRecord(field)));
 }
 function isSubmittedFormFieldVisible(field, fields, values) {
+    // A hidden (store-only) field is never shown, so nobody can fill it in:
+    // treat it like a false `visibleWhen`. Its submitted value is still kept.
+    if (field.hidden) {
+        return false;
+    }
     return field.visibleWhen
         ? evaluateFormConditionExpression(field.visibleWhen, fields, values, true)
         : true;
@@ -4627,6 +4995,84 @@ function isSubmittedFieldValuePresent(value) {
 function isNumberFormField(field) {
     return field.type === 'number' || field.type === 'money';
 }
+// A node that is skipped and then has nowhere to go keeps saying why it was
+// skipped, then why the branch ends; any other node just says why it ends.
+function readDryRunStepResultMessage(assignmentMessage, stopMessage, defaultMessage, skipped) {
+    const message = assignmentMessage ?? defaultMessage;
+    if (stopMessage === null) {
+        return message;
+    }
+    return skipped ? `${endSentence(message)}${stopMessage}` : stopMessage;
+}
+// The skip reason and the stop reason are two sentences; a reason that does not
+// already end in full-stop punctuation gets one so they do not run together.
+function endSentence(message) {
+    return /[。！？.!?]$/.test(message) ? message : `${message}。`;
+}
+// Why a manager resolver's fixed fallback cannot take over when the initiator
+// has no manager, or `null` when it can: like the runtime, it must exist, name
+// a member, and not be the initiator unless the node allows self-approval.
+function readDryRunFallbackProblem(initiatorMemberId, fallback) {
+    if (!fallback || fallback.type !== 'DIRECT') {
+        return 'NOT_SET';
+    }
+    const memberId = fallback.memberId.trim();
+    if (memberId === '') {
+        return 'BLANK_MEMBER';
+    }
+    return memberId === initiatorMemberId && !fallback.allowInitiatorSelfApproval
+        ? 'IS_INITIATOR'
+        : null;
+}
+function readDryRunFallbackMemberIds(input, fallback) {
+    return readDryRunFallbackProblem(input.initiatorMemberId, fallback) ===
+        null && fallback?.type === 'DIRECT'
+        ? [fallback.memberId.trim()]
+        : [];
+}
+function readDryRunNodeName(node) {
+    return node.data.label?.trim() || node.id;
+}
+// The dry run cannot look the organisation up, so these resolvers stand in
+// with a placeholder that names what the runtime would resolve.
+function readDryRunPlaceholderAssignee(resolver) {
+    if (resolver.type === 'POSITION') {
+        return `position:${resolver.positionId}`;
+    }
+    if (resolver.type === 'ORG_UNIT_MEMBER') {
+        return `orgUnitMember:${resolver.orgUnitId}`;
+    }
+    if (resolver.type === 'ORG_UNIT_POSITION') {
+        return `orgUnitPosition:${resolver.orgUnitId}:${resolver.positionId}`;
+    }
+    if (resolver.type === 'ORG_UNIT_MANAGER') {
+        return `orgUnitManager:${resolver.orgUnitId}`;
+    }
+    return resolver.type === 'ORG_MANAGER_CHAIN'
+        ? `orgManagerChain:${resolver.minPositionLevel}`
+        : resolver.type;
+}
+function readDryRunUnresolvedApproverMessage(resolver, nodeName, initiatorMemberId) {
+    if (resolver.type === 'DIRECT') {
+        return `簽核節點「${nodeName}」尚未選擇簽核人，請在流程設計器點選此節點設定簽核人`;
+    }
+    if (resolver.type === 'DYNAMIC_FORM') {
+        return `簽核節點「${nodeName}」依表單欄位找不到簽核人，請確認試跑資料中該欄位有填人員`;
+    }
+    if (resolver.type === 'EXPRESSION') {
+        return `簽核節點「${nodeName}」依運算式找不到簽核人，請確認運算式的結果`;
+    }
+    const fallbackProblem = resolver.type === 'ORG_MANAGER'
+        ? readDryRunFallbackProblem(initiatorMemberId, resolver.fallback)
+        : null;
+    if (fallbackProblem === 'BLANK_MEMBER') {
+        return `簽核節點「${nodeName}」找不到主管，且改派固定人未設定`;
+    }
+    if (fallbackProblem === 'IS_INITIATOR') {
+        return `簽核節點「${nodeName}」找不到主管，且改派固定人是申請人本人，此節點未允許申請人自簽`;
+    }
+    return `簽核節點「${nodeName}」依申請人的組織找不到主管，請確認試跑時的申請人資料`;
+}
 function createDryRunStep(input) {
     return Object.assign(new workflow_dry_run_object_1.WorkflowDryRunStepObject(), {
         assigneeMemberId: input.assigneeMemberId,
@@ -4703,4 +5149,34 @@ function mapDecisionToResolution(action) {
             return notification_enums_1.NotificationResolutionEnum.TRANSFERRED;
     }
 }
+// The limit is stated in characters, so a character outside the BMP counts
+// once rather than as its two UTF-16 code units.
+function countCodePoints(value) {
+    return Array.from(value).length;
+}
+function normalizeBusinessKey(businessKey) {
+    const trimmed = businessKey?.trim() ?? '';
+    if (trimmed === '') {
+        return null;
+    }
+    if (countCodePoints(trimmed) > exports.MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH) {
+        throw new common_1.BadRequestException(`業務鍵長度不可超過 ${exports.MAX_APPROVAL_INSTANCE_BUSINESS_KEY_LENGTH} 個字元`);
+    }
+    return trimmed;
+}
+/**
+ * Turns Postgres rejecting a duplicate (template, business key) into a
+ * Conflict. Any other failure, including other unique violations inside the
+ * same transaction, surfaces as it is.
+ */
+function throwBusinessKeyConflictOrRethrow(error, businessKey) {
+    const { code, constraint, driverError } = (error ?? {});
+    if (businessKey !== null &&
+        (code ?? driverError?.code) === '23505' &&
+        (constraint ?? driverError?.constraint) ===
+            APPROVAL_INSTANCE_BUSINESS_KEY_INDEX) {
+        throw new common_1.ConflictException(`此範本已有相同業務鍵（${businessKey}）的簽核單`);
+    }
+    throw error;
+}
 //# sourceMappingURL=workflow-engine.service.js.map