@rytass/bpm-core-nestjs-module 0.22.0 → 0.23.0

package/src/lib/workflow-engine/workflow-engine.service.d.ts

@@ -1,4 +1,4 @@
-import { MemberMetadata, type ApprovalInstanceFieldFilter, type ApprovalInstanceSort } from '@rytass/bpm-core-shared';
+import { MemberMetadata, type FieldAccessFillUnit, type ApprovalInstanceFieldFilter, type ApprovalInstanceSort } from '@rytass/bpm-core-shared';
 import { WorkflowWebhookDeliveryService } from '../workflow-webhook/workflow-webhook-delivery.service';
 import { Repository } from 'typeorm';
 import { AttachmentService } from '../attachment/attachment.service';
@@ -30,6 +30,8 @@ import { TaskEntity } from './task.entity';
 import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum, MemberTaskRoleEnum, TaskCandidateStatusEnum, TaskReassignmentErrorCodeEnum, TaskReassignmentOutcomeEnum } from './workflow-engine.enums';
 import { WorkflowDryRunResultObject } from './workflow-dry-run.object';
 import { BPMInitiatorCustomFieldsResolver } from './initiator-custom-fields-resolver.token';
+import { InstanceEventWriter } from '../instance-event/instance-event.writer';
+import { BPMInstanceGuard } from './instance-guard.token';
 import { BPMWorkflowServiceTaskDispatcher } from './workflow-service-task-dispatcher.token';
 import { WorkflowTokenEntity } from './workflow-token.entity';
 import { BPMRootRuntimeOptions } from '../bpm/bpm-root-options';
@@ -59,6 +61,15 @@ type SubmitApprovalInstanceCommand = SubmitApprovalInstanceInput & {
      * unset and may prefill them.
      */
     readonly endUserSubmission?: boolean;
+    /**
+     * Service layer only (ADR 27 §5): fields a host adds to the initiator's
+     * `customFields`. The engine still builds the default snapshot and calls the
+     * `customFields` resolver; these values are merged over what it returned, so
+     * a key given here wins. Cannot be combined with
+     * `initiatorMetadataSnapshotJson` (400). The GraphQL mutation always passes
+     * `null`.
+     */
+    readonly initiatorCustomFields?: Readonly<Record<string, unknown>> | null;
 };
 type ResubmitApprovalInstanceCommand = ResubmitApprovalInstanceInput & {
     readonly initiatorMemberId: string;
@@ -114,8 +125,22 @@ export interface TaskListPageOptions {
     /** Defaults to 20, at most 100, once paging is asked for. */
     readonly pageSize?: number;
 }
+/**
+ * Narrows a member's task list to the tasks of some templates. Absent fields
+ * do not filter. An empty `templateIds` matches nothing, as `IN ()` would.
+ * When both fields are given a task must satisfy both.
+ */
+export interface TaskTemplateFilter {
+    /** Only tasks whose instance was started from one of these templates. */
+    readonly templateIds?: readonly string[];
+    /** Only tasks whose instance's template carries this key (ADR 27 §6). */
+    readonly templateKey?: string;
+}
+/** Options of {@link WorkflowEngineService.listInboxTasks}. */
+export interface InboxTaskListOptions extends TaskListPageOptions, TaskTemplateFilter {
+}
 /** Options of {@link WorkflowEngineService.listApprovalHistoryTasks}. */
-export interface ApprovalHistoryTaskListOptions extends TaskListPageOptions {
+export interface ApprovalHistoryTaskListOptions extends TaskListPageOptions, TaskTemplateFilter {
     /** Only tasks of instances in this state. */
     readonly instanceState?: ApprovalInstanceStateEnum;
 }
@@ -152,6 +177,13 @@ export interface DecideTaskOptions {
      * transfer. Defaults to {@link MANUAL_TRANSFER_DELEGATION_REASON}.
      */
     readonly transferReason?: string;
+    /**
+     * The approver's own auth context, passed by the GraphQL mutation. Data
+     * source providers receive it when an approver-filled dynamic field is
+     * resolved. Absent for engine-made decisions (SLA auto-approve), which then
+     * act as the decider's member id only.
+     */
+    readonly approverAuthContext?: BPMAuthContext;
 }
 export interface ListApprovalInstancesOptions {
     /** ADR 25 §7: conditions on form fields. Needs `templateId` when not empty. */
@@ -163,6 +195,11 @@ export interface ListApprovalInstancesOptions {
     readonly sort?: readonly ApprovalInstanceSort[];
     readonly state?: readonly ApprovalInstanceStateEnum[];
     readonly templateId?: string;
+    /**
+     * ADR 27 §6: the template's `key`. Resolved to its id; with `templateId`
+     * as well, both must name the same template. An unknown key matches nothing.
+     */
+    readonly templateKey?: string;
     readonly view?: ApprovalInstanceListViewEnum;
 }
 interface WorkflowDashboardSummaryOptions {
@@ -190,14 +227,38 @@ export declare class WorkflowEngineService {
     private readonly slaScheduleService;
     private readonly formDataSourceValueResolver?;
     private readonly webhookDeliveryService?;
+    private readonly instanceEventWriter?;
     private readonly logger;
     /** In-flight inbox reads by member; see `readSharedOpenInboxTasks`. */
     private readonly openInboxReadsInFlight;
     private readonly approvalInstanceFieldFilterCompiler;
     private readonly approvalInstanceFilterableFieldPolicy;
-    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined, injectedInitiatorCustomFieldsResolver?: BPMInitiatorCustomFieldsResolver);
+    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined, injectedInitiatorCustomFieldsResolver?: BPMInitiatorCustomFieldsResolver, injectedInstanceGuard?: BPMInstanceGuard, instanceEventWriter?: InstanceEventWriter | undefined);
+    /** ADR 27 §3; see `BPMRootRuntimeOptions.expressionMissingFormFieldsAsNull`. */
+    private readonly expressionMissingFormFieldsAsNull;
     private readonly serviceTaskDispatcher;
     private readonly initiatorCustomFieldsResolver;
+    /** ADR 27 §2; `null` means no guard is bound and no guard code runs. */
+    private readonly instanceGuard;
+    private readonly instanceGuardTimeoutMs;
+    /**
+     * Runs the bound guard for one engine path inside its transaction. A no-op
+     * when no guard is bound, so a host without one sees no behavior change.
+     */
+    private guardInstanceChange;
+    /**
+     * Writes one case-lifecycle event (ADR 27 §1) in the caller's transaction.
+     * Returns before any lookup when no observer is bound, so a host without
+     * one pays nothing. `instanceState` is the state the change commits, not the
+     * state the instance held before it.
+     */
+    private recordInstanceEvent;
+    /**
+     * Reads the template version a case runs on, inside the engine transaction,
+     * so the guard sees the same snapshot as the decision. A missing row fails
+     * the change rather than handing the guard a partial input.
+     */
+    private readBoundTemplateVersionOrThrow;
     /** Webhooks each open engine transaction will send once it has committed. */
     private readonly deferredWebhookDispatches;
     private readonly organizationTimeZone;
@@ -239,8 +300,42 @@ export declare class WorkflowEngineService {
      */
     findApprovalInstanceByBusinessKey(templateId: string, businessKey: string): Promise<ApprovalInstanceEntity | null>;
     private resolveFormDataOptionSnapshots;
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, under the decision
+     * lock and as the approver, for the options of the approver-fillable fields.
+     * A value that is no longer among the options is refused by the resolver
+     * (`VALUE_NOT_RESOLVED`). Returns snapshots for the scoped fields only; the
+     * caller swaps them in for the stored ones.
+     */
+    private refreshApproverFilledOptionSnapshots;
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, as the approver, for
+     * the open data-source cells of column-mode tables. `revalidateAll` false lets
+     * the resolver reuse the stored options of cells whose value and bindings did
+     * not move. Returns snapshots for the cells of `cellSchema` only.
+     */
+    private refreshApproverFilledOpenCellSnapshots;
+    /**
+     * Refuses an end user's resubmission of an instance bound to a `HOST_ONLY`
+     * version (ADR 27 §5). Checked before any data source is called and outside
+     * the lock: an instance never changes version and a published version never
+     * changes `launchMode`, so the answer cannot go stale. An instance that does
+     * not exist is left to the locked read, which reports it.
+     */
+    private assertEndUserMayResubmit;
     private prepareResubmitFormDataOptions;
     processInstance(instanceId: string): Promise<void>;
+    /**
+     * Records `TASK_AUTO_DECISION_FAILED` (ADR 27 §3) in its own transaction.
+     * Used after an automatic decision was refused by the instance guard: the
+     * decision's transaction has already rolled back, so the event cannot ride
+     * on it. Returns before any query when no observer is bound.
+     */
+    recordTaskAutoDecisionFailed(input: {
+        readonly instanceId: string;
+        readonly taskId: string;
+        readonly reason: string;
+    }): Promise<void>;
     decideTask(input: DecideTaskInput, options?: DecideTaskOptions): Promise<TaskDecisionEntity>;
     cancelApprovalInstance(input: CancelApprovalInstanceInput): Promise<ApprovalInstanceEntity>;
     /**
@@ -332,6 +427,16 @@ export declare class WorkflowEngineService {
      */
     private readDryRunMemberIds;
     getApprovalInstance(id: string, scope?: WorkflowReadScope): Promise<ApprovalInstanceEntity>;
+    /**
+     * ADR 27 §4.2 (gap 1): the fill units an approver may use to resolve runtime
+     * data-source options on a RUNNING instance. Only tasks the member can act on
+     * count: the member is the assignee or a PENDING/CLAIMED candidate of a
+     * PENDING or IN_PROGRESS, non-ad-hoc task. A task whose candidate row is
+     * WAITING or already decided grants nothing, even though its status is open.
+     * A field counts only when its node lists it as SHOW; a HIDE entry never
+     * grants, whatever its fill is. Returns `[]` when the instance is not RUNNING.
+     */
+    listApproverFillUnits(instanceId: string, memberId: string): Promise<readonly FieldAccessFillUnit[]>;
     /**
      * ADR 25 §6: a value written to a filterable field must fit its type, on
      * every path that writes form data. The fields checked are the ones the
@@ -415,9 +520,31 @@ export declare class WorkflowEngineService {
      * {@link countInboxTasks} and the counters cannot disagree; only the page is
      * given its candidate summaries.
      */
-    listInboxTasks(assigneeMemberId: string, options?: TaskListPageOptions): Promise<readonly TaskEntity[]>;
+    listInboxTasks(assigneeMemberId: string, options?: InboxTaskListOptions): Promise<readonly TaskEntity[]>;
     /** How many tasks {@link listInboxTasks} pages through. */
-    countInboxTasks(assigneeMemberId: string): Promise<number>;
+    countInboxTasks(assigneeMemberId: string, filter?: TaskTemplateFilter): Promise<number>;
+    /**
+     * The template ids a {@link TaskTemplateFilter} allows, or `null` when it
+     * does not filter. A `templateKey` that names no template allows nothing.
+     */
+    private readTaskTemplateFilterIds;
+    /**
+     * Turns `templateKey` into `templateId` (ADR 27 §6), or `null` when the
+     * options can match nothing: an unknown key, or a key naming another
+     * template than `templateId` does.
+     */
+    private resolveApprovalInstanceTemplateKey;
+    /**
+     * The id of the live template carrying `key`, as a list so a key that names
+     * nothing filters everything out. At most one live template holds a key.
+     */
+    private readTemplateIdsByKey;
+    /**
+     * Keeps the tasks whose instance belongs to the filter's templates. The open
+     * task read is shared with the dashboard counters, so the filter is applied
+     * to its result rather than pushed into it.
+     */
+    private filterTasksByTemplate;
     /**
      * {@link readOpenInboxTasks} for the inbox list and its count, joining a
      * read for the same member that is still in flight. The client asks for
@@ -452,7 +579,7 @@ export declare class WorkflowEngineService {
      */
     listApprovalHistoryTasks(assigneeMemberId: string, options?: ApprovalHistoryTaskListOptions): Promise<readonly TaskEntity[]>;
     /** How many tasks {@link listApprovalHistoryTasks} pages through. */
-    countApprovalHistoryTasks(assigneeMemberId: string, options?: Pick<ApprovalHistoryTaskListOptions, 'instanceState'>): Promise<number>;
+    countApprovalHistoryTasks(assigneeMemberId: string, options?: Omit<ApprovalHistoryTaskListOptions, 'page' | 'pageSize'>): Promise<number>;
     /** The rows of {@link listApprovalHistoryTasks}, unordered and unpaged. */
     private createApprovalHistoryTaskQuery;
     /** When the member acted on a history task; see {@link listApprovalHistoryTasks}. */
@@ -471,7 +598,7 @@ export declare class WorkflowEngineService {
      * snapshot without a `nodes` array, and a blank or non-string label all
      * leave the task without a label, as `readWorkflowNodeLabel` does. Only the
      * node's `fieldAccess` leaves the database for the fill flag, which
-     * `readNodeFillableFieldKeys` then reads as tolerantly as the engine does.
+     * `readNodeFillGrantFieldKeys` then reads as tolerantly as the engine does.
      */
     private readTaskNodeSummaries;
     private readDefaultInitiatorMetadataSnapshot;
@@ -708,6 +835,13 @@ export declare class WorkflowEngineService {
      */
     private readApprovalPrincipalMemberIds;
     private resolveInitiatorManagerReplacements;
+    /**
+     * The context workflow expressions on `instance` read. Its `form` is the
+     * stored data, or with `expressionMissingFormFieldsAsNull` on, a copy with
+     * every unfilled top-level field present (ADR 27 §3).
+     */
+    private buildExpressionContext;
+    private readExpressionFormData;
     private buildDelegationContext;
     private delegateResolvedCandidates;
     /** One member's delegation, grade-gated as {@link applyGradeGate} says. */