@gadmin2n/schematics 0.0.138 → 0.0.140

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/external-interaction.service.spec.ts

@@ -0,0 +1,240 @@
+import { ExternalInteractionHandlerRegistry } from './external-interaction-handler.registry';
+import { createCallbackToken } from './external-interaction-token';
+import { ExternalInteractionService } from './external-interaction.service';
+import { ExternalWaitHandler } from './external-wait.handler';
+
+describe('ExternalInteractionService', () => {
+  const now = new Date('2026-07-28T00:00:00.000Z');
+
+  it('creates an idempotent interaction with a caller-provided token', async () => {
+    const { token, tokenHash } = createCallbackToken();
+    const tx = {
+      externalInteraction: {
+        findUnique: jest.fn().mockResolvedValue(null),
+        create: jest.fn().mockImplementation(({ data }) => ({
+          id: BigInt(51),
+          status: 'PENDING',
+          ...data,
+        })),
+      },
+    };
+    const prisma = { $transaction: jest.fn((callback) => callback(tx)) };
+    const registry = new ExternalInteractionHandlerRegistry();
+    registry.register(new ExternalWaitHandler());
+    const service = new ExternalInteractionService(
+      prisma as any,
+      registry,
+      () => now,
+    );
+
+    await expect(
+      service.createInteraction({
+        callbackToken: token,
+        tenantNamespace: 'tenant-a',
+        handlerType: 'EXTERNAL_WAIT',
+        handlerConfig: { allowedOutcomes: ['SIGNED'] },
+        workflowInstanceId: '91',
+        workflowVersionId: '12',
+        temporalRunId: 'wf-91',
+        nodeId: 'external-wait-1',
+        expiresAt: '2026-07-29T00:00:00.000Z',
+      }),
+    ).resolves.toEqual({
+      interactionId: '51',
+      callbackToken: token,
+      status: 'PENDING',
+    });
+    expect(tx.externalInteraction.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        tokenHash,
+        workflowInstanceId: BigInt(91),
+        workflowVersionId: BigInt(12),
+      }),
+    });
+  });
+
+  function setup(overrides: Record<string, unknown> = {}) {
+    const { token, tokenHash } = createCallbackToken();
+    const interaction = {
+      id: BigInt(41),
+      tokenHash,
+      tenantNamespace: 'tenant-a',
+      handlerType: 'EXTERNAL_WAIT',
+      handlerConfig: { allowedOutcomes: ['SIGNED', 'REJECTED'] },
+      workflowInstanceId: BigInt(91),
+      workflowVersionId: BigInt(12),
+      temporalRunId: 'wf-91',
+      nodeId: 'external-wait-1',
+      status: 'PENDING',
+      expiresAt: new Date('2026-07-29T00:00:00.000Z'),
+      resolution: null,
+      resolvedAt: null,
+      ...overrides,
+    };
+    const tx = {
+      externalInteraction: {
+        findUnique: jest.fn().mockResolvedValue(interaction),
+        updateMany: jest.fn().mockResolvedValue({ count: 1 }),
+      },
+      externalInteractionEvent: {
+        findUnique: jest.fn().mockResolvedValue(null),
+        create: jest.fn().mockImplementation(({ data }) => ({
+          id: BigInt(1),
+          ...data,
+        })),
+      },
+      externalInteractionSignalOutbox: {
+        create: jest.fn().mockResolvedValue({ id: BigInt(1) }),
+      },
+    };
+    const prisma = {
+      $transaction: jest.fn((callback) => callback(tx)),
+    };
+    const registry = new ExternalInteractionHandlerRegistry();
+    registry.register(new ExternalWaitHandler());
+    const service = new ExternalInteractionService(
+      prisma as any,
+      registry,
+      () => now,
+    );
+    return { interaction, prisma, service, token, tx };
+  }
+
+  it('resolves an external wait on the first allowed outcome', async () => {
+    const { service, token, tx } = setup();
+
+    await expect(
+      service.submitResult('tenant-a', {
+        callbackToken: token,
+        eventId: 'provider-1001',
+        outcome: 'SIGNED',
+        operatorId: 'alice',
+        data: { fileUrl: 'https://example.test/signed.pdf' },
+      }),
+    ).resolves.toEqual({
+      accepted: true,
+      duplicate: false,
+      interactionStatus: 'RESOLVED',
+      resolvedOutcome: 'SIGNED',
+    });
+    expect(tx.externalInteraction.updateMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: BigInt(41), status: 'PENDING' },
+        data: expect.objectContaining({ status: 'RESOLVED' }),
+      }),
+    );
+    expect(tx.externalInteractionSignalOutbox.create).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the original response for a duplicate event', async () => {
+    const original = {
+      accepted: true,
+      duplicate: false,
+      interactionStatus: 'PENDING',
+    };
+    const { service, token, tx } = setup();
+    tx.externalInteractionEvent.findUnique.mockResolvedValue({
+      response: original,
+    });
+
+    await expect(
+      service.submitResult('tenant-a', {
+        callbackToken: token,
+        eventId: 'provider-1001',
+        outcome: 'SIGNED',
+      }),
+    ).resolves.toEqual({ ...original, duplicate: true });
+    expect(tx.externalInteraction.updateMany).not.toHaveBeenCalled();
+    expect(tx.externalInteractionEvent.create).not.toHaveBeenCalled();
+  });
+
+  it('records a rejected event without resolving for an unsupported outcome', async () => {
+    const { service, token, tx } = setup();
+
+    await expect(
+      service.submitResult('tenant-a', {
+        callbackToken: token,
+        eventId: 'provider-1002',
+        outcome: 'UNKNOWN',
+      }),
+    ).resolves.toEqual({
+      accepted: false,
+      duplicate: false,
+      interactionStatus: 'PENDING',
+      errorCode: 'OUTCOME_NOT_ALLOWED',
+      message: '当前处理结果不在允许列表中',
+    });
+    expect(tx.externalInteraction.updateMany).not.toHaveBeenCalled();
+    expect(tx.externalInteractionEvent.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({ processingStatus: 'REJECTED' }),
+    });
+  });
+
+  it('expires a pending interaction before accepting a late event', async () => {
+    const { service, token, tx } = setup({
+      expiresAt: new Date('2026-07-27T00:00:00.000Z'),
+    });
+
+    await expect(
+      service.submitResult('tenant-a', {
+        callbackToken: token,
+        eventId: 'provider-1003',
+        outcome: 'SIGNED',
+      }),
+    ).resolves.toEqual({
+      accepted: false,
+      duplicate: false,
+      interactionStatus: 'EXPIRED',
+      errorCode: 'EXTERNAL_INTERACTION_EXPIRED',
+      message: '外部处理已过期',
+    });
+    expect(tx.externalInteraction.updateMany).toHaveBeenCalledWith({
+      where: { id: BigInt(41), status: 'PENDING' },
+      data: { status: 'EXPIRED', resolvedAt: now },
+    });
+  });
+
+  it('does not reveal whether a token belongs to another tenant', async () => {
+    const { service, token } = setup();
+
+    await expect(
+      service.submitResult('tenant-b', {
+        callbackToken: token,
+        eventId: 'provider-1004',
+        outcome: 'SIGNED',
+      }),
+    ).rejects.toMatchObject({
+      response: {
+        code: 'EXTERNAL_INTERACTION_TOKEN_INVALID',
+        message: '回调凭证无效',
+      },
+    });
+  });
+
+  it('returns a concurrently resolved result instead of expiring it', async () => {
+    const { interaction, service, token, tx } = setup();
+    tx.externalInteraction.updateMany.mockResolvedValue({ count: 0 });
+    tx.externalInteraction.findUnique
+      .mockResolvedValueOnce(interaction)
+      .mockResolvedValueOnce({
+        ...interaction,
+        status: 'RESOLVED',
+        resolution: {
+          outcome: 'SIGNED',
+          output: { outcome: 'SIGNED' },
+          completedAt: now.toISOString(),
+        },
+      });
+
+    await expect(service.expireInteraction('tenant-a', token)).resolves.toEqual(
+      {
+        status: 'RESOLVED',
+        resolution: {
+          outcome: 'SIGNED',
+          output: { outcome: 'SIGNED' },
+          completedAt: now.toISOString(),
+        },
+      },
+    );
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/external-interaction.service.ts

@@ -0,0 +1,339 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Inject,
+  Injectable,
+  Optional,
+} from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { PrismaService } from 'nestjs-prisma';
+import { ExternalInteractionHandlerRegistry } from './external-interaction-handler.registry';
+import {
+  createCallbackToken,
+  hashCallbackToken,
+} from './external-interaction-token';
+import {
+  CloseExternalInteractionResponse,
+  CreateExternalInteractionInput,
+  CreateExternalInteractionResponse,
+  ExternalHandlerResult,
+  ExternalInteractionRecord,
+  ExternalResultInput,
+  ExternalResultResponse,
+} from './external-interaction.types';
+
+export const EXTERNAL_INTERACTION_CLOCK = Symbol('EXTERNAL_INTERACTION_CLOCK');
+
+@Injectable()
+export class ExternalInteractionService {
+  private readonly currentTime: () => Date;
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly handlers: ExternalInteractionHandlerRegistry,
+    @Optional()
+    @Inject(EXTERNAL_INTERACTION_CLOCK)
+    clock?: () => Date,
+  ) {
+    this.currentTime = clock ?? (() => new Date());
+  }
+
+  createInteraction(
+    input: CreateExternalInteractionInput,
+  ): Promise<CreateExternalInteractionResponse> {
+    return this.prisma.$transaction((tx) =>
+      this.createInteractionInTransaction(input, tx),
+    );
+  }
+
+  createInteractionInTransaction(
+    input: CreateExternalInteractionInput,
+    tx: Pick<Prisma.TransactionClient, 'externalInteraction'>,
+  ): Promise<CreateExternalInteractionResponse> {
+    this.handlers.get(input.handlerType);
+    const generated = input.callbackToken
+      ? {
+          token: input.callbackToken,
+          tokenHash: hashCallbackToken(input.callbackToken),
+        }
+      : createCallbackToken();
+    const workflowInstanceId = parseId(input.workflowInstanceId);
+    const workflowVersionId = parseId(input.workflowVersionId);
+    const expiresAt = input.expiresAt ? new Date(input.expiresAt) : undefined;
+    if (expiresAt && !Number.isFinite(expiresAt.getTime())) {
+      throw new BadRequestException({
+        code: 'EXTERNAL_INTERACTION_INPUT_INVALID',
+        message: 'expiresAt 必须是有效时间',
+      });
+    }
+
+    return (async () => {
+      const existing = await tx.externalInteraction.findUnique({
+        where: {
+          workflowInstanceId_nodeId: {
+            workflowInstanceId,
+            nodeId: input.nodeId,
+          },
+        },
+      });
+      if (existing) {
+        if (existing.tokenHash !== generated.tokenHash) {
+          throw new ConflictException({
+            code: 'EXTERNAL_INTERACTION_TOKEN_CONFLICT',
+            message: '该等待节点已经创建了其他回调凭证',
+          });
+        }
+        return {
+          interactionId: String(existing.id),
+          callbackToken: generated.token,
+          status: existing.status,
+        };
+      }
+
+      const interaction = await tx.externalInteraction.create({
+        data: {
+          tokenHash: generated.tokenHash,
+          tenantNamespace: input.tenantNamespace,
+          handlerType: input.handlerType,
+          handlerConfig: input.handlerConfig as Prisma.InputJsonValue,
+          workflowInstanceId,
+          workflowVersionId,
+          temporalRunId: input.temporalRunId,
+          nodeId: input.nodeId,
+          ...(expiresAt && { expiresAt }),
+        },
+      });
+      return {
+        interactionId: String(interaction.id),
+        callbackToken: generated.token,
+        status: interaction.status,
+      };
+    })();
+  }
+
+  submitResult(
+    tenantNamespace: string,
+    input: ExternalResultInput,
+  ): Promise<ExternalResultResponse> {
+    const tokenHash = hashCallbackToken(input.callbackToken);
+    return this.prisma.$transaction(async (tx) => {
+      await lockInteractionByToken(tx, tokenHash);
+      const interaction = await tx.externalInteraction.findUnique({
+        where: { tokenHash },
+      });
+      if (!interaction || interaction.tenantNamespace !== tenantNamespace) {
+        throw invalidToken();
+      }
+
+      const duplicate = await tx.externalInteractionEvent.findUnique({
+        where: {
+          interactionId_eventId: {
+            interactionId: interaction.id,
+            eventId: input.eventId,
+          },
+        },
+      });
+      if (duplicate) {
+        return {
+          ...(duplicate.response as unknown as ExternalResultResponse),
+          duplicate: true,
+        };
+      }
+
+      const now = this.currentTime();
+      if (
+        interaction.status === 'PENDING' &&
+        interaction.expiresAt &&
+        interaction.expiresAt.getTime() <= now.getTime()
+      ) {
+        await tx.externalInteraction.updateMany({
+          where: { id: interaction.id, status: 'PENDING' },
+          data: { status: 'EXPIRED', resolvedAt: now },
+        });
+        return {
+          accepted: false,
+          duplicate: false,
+          interactionStatus: 'EXPIRED',
+          errorCode: 'EXTERNAL_INTERACTION_EXPIRED',
+          message: '外部处理已过期',
+        };
+      }
+      if (interaction.status !== 'PENDING') {
+        throw new ConflictException({
+          code: 'EXTERNAL_INTERACTION_CLOSED',
+          message: '外部处理已经结束',
+          status: interaction.status,
+        });
+      }
+
+      const handler = this.handlers.get(interaction.handlerType);
+      const result = await handler.handle(
+        interaction as ExternalInteractionRecord,
+        input,
+        tx,
+      );
+      const response = toResponse(result);
+
+      if (result.state === 'RESOLVED') {
+        const resolution = {
+          outcome: result.outcome,
+          ...(result.output !== undefined && { output: result.output }),
+          completedAt: now.toISOString(),
+        };
+        const changed = await tx.externalInteraction.updateMany({
+          where: { id: interaction.id, status: 'PENDING' },
+          data: {
+            status: 'RESOLVED',
+            resolution: resolution as Prisma.InputJsonValue,
+            resolvedAt: now,
+          },
+        });
+        if (changed.count !== 1) {
+          throw new ConflictException({
+            code: 'EXTERNAL_INTERACTION_STATE_CONFLICT',
+            message: '外部处理状态已经发生变化',
+          });
+        }
+        await tx.externalInteractionSignalOutbox.create({
+          data: {
+            interactionId: interaction.id,
+            idempotencyKey: `external-interaction:${interaction.id}:resolved`,
+            signalName: result.signal?.name ?? 'externalInteractionResolved',
+            payload: (result.signal?.payload ?? {
+              nodeId: interaction.nodeId,
+              outcome: result.outcome,
+              ...(input.operatorId && { operatorId: input.operatorId }),
+              ...(input.data && { data: input.data }),
+              completedAt: now.toISOString(),
+            }) as Prisma.InputJsonValue,
+          },
+        });
+      }
+
+      await tx.externalInteractionEvent.create({
+        data: {
+          interactionId: interaction.id,
+          eventId: input.eventId,
+          outcome: input.outcome,
+          ...(input.operatorId && { operatorId: input.operatorId }),
+          ...(input.data && {
+            data: input.data as Prisma.InputJsonValue,
+          }),
+          processingStatus:
+            result.state === 'REJECTED' ? 'REJECTED' : 'ACCEPTED',
+          response: response as unknown as Prisma.InputJsonValue,
+          ...(result.errorCode && { errorCode: result.errorCode }),
+          ...(result.errorMessage && {
+            errorMessage: result.errorMessage,
+          }),
+        },
+      });
+      return response;
+    });
+  }
+
+  expireInteraction(
+    tenantNamespace: string,
+    callbackToken: string,
+  ): Promise<CloseExternalInteractionResponse> {
+    return this.closeInteraction(tenantNamespace, callbackToken, 'EXPIRED');
+  }
+
+  cancelInteraction(
+    tenantNamespace: string,
+    callbackToken: string,
+  ): Promise<CloseExternalInteractionResponse> {
+    return this.closeInteraction(tenantNamespace, callbackToken, 'CANCELLED');
+  }
+
+  private closeInteraction(
+    tenantNamespace: string,
+    callbackToken: string,
+    target: 'EXPIRED' | 'CANCELLED',
+  ): Promise<CloseExternalInteractionResponse> {
+    const tokenHash = hashCallbackToken(callbackToken);
+    return this.prisma.$transaction(async (tx) => {
+      await lockInteractionByToken(tx, tokenHash);
+      const interaction = await tx.externalInteraction.findUnique({
+        where: { tokenHash },
+      });
+      if (!interaction || interaction.tenantNamespace !== tenantNamespace) {
+        throw invalidToken();
+      }
+      if (interaction.status === 'PENDING') {
+        const changed = await tx.externalInteraction.updateMany({
+          where: { id: interaction.id, status: 'PENDING' },
+          data: { status: target, resolvedAt: this.currentTime() },
+        });
+        if (changed.count === 1) return { status: target };
+      }
+      const current = await tx.externalInteraction.findUnique({
+        where: { id: interaction.id },
+      });
+      if (!current) throw invalidToken();
+      return {
+        status: current.status,
+        ...(current.resolution && {
+          resolution: current.resolution as unknown as {
+            outcome: string;
+            output?: unknown;
+            completedAt?: string;
+          },
+        }),
+      };
+    });
+  }
+}
+
+function toResponse(result: ExternalHandlerResult): ExternalResultResponse {
+  if (result.state === 'REJECTED') {
+    return {
+      accepted: false,
+      duplicate: false,
+      interactionStatus: 'PENDING',
+      errorCode: result.errorCode,
+      message: result.errorMessage,
+    };
+  }
+  if (result.state === 'PENDING') {
+    return {
+      accepted: true,
+      duplicate: false,
+      interactionStatus: 'PENDING',
+    };
+  }
+  return {
+    accepted: true,
+    duplicate: false,
+    interactionStatus: 'RESOLVED',
+    resolvedOutcome: result.outcome,
+  };
+}
+
+function invalidToken(): BadRequestException {
+  return new BadRequestException({
+    code: 'EXTERNAL_INTERACTION_TOKEN_INVALID',
+    message: '回调凭证无效',
+  });
+}
+
+function parseId(value: string): bigint {
+  if (!/^[1-9][0-9]*$/.test(value)) {
+    throw new BadRequestException({
+      code: 'EXTERNAL_INTERACTION_INPUT_INVALID',
+      message: 'Workflow IDs 必须是正整数',
+    });
+  }
+  return BigInt(value);
+}
+
+async function lockInteractionByToken(
+  tx: Prisma.TransactionClient,
+  tokenHash: string,
+): Promise<void> {
+  if (typeof (tx as any).$queryRawUnsafe !== 'function') return;
+  await (tx as any).$queryRawUnsafe(
+    'SELECT id FROM t_external_interaction WHERE token_hash = $1 FOR UPDATE',
+    tokenHash,
+  );
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/external-interaction.types.ts

@@ -0,0 +1,74 @@
+export type ExternalInteractionStatus =
+  | 'PENDING'
+  | 'RESOLVED'
+  | 'CANCELLED'
+  | 'EXPIRED';
+
+export interface ExternalResultInput {
+  callbackToken: string;
+  eventId: string;
+  outcome: string;
+  operatorId?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface ExternalResultResponse {
+  accepted: boolean;
+  duplicate: boolean;
+  interactionStatus: ExternalInteractionStatus;
+  resolvedOutcome?: string;
+  errorCode?: string;
+  message?: string;
+}
+
+export interface CreateExternalInteractionInput {
+  callbackToken?: string;
+  tenantNamespace: string;
+  handlerType: string;
+  handlerConfig: Record<string, unknown>;
+  workflowInstanceId: string;
+  workflowVersionId: string;
+  temporalRunId: string;
+  nodeId: string;
+  expiresAt?: string;
+}
+
+export interface CreateExternalInteractionResponse {
+  interactionId: string;
+  callbackToken: string;
+  status: ExternalInteractionStatus;
+}
+
+export interface CloseExternalInteractionResponse {
+  status: ExternalInteractionStatus;
+  resolution?: {
+    outcome: string;
+    output?: unknown;
+    completedAt?: string;
+  };
+}
+
+export interface ExternalInteractionRecord {
+  id: bigint;
+  tenantNamespace: string;
+  handlerType: string;
+  handlerConfig: unknown;
+  workflowInstanceId: bigint;
+  workflowVersionId: bigint;
+  temporalRunId: string;
+  nodeId: string;
+  status: ExternalInteractionStatus;
+  expiresAt: Date | null;
+}
+
+export interface ExternalHandlerResult {
+  state: 'PENDING' | 'RESOLVED' | 'REJECTED';
+  outcome?: string;
+  output?: unknown;
+  errorCode?: string;
+  errorMessage?: string;
+  signal?: {
+    name: string;
+    payload: Record<string, unknown>;
+  };
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/external-wait.handler.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import { ExternalInteractionHandler } from './external-interaction-handler';
+import {
+  ExternalHandlerResult,
+  ExternalInteractionRecord,
+  ExternalResultInput,
+} from './external-interaction.types';
+
+@Injectable()
+export class ExternalWaitHandler implements ExternalInteractionHandler {
+  readonly type = 'EXTERNAL_WAIT';
+
+  handle(
+    interaction: ExternalInteractionRecord,
+    event: ExternalResultInput,
+  ): ExternalHandlerResult {
+    const config = asObject(interaction.handlerConfig);
+    const allowedOutcomes = Array.isArray(config.allowedOutcomes)
+      ? config.allowedOutcomes.filter(
+          (value): value is string =>
+            typeof value === 'string' && Boolean(value.trim()),
+        )
+      : [];
+    if (!allowedOutcomes.includes(event.outcome)) {
+      return {
+        state: 'REJECTED',
+        errorCode: 'OUTCOME_NOT_ALLOWED',
+        errorMessage: '当前处理结果不在允许列表中',
+      };
+    }
+    return {
+      state: 'RESOLVED',
+      outcome: event.outcome,
+      output: {
+        outcome: event.outcome,
+        ...(event.operatorId && { operatorId: event.operatorId }),
+        ...(event.data && { data: event.data }),
+      },
+    };
+  }
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}