@rytass/bpm-core-nestjs-module 0.4.0 → 0.5.0

package/src/lib/workflow-engine/workflow-condition-evaluator.ts

@@ -0,0 +1,168 @@
+import {
+  WorkflowEdge,
+  WorkflowEdgeConditionOperator,
+} from '@rytass/bpm-core-shared/workflow';
+
+export type WorkflowConditionContext = Readonly<{
+  formData: Readonly<Record<string, unknown>>;
+}>;
+
+export function evaluateWorkflowEdgeCondition(
+  edge: WorkflowEdge,
+  context: WorkflowConditionContext,
+): boolean {
+  const fieldKey = edge.data.conditionFieldKey;
+  const operator = edge.data.conditionOperator;
+
+  if (!fieldKey || !operator) {
+    return false;
+  }
+
+  const actualValue = context.formData[fieldKey];
+
+  if (operator === 'IS_FILLED') {
+    return !isEmptyWorkflowValue(actualValue);
+  }
+
+  if (operator === 'IS_EMPTY') {
+    return isEmptyWorkflowValue(actualValue);
+  }
+
+  const expectedValue = edge.data.conditionValue;
+
+  if (typeof expectedValue === 'undefined') {
+    return false;
+  }
+
+  return compareWorkflowValues(actualValue, operator, expectedValue);
+}
+
+function compareWorkflowValues(
+  actualValue: unknown,
+  operator: WorkflowEdgeConditionOperator,
+  expectedValue: string,
+): boolean {
+  if (Array.isArray(actualValue)) {
+    return compareArrayValue(actualValue, operator, expectedValue);
+  }
+
+  if (operator === 'EQUALS') {
+    return normalizeWorkflowValue(actualValue) ===
+      normalizeExpectedValue(actualValue, expectedValue);
+  }
+
+  if (operator === 'NOT_EQUALS') {
+    return normalizeWorkflowValue(actualValue) !==
+      normalizeExpectedValue(actualValue, expectedValue);
+  }
+
+  return compareOrderedValue(actualValue, operator, expectedValue);
+}
+
+function compareArrayValue(
+  actualValue: readonly unknown[],
+  operator: WorkflowEdgeConditionOperator,
+  expectedValue: string,
+): boolean {
+  const includesExpectedValue = actualValue
+    .map((value) => normalizeWorkflowValue(value))
+    .includes(expectedValue);
+
+  if (operator === 'EQUALS') {
+    return includesExpectedValue;
+  }
+
+  if (operator === 'NOT_EQUALS') {
+    return !includesExpectedValue;
+  }
+
+  return false;
+}
+
+function compareOrderedValue(
+  actualValue: unknown,
+  operator: WorkflowEdgeConditionOperator,
+  expectedValue: string,
+): boolean {
+  const actualNumber = readFiniteNumber(actualValue);
+  const expectedNumber = readFiniteNumber(expectedValue);
+  const actualComparable =
+    actualNumber !== null ? actualNumber : normalizeWorkflowValue(actualValue);
+  const expectedComparable =
+    actualNumber !== null && expectedNumber !== null
+      ? expectedNumber
+      : expectedValue;
+
+  if (operator === 'GREATER_THAN') {
+    return actualComparable > expectedComparable;
+  }
+
+  if (operator === 'GREATER_THAN_OR_EQUALS') {
+    return actualComparable >= expectedComparable;
+  }
+
+  if (operator === 'LESS_THAN') {
+    return actualComparable < expectedComparable;
+  }
+
+  if (operator === 'LESS_THAN_OR_EQUALS') {
+    return actualComparable <= expectedComparable;
+  }
+
+  return false;
+}
+
+function isEmptyWorkflowValue(value: unknown): boolean {
+  if (value === null || typeof value === 'undefined') {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+
+  return typeof value === 'string' ? value.trim() === '' : false;
+}
+
+function normalizeWorkflowValue(value: unknown): string | number | boolean {
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+
+  return String(value ?? '');
+}
+
+function normalizeExpectedValue(
+  actualValue: unknown,
+  expectedValue: string,
+): string | number | boolean {
+  if (typeof actualValue === 'boolean') {
+    return expectedValue === 'true';
+  }
+
+  if (typeof actualValue === 'number') {
+    const expectedNumber = Number(expectedValue);
+
+    return Number.isFinite(expectedNumber) ? expectedNumber : expectedValue;
+  }
+
+  return expectedValue;
+}
+
+function readFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+
+  if (typeof value !== 'string' || !value.trim()) {
+    return null;
+  }
+
+  const numberValue = Number(value);
+
+  return Number.isFinite(numberValue) ? numberValue : null;
+}

package/src/lib/workflow-engine/workflow-dashboard-summary.object.ts

@@ -0,0 +1,22 @@
+import { Field, Int, ObjectType } from '@nestjs/graphql';
+
+@ObjectType('WorkflowDashboardSummary')
+export class WorkflowDashboardSummaryObject {
+  @Field(() => Int)
+  activeInstanceCount!: number;
+
+  @Field(() => Int)
+  completedInstanceCount!: number;
+
+  @Field(() => Int)
+  overdueTaskCount!: number;
+
+  @Field(() => Int)
+  pendingTaskCount!: number;
+
+  @Field(() => Int)
+  rejectedInstanceCount!: number;
+
+  @Field(() => Int)
+  totalInstanceCount!: number;
+}

package/src/lib/workflow-engine/workflow-dry-run.object.ts

@@ -0,0 +1,58 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+@ObjectType('WorkflowDryRunStep')
+export class WorkflowDryRunStepObject {
+  @Field()
+  id!: string;
+
+  @Field()
+  nodeId!: string;
+
+  @Field()
+  nodeLabel!: string;
+
+  @Field()
+  nodeType!: string;
+
+  @Field()
+  status!: string;
+
+  @Field(() => String, { nullable: true })
+  edgeId!: string | null;
+
+  @Field(() => String, { nullable: true })
+  edgeLabel!: string | null;
+
+  @Field(() => Boolean, { nullable: true })
+  edgeMatched!: boolean | null;
+
+  @Field(() => String, { nullable: true })
+  edgeReason!: string | null;
+
+  @Field(() => Boolean, { nullable: true })
+  edgeDefault!: boolean | null;
+
+  @Field(() => String, { nullable: true })
+  entryCondition!: string | null;
+
+  @Field(() => Boolean, { nullable: true })
+  entryConditionMatched!: boolean | null;
+
+  @Field(() => String, { nullable: true })
+  assigneeMemberId!: string | null;
+
+  @Field()
+  message!: string;
+}
+
+@ObjectType('WorkflowDryRunResult')
+export class WorkflowDryRunResultObject {
+  @Field()
+  valid!: boolean;
+
+  @Field(() => [String])
+  errors!: readonly string[];
+
+  @Field(() => [WorkflowDryRunStepObject])
+  steps!: readonly WorkflowDryRunStepObject[];
+}

package/src/lib/workflow-engine/workflow-engine.enums.ts

@@ -0,0 +1,102 @@
+import { registerEnumType } from '@nestjs/graphql';
+
+export enum ApprovalInstanceStateEnum {
+  APPROVED = 'APPROVED',
+  CANCELLED = 'CANCELLED',
+  DRAFT = 'DRAFT',
+  EXPIRED = 'EXPIRED',
+  REJECTED = 'REJECTED',
+  RETURNED = 'RETURNED',
+  RUNNING = 'RUNNING',
+}
+
+export enum ApprovalInstanceListViewEnum {
+  ALL = 'ALL',
+  CC = 'CC',
+  SENT = 'SENT',
+}
+
+export enum WorkflowTokenStatusEnum {
+  ACTIVE = 'ACTIVE',
+  CONSUMED = 'CONSUMED',
+  WAITING = 'WAITING',
+}
+
+export enum TaskStatusEnum {
+  CANCELLED = 'CANCELLED',
+  COMPLETED = 'COMPLETED',
+  IN_PROGRESS = 'IN_PROGRESS',
+  PENDING = 'PENDING',
+  TRANSFERRED = 'TRANSFERRED',
+}
+
+export enum TaskAssignmentTypeEnum {
+  CANDIDATE_GROUP = 'CANDIDATE_GROUP',
+  DIRECT_MEMBER = 'DIRECT_MEMBER',
+}
+
+export enum TaskCandidateStatusEnum {
+  CANCELLED = 'CANCELLED',
+  CLAIMED = 'CLAIMED',
+  COMPLETED = 'COMPLETED',
+  PENDING = 'PENDING',
+  SUPERSEDED = 'SUPERSEDED',
+  TRANSFERRED = 'TRANSFERRED',
+}
+
+export enum TaskDecisionActionEnum {
+  APPROVED = 'APPROVED',
+  REJECTED = 'REJECTED',
+  RETURNED = 'RETURNED',
+  TRANSFERRED = 'TRANSFERRED',
+}
+
+export enum ActivityLogEventTypeEnum {
+  ADHOC_DIRECTIVE_CANCELLED = 'ADHOC_DIRECTIVE_CANCELLED',
+  ADHOC_DIRECTIVE_CREATED = 'ADHOC_DIRECTIVE_CREATED',
+  ADHOC_PRE_APPROVAL_RETURNED = 'ADHOC_PRE_APPROVAL_RETURNED',
+  ENGINE_PROCESS_REQUESTED = 'ENGINE_PROCESS_REQUESTED',
+  INSTANCE_CANCELLED = 'INSTANCE_CANCELLED',
+  INSTANCE_RESUBMITTED = 'INSTANCE_RESUBMITTED',
+  INSTANCE_STARTED = 'INSTANCE_STARTED',
+  INSTANCE_RETURNED = 'INSTANCE_RETURNED',
+  SERVICE_TASK_EXECUTED = 'SERVICE_TASK_EXECUTED',
+  SERVICE_TASK_FAILED = 'SERVICE_TASK_FAILED',
+  SLA_TRIGGERED = 'SLA_TRIGGERED',
+  TASK_CREATED = 'TASK_CREATED',
+  TASK_DECIDED = 'TASK_DECIDED',
+  TOKEN_ADVANCED = 'TOKEN_ADVANCED',
+  TOKEN_CREATED = 'TOKEN_CREATED',
+}
+
+registerEnumType(ApprovalInstanceStateEnum, {
+  name: 'ApprovalInstanceState',
+});
+
+registerEnumType(ApprovalInstanceListViewEnum, {
+  name: 'ApprovalInstanceListView',
+});
+
+registerEnumType(WorkflowTokenStatusEnum, {
+  name: 'WorkflowTokenStatus',
+});
+
+registerEnumType(TaskStatusEnum, {
+  name: 'TaskStatus',
+});
+
+registerEnumType(TaskAssignmentTypeEnum, {
+  name: 'TaskAssignmentType',
+});
+
+registerEnumType(TaskCandidateStatusEnum, {
+  name: 'TaskCandidateStatus',
+});
+
+registerEnumType(TaskDecisionActionEnum, {
+  name: 'TaskDecisionAction',
+});
+
+registerEnumType(ActivityLogEventTypeEnum, {
+  name: 'ActivityLogEventType',
+});

package/src/lib/workflow-engine/workflow-engine.module.ts

@@ -0,0 +1,77 @@
+import { DynamicModule, Module, Provider } from '@nestjs/common';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ConditionModule } from '../condition/condition.module';
+import { DelegationModule } from '../delegation/delegation.module';
+import { FormDefinitionVersionEntity } from '../form/form-definition-version.entity';
+import { ManagerResolutionEntity } from '../organization/manager-resolution.entity';
+import { NotificationEntity } from '../notification/notification.entity';
+import { NotificationModule } from '../notification/notification.module';
+import { OrgUnitEntity } from '../organization/org-unit.entity';
+import { SignatureModule } from '../signature/signature.module';
+import { MembershipEntity } from '../organization/membership.entity';
+import { ApprovalTemplateVersionEntity } from '../template/approval-template-version.entity';
+import { ApprovalTemplateEntity } from '../template/approval-template.entity';
+import { ActivityLogEntity } from './activity-log.entity';
+import { AdhocDirectiveEntity } from './adhoc-directive.entity';
+import { ApprovalInstanceEntity } from './approval-instance.entity';
+import { TaskDecisionEntity } from './task-decision.entity';
+import { TaskCandidateEntity } from './task-candidate.entity';
+import { TaskEntity } from './task.entity';
+import { WorkflowEngineMutations } from './workflow-engine.mutations';
+import { WorkflowEngineQueries } from './workflow-engine.queries';
+import { WorkflowEngineService } from './workflow-engine.service';
+import { BPM_WORKFLOW_ENGINE_SERVICE } from './workflow-engine.tokens';
+import { BPMWorkflowServiceTaskDispatcher } from './workflow-service-task-dispatcher.token';
+import { WorkflowTokenEntity } from './workflow-token.entity';
+
+export interface WorkflowEngineModuleOptions
+  extends Pick<ModuleMetadata, 'imports'> {
+  readonly serviceTaskDispatcherProvider?: Provider<BPMWorkflowServiceTaskDispatcher>;
+}
+
+@Module({
+  imports: [
+    ConditionModule,
+    DelegationModule,
+    NotificationModule,
+    SignatureModule,
+    TypeOrmModule.forFeature([
+      ActivityLogEntity,
+      AdhocDirectiveEntity,
+      ApprovalInstanceEntity,
+      ApprovalTemplateEntity,
+      ApprovalTemplateVersionEntity,
+      FormDefinitionVersionEntity,
+      ManagerResolutionEntity,
+      MembershipEntity,
+      NotificationEntity,
+      OrgUnitEntity,
+      TaskCandidateEntity,
+      TaskDecisionEntity,
+      TaskEntity,
+      WorkflowTokenEntity,
+    ]),
+  ],
+  providers: [
+    WorkflowEngineMutations,
+    WorkflowEngineQueries,
+    WorkflowEngineService,
+    {
+      provide: BPM_WORKFLOW_ENGINE_SERVICE,
+      useExisting: WorkflowEngineService,
+    },
+  ],
+  exports: [BPM_WORKFLOW_ENGINE_SERVICE, WorkflowEngineService],
+})
+export class WorkflowEngineModule {
+  static forRoot(options: WorkflowEngineModuleOptions = {}): DynamicModule {
+    return {
+      imports: options.imports ? [...options.imports] : [],
+      module: WorkflowEngineModule,
+      providers: options.serviceTaskDispatcherProvider
+        ? [options.serviceTaskDispatcherProvider]
+        : [],
+    };
+  }
+}

package/src/lib/workflow-engine/workflow-engine.mutations.ts

@@ -0,0 +1,193 @@
+import { Args, ID, Mutation, Resolver } from '@nestjs/graphql';
+import {
+  BPMAdminOnly,
+  BPMAuthenticated,
+  BPMCurrentMemberId,
+} from '../bpm-auth';
+import { AdhocDirectiveEntity } from './adhoc-directive.entity';
+import {
+  AdhocDirectiveTypeEnum,
+  AdhocPreApprovalRejectBehaviorEnum,
+} from './adhoc.enums';
+import { ApprovalInstanceEntity } from './approval-instance.entity';
+import { AdhocNotificationInput } from './dto/adhoc-notification.input';
+import { AdhocTargetInput } from './dto/adhoc-target.input';
+import { CancelApprovalInstanceInput } from './dto/cancel-approval-instance.input';
+import { DecideTaskInput } from './dto/decide-task.input';
+import { DryRunApprovalWorkflowInput } from './dto/dry-run-approval-workflow.input';
+import { ResubmitApprovalInstanceInput } from './dto/resubmit-approval-instance.input';
+import { SubmitApprovalInstanceInput } from './dto/submit-approval-instance.input';
+import { TaskDecisionEntity } from './task-decision.entity';
+import { TaskEntity } from './task.entity';
+import { WorkflowDryRunResultObject } from './workflow-dry-run.object';
+import { WorkflowEngineService } from './workflow-engine.service';
+
+@Resolver()
+@BPMAuthenticated()
+export class WorkflowEngineMutations {
+  constructor(private readonly workflowEngineService: WorkflowEngineService) {}
+
+  @Mutation(() => ApprovalInstanceEntity)
+  async submitApprovalInstance(
+    @Args('input') input: SubmitApprovalInstanceInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<ApprovalInstanceEntity> {
+    return this.workflowEngineService.submitApprovalInstance({
+      ...input,
+      initiatorMemberId: currentMemberId,
+      initiatorMetadataSnapshotJson: null,
+    });
+  }
+
+  @Mutation(() => Boolean)
+  @BPMAdminOnly()
+  async processApprovalInstance(
+    @Args('instanceId', { type: () => String }) instanceId: string,
+  ): Promise<boolean> {
+    await this.workflowEngineService.processInstance(instanceId);
+
+    return true;
+  }
+
+  @Mutation(() => TaskDecisionEntity)
+  async decideTask(
+    @Args('input') input: DecideTaskInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<TaskDecisionEntity> {
+    return this.workflowEngineService.decideTask({
+      ...input,
+      decidedByMemberId: currentMemberId,
+    });
+  }
+
+  @Mutation(() => ApprovalInstanceEntity)
+  async cancelApprovalInstance(
+    @Args('input') input: CancelApprovalInstanceInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<ApprovalInstanceEntity> {
+    return this.workflowEngineService.cancelApprovalInstance({
+      ...input,
+      cancelledByMemberId: currentMemberId,
+    });
+  }
+
+  @Mutation(() => ApprovalInstanceEntity)
+  async resubmitApprovalInstance(
+    @Args('input') input: ResubmitApprovalInstanceInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<ApprovalInstanceEntity> {
+    return this.workflowEngineService.resubmitApprovalInstance({
+      ...input,
+      initiatorMemberId: currentMemberId,
+    });
+  }
+
+  @Mutation(() => WorkflowDryRunResultObject)
+  async dryRunApprovalWorkflow(
+    @Args('input') input: DryRunApprovalWorkflowInput,
+  ): Promise<WorkflowDryRunResultObject> {
+    return Promise.resolve(
+      this.workflowEngineService.dryRunApprovalWorkflow(input),
+    );
+  }
+
+  @Mutation(() => AdhocDirectiveEntity, {
+    description:
+      'Ad-hoc countersign: the target joins the NEXT stage as a parallel '
+      + 'task; the flow only advances once every task on that stage is '
+      + 'approved. Requires allowAddSigner on the node. Instance-scoped — '
+      + 'never alters the template.',
+  })
+  async requestAdhocCountersign(
+    @Args('taskId', { type: () => ID }) taskId: string,
+    @Args('target') target: AdhocTargetInput,
+    @Args('comment', { nullable: true, type: () => String })
+    comment: string | null,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<AdhocDirectiveEntity> {
+    return this.workflowEngineService.requestAdhocCountersign({
+      comment,
+      requestedByMemberId: currentMemberId,
+      target,
+      taskId,
+    });
+  }
+
+  @Mutation(() => TaskEntity, {
+    description:
+      'Ad-hoc pre-approval: spawns a blocking task for the target on the '
+      + 'CURRENT stage; the flow stays until the pre-approver approves. '
+      + 'onReject chooses REJECT_INSTANCE or RETURN_TO_ORIGIN. Requires '
+      + 'allowAddSigner on the node. Instance-scoped.',
+  })
+  async requestAdhocPreApproval(
+    @Args('taskId', { type: () => ID }) taskId: string,
+    @Args('target') target: AdhocTargetInput,
+    @Args('onReject', { type: () => AdhocPreApprovalRejectBehaviorEnum })
+    onReject: AdhocPreApprovalRejectBehaviorEnum,
+    @Args('comment', { nullable: true, type: () => String })
+    comment: string | null,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<TaskEntity> {
+    return this.workflowEngineService.requestAdhocPreApproval({
+      comment,
+      onReject,
+      requestedByMemberId: currentMemberId,
+      target,
+      taskId,
+    });
+  }
+
+  @Mutation(() => AdhocDirectiveEntity, {
+    description:
+      'Notify the target once the CURRENT stage ends, regardless of '
+      + 'outcome (approved / rejected / returned). Instance-scoped.',
+  })
+  async configureAdhocStageNotification(
+    @Args('taskId', { type: () => ID }) taskId: string,
+    @Args('input') input: AdhocNotificationInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<AdhocDirectiveEntity> {
+    return this.workflowEngineService.configureAdhocNotification({
+      channels: input.channels,
+      requestedByMemberId: currentMemberId,
+      target: input.target,
+      taskId,
+      type: AdhocDirectiveTypeEnum.STAGE_NOTIFY,
+    });
+  }
+
+  @Mutation(() => AdhocDirectiveEntity, {
+    description:
+      'Notify the target once the instance reaches a terminal state '
+      + '(APPROVED / REJECTED / CANCELLED). Instance-scoped.',
+  })
+  async configureAdhocCompletionNotification(
+    @Args('taskId', { type: () => ID }) taskId: string,
+    @Args('input') input: AdhocNotificationInput,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<AdhocDirectiveEntity> {
+    return this.workflowEngineService.configureAdhocNotification({
+      channels: input.channels,
+      requestedByMemberId: currentMemberId,
+      target: input.target,
+      taskId,
+      type: AdhocDirectiveTypeEnum.COMPLETION_NOTIFY,
+    });
+  }
+
+  @Mutation(() => AdhocDirectiveEntity, {
+    description:
+      'Withdraw a still-pending ad-hoc directive. Only the creator may '
+      + 'withdraw it.',
+  })
+  async cancelAdhocDirective(
+    @Args('directiveId', { type: () => ID }) directiveId: string,
+    @BPMCurrentMemberId() currentMemberId: string,
+  ): Promise<AdhocDirectiveEntity> {
+    return this.workflowEngineService.cancelAdhocDirective({
+      cancelledByMemberId: currentMemberId,
+      directiveId,
+    });
+  }
+}