@gadmin2n/schematics 0.0.139 → 0.0.140

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

@@ -0,0 +1,41 @@
+import { Injectable, Module, OnModuleInit } from '@nestjs/common';
+import { RuntimeTokenGuard } from '../humanApproval/runtime/runtime-token.guard';
+import { TemporalModule } from '../workflow/temporal.module';
+import { ExternalInteractionHandlerRegistry } from './external-interaction-handler.registry';
+import { ExternalInteractionRuntimeController } from './external-interaction-runtime.controller';
+import { ExternalInteractionSignalOutboxService } from './external-interaction-signal-outbox.service';
+import { ExternalInteractionService } from './external-interaction.service';
+import { ExternalWaitHandler } from './external-wait.handler';
+import { WorkflowCallbackUrlController } from './workflow-callback-url.controller';
+import { WorkflowCallbackUrlService } from './workflow-callback-url.service';
+
+@Injectable()
+class ExternalInteractionHandlerRegistrar implements OnModuleInit {
+  constructor(
+    private readonly handlers: ExternalInteractionHandlerRegistry,
+    private readonly externalWait: ExternalWaitHandler,
+  ) {}
+
+  onModuleInit(): void {
+    this.handlers.register(this.externalWait);
+  }
+}
+
+@Module({
+  imports: [TemporalModule],
+  controllers: [
+    ExternalInteractionRuntimeController,
+    WorkflowCallbackUrlController,
+  ],
+  providers: [
+    ExternalInteractionHandlerRegistry,
+    ExternalInteractionService,
+    ExternalWaitHandler,
+    ExternalInteractionHandlerRegistrar,
+    ExternalInteractionSignalOutboxService,
+    WorkflowCallbackUrlService,
+    RuntimeTokenGuard,
+  ],
+  exports: [ExternalInteractionHandlerRegistry, ExternalInteractionService],
+})
+export class ExternalInteractionModule {}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/human-approval.handler.spec.ts

@@ -0,0 +1,70 @@
+import { HumanApprovalHandler } from './human-approval.handler';
+
+describe('HumanApprovalHandler', () => {
+  const interaction = {
+    id: BigInt(51),
+    tenantNamespace: 'tenant-a',
+    handlerType: 'HUMAN_APPROVAL',
+    handlerConfig: { approvalRequestId: '41' },
+    workflowInstanceId: BigInt(7),
+    workflowVersionId: BigInt(3),
+    temporalRunId: 'wf-7',
+    nodeId: 'approval-1',
+    status: 'PENDING' as const,
+    expiresAt: null,
+  };
+
+  it('keeps a multi-approver request pending after a partial decision', async () => {
+    const approvals = {
+      handleExternalInteractionDecision: jest.fn().mockResolvedValue('PENDING'),
+    };
+    const handler = new HumanApprovalHandler(approvals as any);
+
+    await expect(
+      handler.handle(
+        interaction,
+        {
+          callbackToken: 'ext_cb_test',
+          eventId: 'event-1',
+          outcome: 'APPROVE',
+          operatorId: 'alice',
+        },
+        {},
+      ),
+    ).resolves.toEqual({ state: 'PENDING' });
+  });
+
+  it('resolves with the existing Human Approval signal contract', async () => {
+    const approvals = {
+      handleExternalInteractionDecision: jest
+        .fn()
+        .mockResolvedValue('APPROVED'),
+    };
+    const handler = new HumanApprovalHandler(approvals as any);
+
+    await expect(
+      handler.handle(
+        interaction,
+        {
+          callbackToken: 'ext_cb_test',
+          eventId: 'event-2',
+          outcome: 'APPROVE',
+          operatorId: 'bob',
+        },
+        {},
+      ),
+    ).resolves.toMatchObject({
+      state: 'RESOLVED',
+      outcome: 'APPROVED',
+      signal: {
+        name: 'humanApprovalResolved',
+        payload: {
+          requestId: '41',
+          nodeId: 'approval-1',
+          result: 'APPROVED',
+          reason: 'RULE_SATISFIED',
+        },
+      },
+    });
+  });
+});

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

@@ -0,0 +1,76 @@
+import { Injectable } from '@nestjs/common';
+import { HumanApprovalDomainError } from '../humanApproval/human-approval.errors';
+import { HumanApprovalService } from '../humanApproval/human-approval.service';
+import { ExternalInteractionHandler } from './external-interaction-handler';
+import {
+  ExternalHandlerResult,
+  ExternalInteractionRecord,
+  ExternalResultInput,
+} from './external-interaction.types';
+
+@Injectable()
+export class HumanApprovalHandler implements ExternalInteractionHandler {
+  readonly type = 'HUMAN_APPROVAL';
+
+  constructor(private readonly approvals: HumanApprovalService) {}
+
+  async handle(
+    interaction: ExternalInteractionRecord,
+    event: ExternalResultInput,
+    transaction: unknown,
+  ): Promise<ExternalHandlerResult> {
+    const approvalRequestId = requestId(interaction.handlerConfig);
+    try {
+      const status = await this.approvals.handleExternalInteractionDecision(
+        transaction,
+        approvalRequestId,
+        event,
+      );
+      if (status === 'PENDING') return { state: 'PENDING' };
+      const decidedAt = new Date().toISOString();
+      return {
+        state: 'RESOLVED',
+        outcome: status,
+        output: {
+          requestId: String(approvalRequestId),
+          result: status,
+          reason: 'RULE_SATISFIED',
+          decidedAt,
+        },
+        signal: {
+          name: 'humanApprovalResolved',
+          payload: {
+            requestId: String(approvalRequestId),
+            nodeId: interaction.nodeId,
+            result: status,
+            reason: 'RULE_SATISFIED',
+            decidedAt,
+          },
+        },
+      };
+    } catch (error) {
+      if (error instanceof HumanApprovalDomainError) {
+        const response = error.getResponse() as {
+          code?: string;
+          message?: string;
+        };
+        return {
+          state: 'REJECTED',
+          errorCode: response.code ?? 'APPROVAL_RESULT_REJECTED',
+          errorMessage: response.message ?? error.message,
+        };
+      }
+      throw error;
+    }
+  }
+}
+
+function requestId(config: unknown): bigint {
+  const value =
+    config && typeof config === 'object' && !Array.isArray(config)
+      ? (config as Record<string, unknown>).approvalRequestId
+      : undefined;
+  if (typeof value !== 'string' || !/^[1-9][0-9]*$/.test(value))
+    throw new Error('HUMAN_APPROVAL handler config is invalid');
+  return BigInt(value);
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/workflow-callback-url.controller.ts

@@ -0,0 +1,12 @@
+import { Controller, Get, Query } from '@nestjs/common';
+import { WorkflowCallbackUrlService } from './workflow-callback-url.service';
+
+@Controller('workflow-webhook')
+export class WorkflowCallbackUrlController {
+  constructor(private readonly callbackUrls: WorkflowCallbackUrlService) {}
+
+  @Get('endpoint')
+  resolveEndpoint(@Query('path') path = ''): { endpoint: string } {
+    return { endpoint: this.callbackUrls.resolvePath(path) };
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/workflow-callback-url.service.spec.ts

@@ -0,0 +1,227 @@
+import * as os from 'node:os';
+import { WorkflowCallbackUrlService } from './workflow-callback-url.service';
+
+describe('WorkflowCallbackUrlService', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('resolves the only published external request trigger', async () => {
+    const prisma = {
+      workflow: {
+        findUnique: jest.fn().mockResolvedValue({
+          status: 'PUBLISHED',
+          isEnabled: true,
+          versions: [
+            {
+              dsl: {
+                nodes: [
+                  {
+                    type: 'webhook_trigger',
+                    config: { path: 'provider-callback' },
+                  },
+                ],
+              },
+            },
+          ],
+        }),
+      },
+    };
+    const service = new WorkflowCallbackUrlService(
+      prisma as any,
+      {
+        get: jest.fn().mockReturnValue('https://gadmin.example.com/'),
+      } as any,
+    );
+
+    await expect(service.resolve('44')).resolves.toBe(
+      'https://gadmin.example.com/api/workflow/webhook/provider-callback',
+    );
+  });
+
+  it('rejects a callback Workflow with multiple external request triggers', async () => {
+    const service = new WorkflowCallbackUrlService(
+      {
+        workflow: {
+          findUnique: jest.fn().mockResolvedValue({
+            status: 'PUBLISHED',
+            isEnabled: true,
+            versions: [
+              {
+                dsl: {
+                  nodes: [
+                    { type: 'webhook_trigger', config: { path: 'one' } },
+                    { type: 'webhook_trigger', config: { path: 'two' } },
+                  ],
+                },
+              },
+            ],
+          }),
+        },
+      } as any,
+      { get: jest.fn().mockReturnValue('https://gadmin.example.com') } as any,
+    );
+
+    await expect(service.resolve('44')).rejects.toMatchObject({
+      response: {
+        code: 'CALLBACK_WORKFLOW_TRIGGER_INVALID',
+      },
+    });
+  });
+
+  it('uses the PM2-assigned server port and a reachable IPv4 address when no public base URL is configured', async () => {
+    jest.spyOn(os, 'networkInterfaces').mockReturnValue({
+      lo: [
+        {
+          address: '127.0.0.1',
+          netmask: '255.0.0.0',
+          family: 'IPv4',
+          mac: '00:00:00:00:00:00',
+          internal: true,
+          cidr: '127.0.0.1/8',
+        },
+      ],
+      eth0: [
+        {
+          address: '10.20.30.40',
+          netmask: '255.255.255.0',
+          family: 'IPv4',
+          mac: '00:11:22:33:44:55',
+          internal: false,
+          cidr: '10.20.30.40/24',
+        },
+      ],
+    });
+    const service = new WorkflowCallbackUrlService(
+      {
+        workflow: {
+          findUnique: jest.fn().mockResolvedValue({
+            status: 'PUBLISHED',
+            isEnabled: true,
+            versions: [
+              {
+                dsl: {
+                  nodes: [
+                    {
+                      type: 'webhook_trigger',
+                      config: { path: 'myoa-callback' },
+                    },
+                  ],
+                },
+              },
+            ],
+          }),
+        },
+      } as any,
+      {
+        get: jest.fn((key: string) => {
+          if (key === 'workflow.publicBaseUrl') return '';
+          if (key === 'workflow.publicHost') return '';
+          if (key === 'nest.port') return 14003;
+          return undefined;
+        }),
+      } as any,
+    );
+
+    await expect(service.resolve('44')).resolves.toBe(
+      'http://10.20.30.40:14003/api/workflow/webhook/myoa-callback',
+    );
+  });
+
+  it('lets deployments override the automatically detected host', async () => {
+    jest.spyOn(os, 'networkInterfaces').mockReturnValue({});
+    const service = new WorkflowCallbackUrlService(
+      {
+        workflow: {
+          findUnique: jest.fn().mockResolvedValue({
+            status: 'PUBLISHED',
+            isEnabled: true,
+            versions: [
+              {
+                dsl: {
+                  nodes: [
+                    {
+                      type: 'webhook_trigger',
+                      config: { path: 'myoa-callback' },
+                    },
+                  ],
+                },
+              },
+            ],
+          }),
+        },
+      } as any,
+      {
+        get: jest.fn((key: string) => {
+          if (key === 'workflow.publicBaseUrl') return '';
+          if (key === 'workflow.publicHost') return '10.50.60.70';
+          if (key === 'nest.port') return 14009;
+          return undefined;
+        }),
+      } as any,
+    );
+
+    await expect(service.resolve('44')).resolves.toBe(
+      'http://10.50.60.70:14009/api/workflow/webhook/myoa-callback',
+    );
+  });
+
+  it('does not expose a Docker bridge address as the callback host', async () => {
+    jest.spyOn(os, 'networkInterfaces').mockReturnValue({
+      docker0: [
+        {
+          address: '172.17.0.1',
+          netmask: '255.255.0.0',
+          family: 'IPv4',
+          mac: '00:00:00:00:00:01',
+          internal: false,
+          cidr: '172.17.0.1/16',
+        },
+      ],
+      eth0: [
+        {
+          address: '11.22.33.44',
+          netmask: '255.255.255.0',
+          family: 'IPv4',
+          mac: '00:11:22:33:44:55',
+          internal: false,
+          cidr: '11.22.33.44/24',
+        },
+      ],
+    });
+    const service = new WorkflowCallbackUrlService(
+      {
+        workflow: {
+          findUnique: jest.fn().mockResolvedValue({
+            status: 'PUBLISHED',
+            isEnabled: true,
+            versions: [
+              {
+                dsl: {
+                  nodes: [
+                    {
+                      type: 'webhook_trigger',
+                      config: { path: 'myoa-callback' },
+                    },
+                  ],
+                },
+              },
+            ],
+          }),
+        },
+      } as any,
+      {
+        get: jest.fn((key: string) => {
+          if (key === 'workflow.publicBaseUrl') return '';
+          if (key === 'workflow.publicHost') return '';
+          if (key === 'nest.port') return 14003;
+          return undefined;
+        }),
+      } as any,
+    );
+
+    await expect(service.resolve('44')).resolves.toBe(
+      'http://11.22.33.44:14003/api/workflow/webhook/myoa-callback',
+    );
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/externalInteraction/workflow-callback-url.service.ts

@@ -0,0 +1,121 @@
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { PrismaService } from 'nestjs-prisma';
+import { networkInterfaces } from 'node:os';
+
+@Injectable()
+export class WorkflowCallbackUrlService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly config: ConfigService,
+  ) {}
+
+  async resolve(workflowId: string): Promise<string> {
+    if (!/^[1-9][0-9]*$/.test(workflowId)) {
+      throw new BadRequestException({
+        code: 'CALLBACK_WORKFLOW_INVALID',
+        message: '回调 Workflow 无效',
+      });
+    }
+    const workflow = await this.prisma.workflow.findUnique({
+      where: { id: BigInt(workflowId) },
+      select: {
+        status: true,
+        isEnabled: true,
+        versions: {
+          orderBy: { version: 'desc' },
+          take: 1,
+          select: { dsl: true },
+        },
+      },
+    });
+    if (!workflow) throw new NotFoundException('回调 Workflow 不存在');
+    if (workflow.status !== 'PUBLISHED' || !workflow.isEnabled) {
+      throw new BadRequestException({
+        code: 'CALLBACK_WORKFLOW_NOT_AVAILABLE',
+        message: '回调 Workflow 必须已发布并启用',
+      });
+    }
+    const nodes = asNodes(workflow.versions[0]?.dsl);
+    const triggers = nodes.filter((node) => node.type === 'webhook_trigger');
+    if (triggers.length !== 1) {
+      throw new BadRequestException({
+        code: 'CALLBACK_WORKFLOW_TRIGGER_INVALID',
+        message: '回调 Workflow 必须有且只有一个“接收外部请求”节点',
+      });
+    }
+    const path = triggers[0]?.config?.path;
+    if (typeof path !== 'string' || !path.trim()) {
+      throw new BadRequestException({
+        code: 'CALLBACK_WORKFLOW_TRIGGER_INVALID',
+        message: '回调 Workflow 的外部请求地址无效',
+      });
+    }
+    return this.resolvePath(path);
+  }
+
+  resolvePath(path: string): string {
+    const normalizedPath = path.trim();
+    if (!normalizedPath) {
+      throw new BadRequestException({
+        code: 'CALLBACK_WORKFLOW_TRIGGER_INVALID',
+        message: '回调 Workflow 的外部请求地址无效',
+      });
+    }
+    return `${this.resolvePublicBaseUrl()}/api/workflow/webhook/${encodeURIComponent(
+      normalizedPath,
+    )}`;
+  }
+
+  private resolvePublicBaseUrl(): string {
+    const configuredBaseUrl = this.config
+      .get<string>('workflow.publicBaseUrl')
+      ?.trim();
+    if (configuredBaseUrl) return configuredBaseUrl.replace(/\/+$/, '');
+
+    const configuredHost = this.config
+      .get<string>('workflow.publicHost')
+      ?.trim();
+    const host = configuredHost || findReachableIpv4();
+    if (!host) {
+      throw new BadRequestException({
+        code: 'WORKFLOW_PUBLIC_HOST_UNRESOLVED',
+        message:
+          '无法自动识别 Workflow 回调 IP，请配置 WORKFLOW_PUBLIC_HOST 或 WORKFLOW_PUBLIC_BASE_URL',
+      });
+    }
+
+    const port = Number(this.config.get<number>('nest.port'));
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new BadRequestException({
+        code: 'WORKFLOW_PUBLIC_PORT_INVALID',
+        message: 'Workflow 回调端口无效',
+      });
+    }
+    return `http://${host}:${port}`;
+  }
+}
+
+function findReachableIpv4(): string | undefined {
+  for (const [name, addresses] of Object.entries(networkInterfaces())) {
+    if (/^(?:lo|docker|br-|veth|virbr|utun|tun|tap)/i.test(name)) continue;
+    for (const address of addresses ?? []) {
+      const isIpv4 = address.family === 'IPv4';
+      if (isIpv4 && !address.internal) return address.address;
+    }
+  }
+  return undefined;
+}
+
+function asNodes(value: unknown): Array<{
+  type?: string;
+  config?: Record<string, unknown>;
+}> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+  const nodes = (value as { nodes?: unknown }).nodes;
+  return Array.isArray(nodes) ? nodes : [];
+}