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

package/src/lib/workflow-engine/adhoc-directive.entity.ts

@@ -0,0 +1,90 @@
+import { Field, ID, ObjectType } from '@nestjs/graphql';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+import { NotificationChannelEnum } from '../notification/notification.enums';
+import {
+  AdhocDirectiveStatusEnum,
+  AdhocDirectiveTypeEnum,
+  AdhocPreApprovalRejectBehaviorEnum,
+  AdhocTargetKindEnum,
+} from './adhoc.enums';
+
+/**
+ * Instance-scoped ad-hoc directive recorded by a stage approver. Directives
+ * never touch the workflow template — they only affect the single approval
+ * instance they were created on:
+ *
+ * - COUNTERSIGN: spawn a parallel ad-hoc task next to the next user task.
+ * - PRE_APPROVAL: spawn a parallel ad-hoc task on the current node that must
+ *   complete before the token may advance.
+ * - STAGE_NOTIFY: notify targets once the origin node's stage ends.
+ * - COMPLETION_NOTIFY: notify targets once the instance reaches a terminal
+ *   state (APPROVED / REJECTED / CANCELLED).
+ */
+@Entity('task_adhoc_directives')
+@ObjectType('AdhocDirective')
+export class AdhocDirectiveEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'instance_id' })
+  @Field(() => ID)
+  instanceId!: string;
+
+  @Column('uuid', { name: 'origin_task_id' })
+  @Field(() => ID)
+  originTaskId!: string;
+
+  @Column('text', { name: 'origin_node_id' })
+  @Field()
+  originNodeId!: string;
+
+  @Column('text', { name: 'created_by_member_id' })
+  @Field()
+  createdByMemberId!: string;
+
+  @Column('text')
+  @Field(() => AdhocDirectiveTypeEnum)
+  type!: AdhocDirectiveTypeEnum;
+
+  @Column('text', { name: 'target_kind' })
+  @Field(() => AdhocTargetKindEnum)
+  targetKind!: AdhocTargetKindEnum;
+
+  @Column('jsonb', { name: 'target_value' })
+  targetValue!: Readonly<Record<string, unknown>>;
+
+  @Column('text', { name: 'on_reject', nullable: true })
+  @Field(() => AdhocPreApprovalRejectBehaviorEnum, { nullable: true })
+  onReject!: AdhocPreApprovalRejectBehaviorEnum | null;
+
+  @Column('jsonb', { nullable: true })
+  @Field(() => [NotificationChannelEnum], { nullable: true })
+  channels!: readonly NotificationChannelEnum[] | null;
+
+  @Column('text', { nullable: true })
+  @Field(() => String, { nullable: true })
+  comment!: string | null;
+
+  @Column('text', { default: AdhocDirectiveStatusEnum.PENDING })
+  @Field(() => AdhocDirectiveStatusEnum)
+  status!: AdhocDirectiveStatusEnum;
+
+  @Column('timestamptz', { name: 'consumed_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  consumedAt!: Date | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  @Field()
+  createdAt!: Date;
+
+  @Field(() => String)
+  get targetValueJson(): string {
+    return JSON.stringify(this.targetValue);
+  }
+}

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

@@ -0,0 +1,42 @@
+import { registerEnumType } from '@nestjs/graphql';
+
+export enum AdhocDirectiveTypeEnum {
+  COMPLETION_NOTIFY = 'COMPLETION_NOTIFY',
+  COUNTERSIGN = 'COUNTERSIGN',
+  PRE_APPROVAL = 'PRE_APPROVAL',
+  STAGE_NOTIFY = 'STAGE_NOTIFY',
+}
+
+export enum AdhocDirectiveStatusEnum {
+  CANCELLED = 'CANCELLED',
+  CONSUMED = 'CONSUMED',
+  PENDING = 'PENDING',
+}
+
+export enum AdhocTargetKindEnum {
+  MEMBER = 'MEMBER',
+  ORG_UNIT_MEMBER = 'ORG_UNIT_MEMBER',
+  POSITION = 'POSITION',
+  WEBHOOK = 'WEBHOOK',
+}
+
+export enum AdhocPreApprovalRejectBehaviorEnum {
+  REJECT_INSTANCE = 'REJECT_INSTANCE',
+  RETURN_TO_ORIGIN = 'RETURN_TO_ORIGIN',
+}
+
+registerEnumType(AdhocDirectiveTypeEnum, {
+  name: 'AdhocDirectiveType',
+});
+
+registerEnumType(AdhocDirectiveStatusEnum, {
+  name: 'AdhocDirectiveStatus',
+});
+
+registerEnumType(AdhocTargetKindEnum, {
+  name: 'AdhocTargetKind',
+});
+
+registerEnumType(AdhocPreApprovalRejectBehaviorEnum, {
+  name: 'AdhocPreApprovalRejectBehavior',
+});

package/src/lib/workflow-engine/approval-instance-page-info.object.ts

@@ -0,0 +1,22 @@
+import { Field, Int, ObjectType } from '@nestjs/graphql';
+
+@ObjectType('ApprovalInstancePageInfo')
+export class ApprovalInstancePageInfoObject {
+  @Field(() => Boolean)
+  hasNextPage!: boolean;
+
+  @Field(() => Boolean)
+  hasPreviousPage!: boolean;
+
+  @Field(() => Int)
+  page!: number;
+
+  @Field(() => Int)
+  pageSize!: number;
+
+  @Field(() => Int)
+  totalCount!: number;
+
+  @Field(() => Int)
+  totalPages!: number;
+}

package/src/lib/workflow-engine/approval-instance.entity.ts

@@ -0,0 +1,86 @@
+import { WorkflowDefinition } from '@rytass/bpm-core-shared/workflow';
+import { Field, ID, ObjectType } from '@nestjs/graphql';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { ApprovalInstanceStateEnum } from './workflow-engine.enums';
+
+@Entity('approval_instances')
+@ObjectType('ApprovalInstance')
+export class ApprovalInstanceEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'template_id' })
+  @Field(() => ID)
+  templateId!: string;
+
+  @Column('uuid', { name: 'template_version_id' })
+  @Field(() => ID)
+  templateVersionId!: string;
+
+  @Column('text', { name: 'initiator_member_id' })
+  @Field()
+  initiatorMemberId!: string;
+
+  @Column('jsonb', { name: 'initiator_metadata_snapshot' })
+  initiatorMetadataSnapshot!: Readonly<Record<string, unknown>>;
+
+  @Column('jsonb', { name: 'workflow_snapshot' })
+  workflowSnapshot!: WorkflowDefinition;
+
+  @Column('jsonb', { name: 'form_definition_snapshot' })
+  formDefinitionSnapshot!: Readonly<Record<string, unknown>>;
+
+  @Column('jsonb', { name: 'form_data' })
+  formData!: Readonly<Record<string, unknown>>;
+
+  @Column('text')
+  @Field(() => ApprovalInstanceStateEnum)
+  state!: ApprovalInstanceStateEnum;
+
+  @Column('text')
+  @Field()
+  title!: string;
+
+  @Column('timestamptz', { name: 'started_at' })
+  @Field()
+  startedAt!: Date;
+
+  @Column('timestamptz', { name: 'completed_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  completedAt!: Date | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  @Field()
+  createdAt!: Date;
+
+  @UpdateDateColumn({ name: 'updated_at', type: 'timestamptz' })
+  @Field()
+  updatedAt!: Date;
+
+  @Field(() => String)
+  get initiatorMetadataSnapshotJson(): string {
+    return JSON.stringify(this.initiatorMetadataSnapshot);
+  }
+
+  @Field(() => String)
+  get workflowSnapshotJson(): string {
+    return JSON.stringify(this.workflowSnapshot);
+  }
+
+  @Field(() => String)
+  get formDefinitionSnapshotJson(): string {
+    return JSON.stringify(this.formDefinitionSnapshot);
+  }
+
+  @Field(() => String)
+  get formDataJson(): string {
+    return JSON.stringify(this.formData);
+  }
+}

package/src/lib/workflow-engine/dto/adhoc-notification.input.ts

@@ -0,0 +1,18 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { Type } from 'class-transformer';
+import { IsEnum, IsOptional, ValidateNested } from 'class-validator';
+import { NotificationChannelEnum } from '../../notification/notification.enums';
+import { AdhocTargetInput } from './adhoc-target.input';
+
+@InputType()
+export class AdhocNotificationInput {
+  @Field(() => AdhocTargetInput)
+  @Type(() => AdhocTargetInput)
+  @ValidateNested()
+  target!: AdhocTargetInput;
+
+  @Field(() => [NotificationChannelEnum], { nullable: true })
+  @IsOptional()
+  @IsEnum(NotificationChannelEnum, { each: true })
+  channels?: readonly NotificationChannelEnum[] | null;
+}

package/src/lib/workflow-engine/dto/adhoc-target.input.ts

@@ -0,0 +1,52 @@
+import { Field, InputType } from '@nestjs/graphql';
+import {
+  IsBoolean,
+  IsEnum,
+  IsOptional,
+  IsString,
+  IsUrl,
+} from 'class-validator';
+import { AdhocTargetKindEnum } from '../adhoc.enums';
+
+/**
+ * Polymorphic ad-hoc target. Exactly the fields matching `kind` must be set:
+ * MEMBER → memberIds, POSITION → positionId, ORG_UNIT_MEMBER → orgUnitId
+ * (+ optional includeDescendants), WEBHOOK → webhookUrl (+ optional
+ * webhookHeadersJson). WEBHOOK is only valid for notification directives.
+ */
+@InputType()
+export class AdhocTargetInput {
+  @Field(() => AdhocTargetKindEnum)
+  @IsEnum(AdhocTargetKindEnum)
+  kind!: AdhocTargetKindEnum;
+
+  @Field(() => [String], { nullable: true })
+  @IsOptional()
+  @IsString({ each: true })
+  memberIds?: readonly string[] | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  positionId?: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  orgUnitId?: string | null;
+
+  @Field(() => Boolean, { nullable: true })
+  @IsOptional()
+  @IsBoolean()
+  includeDescendants?: boolean | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsUrl({ require_tld: false })
+  webhookUrl?: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  webhookHeadersJson?: string | null;
+}

package/src/lib/workflow-engine/dto/cancel-approval-instance.input.ts

@@ -0,0 +1,18 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { IsOptional, IsString, IsUUID } from 'class-validator';
+
+@InputType()
+export class CancelApprovalInstanceInput {
+  @Field()
+  @IsUUID()
+  instanceId!: string;
+
+  @Field()
+  @IsString()
+  cancelledByMemberId!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  comment!: string | null;
+}

package/src/lib/workflow-engine/dto/decide-task.input.ts

@@ -0,0 +1,33 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { IsEnum, IsOptional, IsString, IsUUID } from 'class-validator';
+import { TaskDecisionActionEnum } from '../workflow-engine.enums';
+
+@InputType()
+export class DecideTaskInput {
+  @Field()
+  @IsUUID()
+  taskId!: string;
+
+  @Field()
+  @IsString()
+  decidedByMemberId!: string;
+
+  @Field(() => TaskDecisionActionEnum)
+  @IsEnum(TaskDecisionActionEnum)
+  action!: TaskDecisionActionEnum;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  comment?: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  returnToNodeId?: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  transferToMemberId?: string | null;
+}

package/src/lib/workflow-engine/dto/dry-run-approval-workflow.input.ts

@@ -0,0 +1,22 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { IsOptional, IsString } from 'class-validator';
+
+@InputType()
+export class DryRunApprovalWorkflowInput {
+  @Field()
+  @IsString()
+  workflowDefinitionJson!: string;
+
+  @Field()
+  @IsString()
+  formDataJson!: string;
+
+  @Field()
+  @IsString()
+  initiatorMemberId!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  initiatorMetadataSnapshotJson!: string | null;
+}

package/src/lib/workflow-engine/dto/resubmit-approval-instance.input.ts

@@ -0,0 +1,22 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { IsOptional, IsString, IsUUID } from 'class-validator';
+
+@InputType()
+export class ResubmitApprovalInstanceInput {
+  @Field()
+  @IsUUID()
+  instanceId!: string;
+
+  @Field()
+  @IsString()
+  initiatorMemberId!: string;
+
+  @Field()
+  @IsString()
+  formDataJson!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  title!: string | null;
+}

package/src/lib/workflow-engine/dto/submit-approval-instance.input.ts

@@ -0,0 +1,27 @@
+import { Field, InputType } from '@nestjs/graphql';
+import { IsOptional, IsString, IsUUID } from 'class-validator';
+
+@InputType()
+export class SubmitApprovalInstanceInput {
+  @Field()
+  @IsUUID()
+  templateId!: string;
+
+  @Field()
+  @IsString()
+  initiatorMemberId!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  initiatorMetadataSnapshotJson!: string | null;
+
+  @Field()
+  @IsString()
+  formDataJson!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  title!: string | null;
+}

package/src/lib/workflow-engine/task-candidate.entity.ts

@@ -0,0 +1,56 @@
+import { Field, ID, ObjectType } from '@nestjs/graphql';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+import { TaskCandidateStatusEnum } from './workflow-engine.enums';
+
+@Entity('task_candidates')
+@ObjectType('TaskCandidate')
+export class TaskCandidateEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'task_id' })
+  @Field(() => ID)
+  taskId!: string;
+
+  @Column('text', { name: 'member_id' })
+  @Field()
+  memberId!: string;
+
+  @Column('text', { name: 'original_member_id' })
+  @Field()
+  originalMemberId!: string;
+
+  @Column('text', { name: 'source_type' })
+  @Field()
+  sourceType!: string;
+
+  @Column('jsonb', { name: 'delegation_chain' })
+  delegationChain!: readonly Readonly<Record<string, unknown>>[];
+
+  @Column('text')
+  @Field(() => TaskCandidateStatusEnum)
+  status!: TaskCandidateStatusEnum;
+
+  @Column('timestamptz', { name: 'claimed_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  claimedAt!: Date | null;
+
+  @Column('timestamptz', { name: 'decided_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  decidedAt!: Date | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  @Field()
+  createdAt!: Date;
+
+  @Field(() => String)
+  get delegationChainJson(): string {
+    return JSON.stringify(this.delegationChain);
+  }
+}

package/src/lib/workflow-engine/task-decision.entity.ts

@@ -0,0 +1,43 @@
+import { Field, ID, ObjectType } from '@nestjs/graphql';
+import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
+import { TaskDecisionActionEnum } from './workflow-engine.enums';
+
+@Entity('task_decisions')
+@ObjectType('TaskDecision')
+export class TaskDecisionEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'task_id' })
+  @Field(() => ID)
+  taskId!: string;
+
+  @Column('text', { name: 'decided_by_member_id' })
+  @Field()
+  decidedByMemberId!: string;
+
+  @Column('text')
+  @Field(() => TaskDecisionActionEnum)
+  action!: TaskDecisionActionEnum;
+
+  @Column('text', { nullable: true })
+  @Field(() => String, { nullable: true })
+  comment!: string | null;
+
+  @Column('text', { name: 'return_to_node_id', nullable: true })
+  @Field(() => String, { nullable: true })
+  returnToNodeId!: string | null;
+
+  @Column('text', { name: 'transfer_to_member_id', nullable: true })
+  @Field(() => String, { nullable: true })
+  transferToMemberId!: string | null;
+
+  @Column('uuid', { name: 'signature_id', nullable: true })
+  @Field(() => ID, { nullable: true })
+  signatureId!: string | null;
+
+  @Column('timestamptz', { name: 'decided_at' })
+  @Field()
+  decidedAt!: Date;
+}

package/src/lib/workflow-engine/task.entity.ts

@@ -0,0 +1,102 @@
+import { Field, ID, ObjectType } from '@nestjs/graphql';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+import { AdhocDirectiveTypeEnum } from './adhoc.enums';
+import {
+  TaskAssignmentTypeEnum,
+  TaskStatusEnum,
+} from './workflow-engine.enums';
+
+@Entity('tasks')
+@ObjectType('Task')
+export class TaskEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'instance_id' })
+  @Field(() => ID)
+  instanceId!: string;
+
+  @Column('uuid', { name: 'token_id' })
+  @Field(() => ID)
+  tokenId!: string;
+
+  @Column('text', { name: 'node_id' })
+  @Field()
+  nodeId!: string;
+
+  @Column('text', { name: 'original_assignee_member_id', nullable: true })
+  @Field(() => String, { nullable: true })
+  originalAssigneeMemberId!: string | null;
+
+  @Column('text', { name: 'assignee_member_id', nullable: true })
+  @Field(() => String, { nullable: true })
+  assigneeMemberId!: string | null;
+
+  @Column('text', {
+    default: TaskAssignmentTypeEnum.DIRECT_MEMBER,
+    name: 'assignment_type',
+  })
+  @Field(() => TaskAssignmentTypeEnum)
+  assignmentType!: TaskAssignmentTypeEnum;
+
+  @Column('jsonb', { default: { type: 'SINGLE' }, name: 'decision_policy_snapshot' })
+  decisionPolicySnapshot!: Readonly<Record<string, unknown>>;
+
+  @Column('jsonb', { name: 'delegation_chain' })
+  delegationChain!: readonly Readonly<Record<string, unknown>>[];
+
+  @Column('text')
+  @Field(() => TaskStatusEnum)
+  status!: TaskStatusEnum;
+
+  @Column('timestamptz', { name: 'sla_due_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  slaDueAt!: Date | null;
+
+  @Column('boolean', { default: false, name: 'is_adhoc' })
+  @Field()
+  isAdhoc!: boolean;
+
+  @Column('text', { name: 'adhoc_type', nullable: true })
+  @Field(() => AdhocDirectiveTypeEnum, { nullable: true })
+  adhocType!: AdhocDirectiveTypeEnum | null;
+
+  @Column('uuid', { name: 'adhoc_origin_task_id', nullable: true })
+  @Field(() => ID, { nullable: true })
+  adhocOriginTaskId!: string | null;
+
+  @Column('uuid', { name: 'adhoc_directive_id', nullable: true })
+  @Field(() => ID, { nullable: true })
+  adhocDirectiveId!: string | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  @Field()
+  createdAt!: Date;
+
+  @Column('timestamptz', { name: 'opened_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  openedAt!: Date | null;
+
+  @Column('timestamptz', { name: 'completed_at', nullable: true })
+  @Field(() => Date, { nullable: true })
+  completedAt!: Date | null;
+
+  @Field(() => String)
+  get delegationChainJson(): string {
+    return JSON.stringify(this.delegationChain);
+  }
+
+  @Field(() => String)
+  get decisionPolicySnapshotJson(): string {
+    return JSON.stringify(this.decisionPolicySnapshot);
+  }
+
+  @Field(() => [String])
+  candidateMemberIds: readonly string[] = [];
+}