@rytass/bpm-core-nestjs-module 0.1.1 → 0.1.3

package/src/lib/migrations/0000000013000-workflow-query-indexes.ts

@@ -0,0 +1,113 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class WorkflowQueryIndexes0000000013000 implements MigrationInterface {
+  readonly name = 'WorkflowQueryIndexes0000000013000';
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('CREATE EXTENSION IF NOT EXISTS "pg_trgm"');
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_created_desc"
+      ON "approval_instances" ("created_at" DESC)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_state_created_desc"
+      ON "approval_instances" ("state", "created_at" DESC)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_template_created_desc"
+      ON "approval_instances" ("template_id", "created_at" DESC)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_initiator_created_desc"
+      ON "approval_instances" ("initiator_member_id", "created_at" DESC)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_title_trgm"
+      ON "approval_instances"
+      USING gin (lower("title") gin_trgm_ops)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instances_initiator_trgm"
+      ON "approval_instances"
+      USING gin (lower("initiator_member_id") gin_trgm_ops)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_tasks_instance_assignee_read"
+      ON "tasks" ("instance_id", "assignee_member_id")
+      WHERE "assignee_member_id" IS NOT NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_tasks_instance_original_assignee_read"
+      ON "tasks" ("instance_id", "original_assignee_member_id")
+      WHERE "original_assignee_member_id" IS NOT NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_task_candidates_member_task"
+      ON "task_candidates" ("member_id", "task_id")
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_task_candidates_original_member_task"
+      ON "task_candidates" ("original_member_id", "task_id")
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_task_decisions_decider_task"
+      ON "task_decisions" ("decided_by_member_id", "task_id")
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_notifications_recipient_instance"
+      ON "notifications" ("recipient_member_id", "instance_id")
+      WHERE "instance_id" IS NOT NULL
+    `);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_notifications_recipient_instance"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_task_decisions_decider_task"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_task_candidates_original_member_task"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_task_candidates_member_task"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_tasks_instance_original_assignee_read"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_tasks_instance_assignee_read"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_initiator_trgm"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_title_trgm"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_initiator_created_desc"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_template_created_desc"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_state_created_desc"',
+    );
+    await queryRunner.query(
+      'DROP INDEX IF EXISTS "IDX_approval_instances_created_desc"',
+    );
+  }
+}

package/src/lib/migrations/index.ts

@@ -0,0 +1,47 @@
+import { MigrationInterface } from 'typeorm';
+import { EnablePostgresExtensions0000000000001 } from './0000000000001-enable-postgres-extensions';
+import { IdentityOrganizationFoundation0000000001000 } from './0000000001000-identity-organization-foundation';
+import { FormBuilderFoundation0000000002000 } from './0000000002000-form-builder-foundation';
+import { ApprovalTemplateFoundation0000000003000 } from './0000000003000-approval-template-foundation';
+import { WorkflowEngineFoundation0000000004000 } from './0000000004000-workflow-engine-foundation';
+import { DelegationRules0000000005000 } from './0000000005000-delegation-rules';
+import { NotificationsSla0000000006000 } from './0000000006000-notifications-sla';
+import { SignaturesAttachments0000000007000 } from './0000000007000-signatures-attachments';
+import { ApprovalTemplateCategories0000000008000 } from './0000000008000-approval-template-categories';
+import { TaskCandidates0000000009000 } from './0000000009000-task-candidates';
+import { NotificationDeliveryState0000000010000 } from './0000000010000-notification-delivery-state';
+import { RemoveAttachmentEncryptionKey0000000011000 } from './0000000011000-remove-attachment-encryption-key';
+import { NotificationSlaIdempotency0000000012000 } from './0000000012000-notification-sla-idempotency';
+import { WorkflowQueryIndexes0000000013000 } from './0000000013000-workflow-query-indexes';
+
+export const BPM_CORE_MIGRATIONS: readonly (new () => MigrationInterface)[] = [
+  EnablePostgresExtensions0000000000001,
+  IdentityOrganizationFoundation0000000001000,
+  FormBuilderFoundation0000000002000,
+  ApprovalTemplateFoundation0000000003000,
+  WorkflowEngineFoundation0000000004000,
+  DelegationRules0000000005000,
+  NotificationsSla0000000006000,
+  SignaturesAttachments0000000007000,
+  ApprovalTemplateCategories0000000008000,
+  TaskCandidates0000000009000,
+  NotificationDeliveryState0000000010000,
+  RemoveAttachmentEncryptionKey0000000011000,
+  NotificationSlaIdempotency0000000012000,
+  WorkflowQueryIndexes0000000013000,
+];
+
+export * from './0000000000001-enable-postgres-extensions';
+export * from './0000000001000-identity-organization-foundation';
+export * from './0000000002000-form-builder-foundation';
+export * from './0000000003000-approval-template-foundation';
+export * from './0000000004000-workflow-engine-foundation';
+export * from './0000000005000-delegation-rules';
+export * from './0000000006000-notifications-sla';
+export * from './0000000007000-signatures-attachments';
+export * from './0000000008000-approval-template-categories';
+export * from './0000000009000-task-candidates';
+export * from './0000000010000-notification-delivery-state';
+export * from './0000000011000-remove-attachment-encryption-key';
+export * from './0000000012000-notification-sla-idempotency';
+export * from './0000000013000-workflow-query-indexes';

package/src/lib/notification/dto/notification-preference.input.ts

@@ -0,0 +1,46 @@
+import { Field, InputType } from '@nestjs/graphql';
+import {
+  IsBoolean,
+  IsIn,
+  IsOptional,
+  IsString,
+  Matches,
+} from 'class-validator';
+import { NotificationDigestModeEnum } from '../notification.enums';
+
+const TIME_ONLY_PATTERN = /^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/;
+
+@InputType()
+export class UpdateNotificationPreferenceInput {
+  @Field()
+  @IsString()
+  memberId!: string;
+
+  @Field()
+  @IsBoolean()
+  inAppEnabled!: boolean;
+
+  @Field()
+  @IsBoolean()
+  emailEnabled!: boolean;
+
+  @Field(() => NotificationDigestModeEnum)
+  @IsIn(Object.values(NotificationDigestModeEnum))
+  emailDigestMode!: NotificationDigestModeEnum;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  @Matches(TIME_ONLY_PATTERN, {
+    message: 'quietHoursStart must use HH:mm or HH:mm:ss format',
+  })
+  quietHoursStart!: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  @Matches(TIME_ONLY_PATTERN, {
+    message: 'quietHoursEnd must use HH:mm or HH:mm:ss format',
+  })
+  quietHoursEnd!: string | null;
+}

package/src/lib/notification/notification-delivery-scheduler.service.ts

@@ -0,0 +1,69 @@
+import {
+  Inject,
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnApplicationShutdown,
+  Optional,
+} from '@nestjs/common';
+import { NotificationDeliveryService } from './notification-delivery.service';
+import {
+  BPM_NOTIFICATION_OPTIONS,
+  BPMResolvedNotificationOptions,
+  DEFAULT_BPM_NOTIFICATION_OPTIONS,
+} from './notification-options';
+
+@Injectable()
+export class NotificationDeliverySchedulerService
+  implements OnApplicationBootstrap, OnApplicationShutdown
+{
+  private readonly logger = new Logger(
+    NotificationDeliverySchedulerService.name,
+  );
+  private timer: NodeJS.Timeout | null = null;
+
+  constructor(
+    private readonly deliveryService: NotificationDeliveryService,
+    @Optional()
+    @Inject(BPM_NOTIFICATION_OPTIONS)
+    private readonly notificationOptions: BPMResolvedNotificationOptions = DEFAULT_BPM_NOTIFICATION_OPTIONS,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (
+      process.env.NODE_ENV === 'test' ||
+      !this.notificationOptions.deliverySchedulerEnabled
+    ) {
+      return;
+    }
+
+    this.timer = setInterval((): void => {
+      void this.scanPendingDeliveries();
+    }, this.notificationOptions.deliveryScanIntervalMs);
+    this.timer.unref();
+  }
+
+  onApplicationShutdown(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private async scanPendingDeliveries(): Promise<void> {
+    try {
+      const deliveredCount =
+        await this.deliveryService.deliverPendingNotifications({
+          options: this.notificationOptions,
+        });
+
+      if (deliveredCount) {
+        this.logger.log(`Delivered ${deliveredCount} pending notifications`);
+      }
+    } catch (error: unknown) {
+      this.logger.error(
+        error instanceof Error ? error.message : 'Delivery scan failed',
+      );
+    }
+  }
+}

package/src/lib/notification/notification-delivery.service.spec.ts

@@ -0,0 +1,315 @@
+import * as nodemailer from 'nodemailer';
+import { ModuleRef } from '@nestjs/core';
+import { Repository } from 'typeorm';
+import { IdentityService } from '../identity/identity.service';
+import { NotificationDeliveryService } from './notification-delivery.service';
+import {
+  BPM_NOTIFICATION_DISPATCHER,
+  BPMNotificationDispatcher,
+} from './notification-dispatcher.token';
+import { NotificationEntity } from './notification.entity';
+import {
+  NotificationChannelEnum,
+  NotificationStatusEnum,
+  NotificationTypeEnum,
+} from './notification.enums';
+import { DEFAULT_BPM_NOTIFICATION_OPTIONS } from './notification-options';
+
+describe('NotificationDeliveryService', () => {
+  afterEach((): void => {
+    jest.restoreAllMocks();
+  });
+
+  it('sends pending email notifications through SMTP and marks them sent', async (): Promise<void> => {
+    const sendMail = jest.fn((): Promise<void> => Promise.resolve());
+    jest.spyOn(nodemailer, 'createTransport').mockReturnValue({
+      sendMail,
+    } as unknown as ReturnType<typeof nodemailer.createTransport>);
+    const notification = createNotification(NotificationChannelEnum.EMAIL);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await expect(
+      service.deliverNotification(notification, {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        emailEnabled: true,
+        emailFrom: 'BPM <bpm@example.com>',
+        emailSmtpHost: 'smtp.example.com',
+        emailSmtpPassword: 'secret',
+        emailSmtpPort: 587,
+        emailSmtpSecure: false,
+        emailSmtpUsername: 'bpm@example.com',
+      }),
+    ).resolves.toBe(true);
+
+    expect(sendMail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        from: 'BPM <bpm@example.com>',
+        subject: notification.title,
+        text: notification.body,
+        to: 'member-001@example.com',
+      }),
+    );
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: NotificationStatusEnum.SENT,
+        deliveryTarget: 'member-001@example.com',
+      }),
+    );
+  });
+
+  it('sends signed webhook notifications', async (): Promise<void> => {
+    const fetchMock = jest.fn(() =>
+      Promise.resolve({
+        ok: true,
+        status: 200,
+      }),
+    );
+    jest
+      .spyOn(globalThis, 'fetch')
+      .mockImplementation(fetchMock as unknown as typeof fetch);
+    const notification = createNotification(NotificationChannelEnum.WEBHOOK);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await expect(
+      service.deliverNotification(notification, {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        webhookEnabled: true,
+        webhookEndpointUrl: 'https://example.com/bpm-webhook',
+        webhookSigningSecret: 'secret',
+      }),
+    ).resolves.toBe(true);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://example.com/bpm-webhook',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          'x-bpm-signature-sha256': expect.any(String),
+        }),
+        method: 'POST',
+      }),
+    );
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: NotificationStatusEnum.SENT,
+        deliveryTarget: 'https://example.com/bpm-webhook',
+      }),
+    );
+  });
+
+  it('dispatches email and webhook notifications through a host dispatcher when provided', async (): Promise<void> => {
+    const dispatch = jest.fn((): Promise<string> => Promise.resolve('queue-1'));
+    const notification = createNotification(NotificationChannelEnum.EMAIL);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef({
+        dispatch,
+      }),
+    );
+
+    await expect(
+      service.deliverNotification(notification, DEFAULT_BPM_NOTIFICATION_OPTIONS),
+    ).resolves.toBe(true);
+
+    expect(dispatch).toHaveBeenCalledWith(
+      notification,
+      DEFAULT_BPM_NOTIFICATION_OPTIONS,
+    );
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({
+        deliveryTarget: 'queue-1',
+        status: NotificationStatusEnum.SENT,
+      }),
+    );
+  });
+
+  it('records delivery failures and schedules a retry', async (): Promise<void> => {
+    const notification = createNotification(NotificationChannelEnum.EMAIL);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await expect(
+      service.deliverNotification(notification, {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        emailEnabled: false,
+      }),
+    ).resolves.toBe(false);
+
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attemptCount: 1,
+        deliveryError: 'EMAIL_DISABLED',
+        nextRetryAt: expect.any(Date),
+        status: NotificationStatusEnum.PENDING,
+      }),
+    );
+  });
+
+  it('uses configured retry policy and marks notifications failed after max attempts', async (): Promise<void> => {
+    const notification = Object.assign(
+      createNotification(NotificationChannelEnum.EMAIL),
+      { attemptCount: 1 },
+    );
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await expect(
+      service.deliverNotification(notification, {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        deliveryMaxAttempts: 2,
+        deliveryRetryBaseDelayMs: 5_000,
+        emailEnabled: false,
+      }),
+    ).resolves.toBe(false);
+
+    expect(repository.save).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attemptCount: 2,
+        nextRetryAt: null,
+        status: NotificationStatusEnum.FAILED,
+      }),
+    );
+  });
+
+  it('uses configured batch size when scanning pending notifications', async (): Promise<void> => {
+    const notification = createNotification(NotificationChannelEnum.IN_APP);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await service.deliverPendingNotifications({
+      options: {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        deliveryBatchSize: 7,
+      },
+    });
+
+    expect(repository.find).toHaveBeenCalledWith(
+      expect.objectContaining({ take: 7 }),
+    );
+  });
+
+  it('includes stale in-progress notifications in the next delivery scan', async (): Promise<void> => {
+    const notification = createNotification(NotificationChannelEnum.IN_APP);
+    const repository = createNotificationRepository(notification);
+    const service = new NotificationDeliveryService(
+      repository,
+      createModuleRef(),
+    );
+
+    await service.deliverPendingNotifications({
+      now: new Date('2026-05-15T00:10:00.000Z'),
+      options: {
+        ...DEFAULT_BPM_NOTIFICATION_OPTIONS,
+        deliveryRetryBaseDelayMs: 60_000,
+      },
+    });
+
+    expect(repository.find).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.arrayContaining([
+          expect.objectContaining({
+            lastAttemptAt: expect.any(Object),
+            status: NotificationStatusEnum.DELIVERY_IN_PROGRESS,
+          }),
+        ]),
+      }),
+    );
+  });
+});
+
+function createNotification(
+  channel: NotificationChannelEnum,
+): NotificationEntity {
+  return Object.assign(new NotificationEntity(), {
+    attemptCount: 0,
+    body: '請處理待簽任務。',
+    channel,
+    createdAt: new Date('2026-05-15T00:00:00.000Z'),
+    deliveredAt: null,
+    deliveryError: null,
+    deliveryTarget: null,
+    id: 'notification-001',
+    instanceId: 'd6f61a56-8b12-4ab8-9424-a2f7c27874e2',
+    lastAttemptAt: null,
+    nextRetryAt: null,
+    payload: { instanceTitle: '採購申請' },
+    readAt: null,
+    recipientMemberId: 'member-001',
+    sentAt: null,
+    status: NotificationStatusEnum.PENDING,
+    taskId: 'f4fae7b0-eab0-40de-8dfa-7dfbff746980',
+    title: '新的待簽任務',
+    type: NotificationTypeEnum.TASK_ASSIGNED,
+  });
+}
+
+function createNotificationRepository(
+  notification: NotificationEntity,
+): Repository<NotificationEntity> & {
+  readonly find: jest.Mock;
+  readonly save: jest.Mock;
+} {
+  const repository = {
+    find: jest.fn(
+      (): Promise<readonly NotificationEntity[]> =>
+        Promise.resolve([notification]),
+    ),
+    save: jest.fn(
+      (entity: NotificationEntity): Promise<NotificationEntity> =>
+        Promise.resolve(entity),
+    ),
+  };
+
+  return repository as unknown as Repository<NotificationEntity> & {
+    readonly find: jest.Mock;
+    readonly save: jest.Mock;
+  };
+}
+
+function createModuleRef(
+  dispatcher?: BPMNotificationDispatcher,
+): ModuleRef {
+  return {
+    get: (token: unknown): BPMNotificationDispatcher | IdentityService => {
+      if (token === BPM_NOTIFICATION_DISPATCHER && dispatcher) {
+        return dispatcher;
+      }
+
+      if (token !== IdentityService) {
+        throw new Error('Unexpected module token');
+      }
+
+      return {
+        resolveMember: (): Promise<{
+          readonly customFields: Readonly<Record<string, unknown>>;
+          readonly email: string;
+          readonly memberId: string;
+          readonly name: string;
+        }> =>
+          Promise.resolve({
+            customFields: {},
+            email: 'member-001@example.com',
+            memberId: 'member-001',
+            name: '王小明',
+          }),
+      } as unknown as IdentityService;
+    },
+  } as unknown as ModuleRef;
+}