@gadmin2n/schematics 0.0.144 → 0.0.145

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/workflow/dsl-validate.util.spec.ts

@@ -1,4 +1,17 @@
-import { validateDslGraph } from './dsl-validate.util';
+import { validateDslGraph as validateDslGraphRaw } from './dsl-validate.util';
+
+function validateDslGraph(dsl: any) {
+  if (!dsl || typeof dsl !== 'object') return validateDslGraphRaw(dsl);
+  return validateDslGraphRaw({
+    ...dsl,
+    edges: Array.isArray(dsl?.edges)
+      ? dsl.edges.map((edge: any, index: number) => ({
+          id: `edge-${index}`,
+          ...edge,
+        }))
+      : dsl?.edges,
+  });
+}
 
 describe('validateDslGraph', () => {
   const validDsl = {
@@ -18,20 +31,19 @@ describe('validateDslGraph', () => {
       expect(() => validateDslGraph(validDsl)).not.toThrow();
     });
 
-    it('accepts a diamond DAG', () => {
+    it('accepts distinct conditional branches', () => {
       expect(() =>
         validateDslGraph({
           nodes: [
             { id: 't1', type: 'manual_trigger' },
-            { id: 'a', type: 'http_request' },
+            { id: 'a', type: 'if_else' },
             { id: 'b', type: 'http_request' },
             { id: 'c', type: 'code' },
           ],
           edges: [
             { source: 't1', target: 'a' },
-            { source: 't1', target: 'b' },
-            { source: 'a', target: 'c' },
-            { source: 'b', target: 'c' },
+            { source: 'a', target: 'b', sourceHandle: 'true' },
+            { source: 'a', target: 'c', sourceHandle: 'false' },
           ],
         }),
       ).not.toThrow();
@@ -106,11 +118,199 @@ describe('validateDslGraph', () => {
           nodes: [{ id: 'n1', type: 'http_request' }],
           edges: [],
         }),
-      ).toThrow('at least one *_trigger node');
+      ).toThrow('exactly one *_trigger node');
+    });
+
+    it('rejects more than one trigger node', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'manual', type: 'manual_trigger' },
+            { id: 'event', type: 'event_trigger' },
+          ],
+          edges: [],
+        }),
+      ).toThrow('exactly one *_trigger node');
+    });
+  });
+
+  describe('main-flow semantics', () => {
+    it('rejects joins because input has no unambiguous predecessor', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'branch', type: 'if_else' },
+            { id: 'left', type: 'code' },
+            { id: 'right', type: 'code' },
+            { id: 'join', type: 'code' },
+          ],
+          edges: [
+            { source: 'trigger', target: 'branch' },
+            { source: 'branch', target: 'left', sourceHandle: 'true' },
+            { source: 'branch', target: 'right', sourceHandle: 'false' },
+            { source: 'left', target: 'join' },
+            { source: 'right', target: 'join' },
+          ],
+        }),
+      ).toThrow('main-flow joins are not supported');
+    });
+
+    it('rejects multiple outgoing edges from an ordinary node', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'left', type: 'code' },
+            { id: 'right', type: 'code' },
+          ],
+          edges: [
+            { source: 'trigger', target: 'left' },
+            { source: 'trigger', target: 'right' },
+          ],
+        }),
+      ).toThrow('at most one outgoing FLOW edge');
+    });
+
+    it('rejects duplicate connections from one conditional output', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'branch', type: 'if_else' },
+            { id: 'left', type: 'code' },
+            { id: 'right', type: 'code' },
+          ],
+          edges: [
+            { source: 'trigger', target: 'branch' },
+            { source: 'branch', target: 'left', sourceHandle: 'true' },
+            { source: 'branch', target: 'right', sourceHandle: 'true' },
+          ],
+        }),
+      ).toThrow('each output to at most one next node');
+    });
+
+    it('accepts Parallel START / END pipelines and one main OUT', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'parallel', type: 'parallel' },
+            { id: 'left', type: 'code' },
+            { id: 'right', type: 'code' },
+            { id: 'after', type: 'code' },
+          ],
+          edges: [
+            { source: 'trigger', target: 'parallel' },
+            { source: 'parallel', target: 'after' },
+            {
+              source: 'parallel',
+              target: 'left',
+              kind: 'CALL',
+              pairId: 'left-pair',
+              sourceHandle: 'left-start',
+            },
+            {
+              source: 'left',
+              target: 'parallel',
+              kind: 'RETURN',
+              pairId: 'left-pair',
+              targetHandle: 'left-end',
+            },
+            {
+              source: 'parallel',
+              target: 'right',
+              kind: 'CALL',
+              pairId: 'right-pair',
+              sourceHandle: 'right-start',
+            },
+            {
+              source: 'right',
+              target: 'parallel',
+              kind: 'RETURN',
+              pairId: 'right-pair',
+              targetHandle: 'right-end',
+            },
+          ],
+        }),
+      ).not.toThrow();
+    });
+
+    it('rejects nodes disconnected from the trigger', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'orphan', type: 'code' },
+          ],
+          edges: [],
+        }),
+      ).toThrow('not connected to its trigger');
     });
   });
 
   describe('edge errors', () => {
+    it('rejects an edge without id', () => {
+      expect(() =>
+        validateDslGraphRaw({
+          nodes: [{ id: 't1', type: 'manual_trigger' }],
+          edges: [{ source: 't1', target: 't1' }],
+        }),
+      ).toThrow('non-empty string id');
+    });
+
+    it('rejects duplicate edge ids', () => {
+      expect(() =>
+        validateDslGraphRaw({
+          nodes: [
+            { id: 't1', type: 'manual_trigger' },
+            { id: 'a', type: 'code' },
+          ],
+          edges: [
+            { id: 'same', source: 't1', target: 'a' },
+            { id: 'same', source: 't1', target: 'a' },
+          ],
+        }),
+      ).toThrow('Duplicate edge id');
+    });
+
+    it('rejects an orphan paired FLOW as unreachable runtime flow', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 't1', type: 'manual_trigger' },
+            { id: 'a', type: 'code' },
+          ],
+          edges: [
+            {
+              source: 't1',
+              target: 'a',
+              kind: 'FLOW',
+              pairId: 'ghost',
+            },
+          ],
+        }),
+      ).toThrow('not connected to its trigger');
+    });
+
+    it('rejects an edge with pairId and an omitted kind', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'code', type: 'code' },
+          ],
+          edges: [
+            {
+              source: 'trigger',
+              target: 'code',
+              pairId: 'ghost',
+            },
+          ],
+        }),
+      ).toThrow('must explicitly declare kind');
+    });
+
     it('rejects edge with unknown source', () => {
       expect(() =>
         validateDslGraph({
@@ -143,6 +343,42 @@ describe('validateDslGraph', () => {
         }),
       ).toThrow('Self-loop');
     });
+
+    it('rejects removed DATA edges', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'action', type: 'code' },
+          ],
+          edges: [
+            {
+              source: 'trigger',
+              target: 'action',
+              kind: 'DATA',
+            },
+          ],
+        }),
+      ).toThrow('DATA edges are no longer supported');
+    });
+
+    it('rejects unknown edge kinds', () => {
+      expect(() =>
+        validateDslGraph({
+          nodes: [
+            { id: 'trigger', type: 'manual_trigger' },
+            { id: 'action', type: 'code' },
+          ],
+          edges: [
+            {
+              source: 'trigger',
+              target: 'action',
+              kind: 'UNKNOWN',
+            },
+          ],
+        }),
+      ).toThrow('Unsupported edge kind: "UNKNOWN"');
+    });
   });
 
   describe('cycle detection', () => {
@@ -208,13 +444,23 @@ describe('validateDslGraph', () => {
       validateDslGraph({
         nodes: [
           { id: 'trigger', type: 'manual_trigger' },
-          { id: 'approval', type: 'human_approval' },
-          { id: 'lookup', type: 'http_request' },
+          { id: 'loop', type: 'for_each' },
+          { id: 'body', type: 'code' },
         ],
         edges: [
-          { source: 'trigger', target: 'approval', kind: 'FLOW' },
-          { source: 'approval', target: 'lookup', kind: 'CALL' },
-          { source: 'lookup', target: 'approval', kind: 'RETURN' },
+          { source: 'trigger', target: 'loop', kind: 'FLOW' },
+          {
+            source: 'loop',
+            target: 'body',
+            kind: 'CALL',
+            pairId: 'loop-body',
+          },
+          {
+            source: 'body',
+            target: 'loop',
+            kind: 'RETURN',
+            pairId: 'loop-body',
+          },
         ],
       }),
     ).not.toThrow();

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/workflow/dsl-validate.util.ts

@@ -10,8 +10,9 @@
  * 1. nodes / edges are present and well-typed
  * 2. every edge references existing nodes
  * 3. node ids are unique
- * 4. there is at least one trigger node
- * 5. graph is a DAG (Kahn's algorithm — no cycles)
+ * 4. there is exactly one trigger node and every node is reachable from it
+ * 5. main FLOW has unambiguous input/output cardinality
+ * 6. graph is a DAG (Kahn's algorithm — no cycles)
  *
  * Throws Error with a human-readable message on the first failure;
  * caller should map to BadRequestException.
@@ -19,9 +20,12 @@
 export interface DslGraphLike {
   nodes?: Array<{ id?: string; type?: string }>;
   edges?: Array<{
+    id?: string;
     source?: string;
     target?: string;
-    kind?: 'FLOW' | 'DATA' | 'CALL' | 'RETURN';
+    kind?: string;
+    pairId?: string;
+    sourceHandle?: string;
   }>;
 }
 
@@ -56,14 +60,23 @@ export function validateDslGraph(dsl: unknown): void {
     }
   }
 
-  // 2. at least one trigger node
-  const hasTrigger = g.nodes.some((n) => n.type!.endsWith('_trigger'));
-  if (!hasTrigger) {
-    throw new Error('DSL must contain at least one *_trigger node');
-  }
+  // 2. exactly one trigger node. The worker starts every trigger successor,
+  // so accepting multiple triggers would execute unrelated entry paths in the
+  // same run regardless of which trigger actually started it.
+  const triggerNodes = g.nodes.filter((n) => n.type!.endsWith('_trigger'));
+  if (triggerNodes.length !== 1)
+    throw new Error('DSL must contain exactly one *_trigger node');
 
-  // 3. edges reference existing nodes; no self-loops
+  // 3. edge ids unique + non-empty; edges reference existing nodes; no self-loops
+  const edgeIdSet = new Set<string>();
   for (const e of g.edges) {
+    if (!e || typeof e.id !== 'string' || e.id.length === 0) {
+      throw new Error('Every edge must have a non-empty string id');
+    }
+    if (edgeIdSet.has(e.id)) {
+      throw new Error(`Duplicate edge id: "${e.id}"`);
+    }
+    edgeIdSet.add(e.id);
     if (!e || typeof e.source !== 'string' || typeof e.target !== 'string') {
       throw new Error('Every edge must have string source and target');
     }
@@ -76,19 +89,119 @@ export function validateDslGraph(dsl: unknown): void {
     if (e.source === e.target) {
       throw new Error(`Self-loop detected on node "${e.source}"`);
     }
+    if (e.kind === 'DATA')
+      throw new Error(
+        'DATA edges are no longer supported; use structured bindings or a CALL / RETURN pipeline',
+      );
+    if (e.pairId && e.kind === undefined)
+      throw new Error(
+        `Edge "${e.id}" with pairId must explicitly declare kind FLOW, CALL, or RETURN`,
+      );
+    if (e.kind !== undefined && !['FLOW', 'CALL', 'RETURN'].includes(e.kind))
+      throw new Error(`Unsupported edge kind: "${e.kind}"`);
+  }
+
+  const nodeById = new Map(g.nodes.map((node) => [node.id!, node]));
+  const edges = g.edges;
+  const mainEdges = edges.filter(
+    (edge) => (!edge.kind || edge.kind === 'FLOW') && !edge.pairId,
+  );
+
+  validateAcyclicMainFlow(idSet, edges);
+
+  // 4. main-flow topology. A node receives one well-defined `input`: the
+  // immediately preceding node's output. There is no merge node today, so a
+  // main-flow join would either deadlock on an unselected branch or leave the
+  // runtime unable to choose which predecessor is `input`.
+  for (const node of g.nodes) {
+    const incoming = mainEdges.filter((edge) => edge.target === node.id);
+    const outgoing = mainEdges.filter((edge) => edge.source === node.id);
+
+    if (node.type!.endsWith('_trigger') && incoming.length > 0)
+      throw new Error(`Trigger node "${node.id}" cannot have an incoming FLOW`);
+    if (incoming.length > 1)
+      throw new Error(
+        `Node "${node.id}" has multiple incoming FLOW edges; main-flow joins are not supported`,
+      );
+    const isBranchNode = [
+      'if_else',
+      'switch',
+      'approval',
+      'external_wait',
+    ].includes(node.type!);
+    if (!isBranchNode && outgoing.length > 1)
+      throw new Error(
+        `Node "${node.id}" can have at most one outgoing FLOW edge`,
+      );
+
+    const branchesByHandle = new Map<string, number>();
+    for (const edge of outgoing) {
+      const handle = edge.sourceHandle ?? '';
+      branchesByHandle.set(handle, (branchesByHandle.get(handle) ?? 0) + 1);
+    }
+    if ([...branchesByHandle.values()].some((count) => count > 1))
+      throw new Error(
+        `Node "${node.id}" can connect each output to at most one next node`,
+      );
   }
 
-  // 4. cycle detection — Kahn's algorithm.
-  // 注意：parallel/for_each 节点的"分支"在 worker 侧也是普通的 edge，因此用普通 DAG 校验即可。
+  // Every node must belong to the single entry graph. CALL edges make inline
+  // loop bodies reachable. A paired FLOW is only traversable when its pair is
+  // owned by exactly one CALL; otherwise it is not executable main flow.
+  const callablePairIds = new Set(
+    edges
+      .filter(
+        (edge) =>
+          edge.kind === 'CALL' &&
+          edge.pairId &&
+          edges.filter(
+            (candidate) =>
+              candidate.kind === 'CALL' && candidate.pairId === edge.pairId,
+          ).length === 1,
+      )
+      .map((edge) => edge.pairId)
+      .filter((pairId): pairId is string => Boolean(pairId)),
+  );
+  const reachable = new Set<string>([triggerNodes[0].id!]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of edges) {
+      if (
+        edge.kind === 'RETURN' ||
+        (edge.kind === 'FLOW' &&
+          Boolean(edge.pairId) &&
+          !callablePairIds.has(edge.pairId ?? '')) ||
+        !reachable.has(edge.source!) ||
+        reachable.has(edge.target!)
+      )
+        continue;
+      reachable.add(edge.target!);
+      changed = true;
+    }
+  }
+  const unreachable = [...nodeById.keys()].filter((id) => !reachable.has(id));
+  if (unreachable.length > 0)
+    throw new Error(
+      `DSL contains nodes that are not connected to its trigger: [${unreachable.join(
+        ', ',
+      )}]`,
+    );
+}
+
+function validateAcyclicMainFlow(
+  idSet: Set<string>,
+  edges: NonNullable<DslGraphLike['edges']>,
+): void {
+  // Paired For Each / lookup FLOW chains must also be acyclic. CALL and RETURN
+  // edges describe invocation boundaries rather than normal execution order.
   const indegree = new Map<string, number>();
   const adj = new Map<string, string[]>();
   for (const id of idSet) {
     indegree.set(id, 0);
     adj.set(id, []);
   }
-  for (const e of g.edges.filter(
-    (edge) => !edge.kind || edge.kind === 'FLOW',
-  )) {
+  for (const e of edges.filter((edge) => !edge.kind || edge.kind === 'FLOW')) {
     indegree.set(e.target!, indegree.get(e.target!)! + 1);
     adj.get(e.source!)!.push(e.target!);
   }

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/workflow/manual-workflow-execution.spec.ts

@@ -0,0 +1,85 @@
+import { BadRequestException } from '@nestjs/common';
+import {
+  assertManualWorkflowExecution,
+  normalizeIdempotencyKey,
+  scopedIdempotencyKey,
+  workflowDataHash,
+} from './manual-workflow-execution';
+
+describe('manual Workflow execution', () => {
+  it('accepts a valid manual trigger input', () => {
+    expect(() =>
+      assertManualWorkflowExecution(
+        {
+          nodes: [
+            {
+              type: 'manual_trigger',
+              config: {
+                inputSchema: {
+                  type: 'object',
+                  required: ['orderId'],
+                  properties: { orderId: { type: 'string' } },
+                },
+              },
+            },
+          ],
+        },
+        { orderId: 'O-1' },
+      ),
+    ).not.toThrow();
+  });
+
+  it('rejects a non-manual trigger and invalid input', () => {
+    expect(() =>
+      assertManualWorkflowExecution(
+        { nodes: [{ type: 'webhook_trigger', config: {} }] },
+        {},
+      ),
+    ).toThrow(BadRequestException);
+
+    expect(() =>
+      assertManualWorkflowExecution(
+        {
+          nodes: [
+            {
+              type: 'manual_trigger',
+              config: {
+                inputSchema: {
+                  type: 'object',
+                  required: ['orderId'],
+                },
+              },
+            },
+          ],
+        },
+        {},
+      ),
+    ).toThrow(BadRequestException);
+  });
+
+  it('normalizes, scopes, and compares idempotent requests', () => {
+    expect(normalizeIdempotencyKey(' request-1 ')).toBe('request-1');
+    expect(scopedIdempotencyKey('manual', 'request-1')).toMatch(
+      /^manual:[a-f0-9]{64}$/,
+    );
+    expect(
+      workflowDataHash(
+        {
+          orderId: 'O-1',
+          receivedAt: 'first',
+          headers: { 'x-workflow-timestamp': 'first' },
+        },
+        ['receivedAt', 'headers.x-workflow-timestamp'],
+      ),
+    ).toBe(
+      workflowDataHash(
+        {
+          receivedAt: 'retry',
+          orderId: 'O-1',
+          headers: { 'x-workflow-timestamp': 'retry' },
+        },
+        ['receivedAt', 'headers.x-workflow-timestamp'],
+      ),
+    );
+  });
+});

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/workflow/manual-workflow-execution.ts

@@ -0,0 +1,108 @@
+import { BadRequestException } from '@nestjs/common';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { createHash } from 'crypto';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+export function assertManualWorkflowExecution(
+  dsl: unknown,
+  workflowData: Record<string, unknown>,
+): void {
+  const nodes = Array.isArray((dsl as any)?.nodes) ? (dsl as any).nodes : [];
+  const triggers = nodes.filter(
+    (node: any) =>
+      typeof node?.type === 'string' && node.type.endsWith('_trigger'),
+  );
+  const manualTriggers = triggers.filter(
+    (node: any) => node.type === 'manual_trigger',
+  );
+
+  if (triggers.length !== 1 || manualTriggers.length !== 1) {
+    throw new BadRequestException({
+      code: 'WORKFLOW_ACTION_REQUIRES_MANUAL_TRIGGER',
+      message: '只有“手动触发”的 Workflow 可以绑定到页面按钮',
+    });
+  }
+
+  const inputSchema = manualTriggers[0]?.config?.inputSchema;
+  if (!inputSchema || typeof inputSchema !== 'object') return;
+
+  let validate;
+  try {
+    validate = ajv.compile(inputSchema);
+  } catch {
+    throw new BadRequestException({
+      code: 'WORKFLOW_INPUT_SCHEMA_INVALID',
+      message: 'Workflow 的启动数据规则无效，请重新发布后再试',
+    });
+  }
+  if (validate(workflowData)) return;
+
+  throw new BadRequestException({
+    code: 'WORKFLOW_INPUT_INVALID',
+    message: '启动数据不符合 Workflow 的要求',
+    details: (validate.errors ?? []).map((error) => ({
+      path: error.instancePath || '/',
+      message: error.message,
+    })),
+  });
+}
+
+export function normalizeIdempotencyKey(value: string | undefined): string {
+  const key = value?.trim() ?? '';
+  if (!key || key.length > 128 || /[\u0000-\u001f\u007f]/.test(key)) {
+    throw new BadRequestException({
+      code: 'IDEMPOTENCY_KEY_INVALID',
+      message: 'Idempotency-Key 必须是 1 到 128 个字符',
+    });
+  }
+  return key;
+}
+
+export function workflowDataHash(
+  workflowData: Record<string, unknown>,
+  ignoredFields: string[] = [],
+): string {
+  return createHash('sha256')
+    .update(stableJson(omitPaths(workflowData, ignoredFields)))
+    .digest('hex');
+}
+
+export function scopedIdempotencyKey(scope: string, value: string): string {
+  return `${scope}:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function omitPaths(value: unknown, paths: string[]): unknown {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => !paths.includes(key))
+      .map(([key, child]) => [
+        key,
+        omitPaths(
+          child,
+          paths
+            .filter((path) => path.startsWith(`${key}.`))
+            .map((path) => path.slice(key.length + 1)),
+        ),
+      ]),
+  );
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${stableJson(
+            (value as Record<string, unknown>)[key],
+          )}`,
+      )
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}