Workflow

Custom workflow node (IWorkflowNode) တည်ဆောက်ရပါသည်၊ module တွင် မှတ်ပုံတင်ရပါသည်၊ service မှ trigger လုပ်ရပါသည်၊ controller API များကို @WorkflowEntry ဖြင့် discoverable step အဖြစ် ဖော်ပြရပါသည်။

ခြုံငုံသုံးသပ်ချက်

Workflow engine သည် node graph များကို run လုပ်ပါသည်။ Plugin များက node ပေးနိုင်ပြီး domain event တွင် workflow စတင်နိုင်ပါသည်။ Type များကို @quan-erp/shared-backend-core မှ import လုပ်ရပါသည်။

Custom node — IWorkflowNode implement; @Module({ workflowNodes }) တွင် မှတ်ပုံတင်ရပါသည်
Trigger — isTriggerable: true + WorkflowService.findByInitId / executeWorkflow
API entry — controller method ပေါ်တွင် @WorkflowEntry
Frontend — @quan-erp/base-frontend မှ workflowNodes() ဖြင့် UI node မှတ်ပုံတင်ရပါသည်

Node data model

Props — workflow editor UI မှ configuration
Args — run အချိန်တွင် inject လုပ်သော တန်ဖိုးများ
ReturnType — နောက် node များသို့ ပေးသော ထွက်ရှိချက်
type — plugin node အတွက် အမြဲ `${metadata.name}/${NODE_ID}`

Props & return schemas

PropsType ဖြင့် JSON schema ကြေညာပြီး SchemaToType ဖြင့် TypeScript type ရယူရပါသည်။ Schema သည် process() typing နှင့် frontend editor နှစ်ခုလုံးအတွက် အသုံးပြုပါသည်။

TSXschemas

import {
  PropsType,
  SchemaToType,
} from "@quan-erp/shared-backend-core";

const inputSchema = {
  type: "number",
} as const satisfies PropsType;
type Props = SchemaToType<typeof inputSchema>;

const returnSchema = {
  type: "object",
  properties: {
    bookingId: { type: "number" },
    bookingSource: { type: "string" },
  },
} as const satisfies PropsType;
type ReturnType = SchemaToType<typeof returnSchema>;

export type Args = {
  bookingId: number;
  bookingSource: string;
};

Execution lifecycle

01
process()
Executor က process(context, uid, props, args) ခေါ်ပါသည်။ NodeResult.single(...) ပြန်ပေးရပါသည်။
02
nextToExecute()
process ပြီးနောက် နောက် node id များကို မေးပါသည်။ null = UI next edges; string[] = routing override။
03
Routing
null → canvas next array။ string[] → ထို node id များကို run လုပ်ပါသည်။

ExecutionContext

Run တိုင်းတွင် node အားလုံး မျှဝေသော ExecutionContext ရရှိပါသည်။ UI-mapped props ကို မသုံးမီ resolve လုပ်ရပါသည်။

context.pipeData.resolve(props) — ${{node_….output}} များကို ဖြေရှင်းပါသည်; props မဖတ်မီ အမြဲ resolve လုပ်ရပါသည်
context.execute(nodeId, args) — အခြား node ကို ချက်ချင်း run / await (NodeResultType = T[])
toolResult[0] — sub-execution ၏ raw payload
context.findWorkflowNodeById(uid) — custom nextToExecute အတွက် edges စစ်ရန်

TSXresolve props

import type {
  ExecutionContext,
  NodeResultType,
  PromisableReturn,
} from "@quan-erp/shared-backend-core";
import { NodeResult } from "@quan-erp/shared-backend-core";

function process(
  context: ExecutionContext,
  uid: string,
  props: { expression: string },
  args: unknown,
): PromisableReturn<NodeResultType<boolean>> {
  const resolvedProps = context.pipeData.resolve(props);
  const evaluateResult = eval(resolvedProps.expression);
  return NodeResult.single(evaluateResult as boolean);
}

TSXsub-execute

import type { ExecutionContext } from "@quan-erp/shared-backend-core";

async function callTool(
  context: ExecutionContext,
  toolNodeId: string,
  toolArgs: Record<string, unknown>,
) {
  const toolResult = await context.execute(toolNodeId, toolArgs);
  return toolResult[0];
}

Custom routing (nextToExecute)

Conditional / loop အတွက် default edge walk ကို override လုပ်ရပါသည်။ Canvas edges ထားလိုလျှင် null ပြန်ပေးရပါသည်။ process မှ NodeResultType array ရရှိပါသည် (args[0] သုံးရပါသည်)။

TSXif-style routing

import type {
  ExecutionContext,
  NodeResultType,
  PromisableReturn,
} from "@quan-erp/shared-backend-core";

function nextToExecute(
  context: ExecutionContext,
  uid: string,
  args: NodeResultType<boolean>,
): PromisableReturn<string[]> | PromisableReturn<null> {
  const current = context.findWorkflowNodeById(uid);
  const ifTrue = current?.next?.[0];
  const ifFalse = current?.next?.[1];
  if (args[0] && ifTrue?.id) return [ifTrue.id];
  if (!args[0] && ifFalse?.id) return [ifFalse.id];
  return null;
}

Full trigger node

Trigger node များတွင် isTriggerable: true ထားရှိပြီး Args ကို return အဖြစ် များသောအားဖြင့် ဖြတ်ပေးပါသည်။

TSXOnBookingWorkflowNode

import {
  ExecutionContext,
  IWorkflowNode,
  NodeResult,
  NodeResultType,
  PromisableReturn,
  PropsType,
  SchemaToType,
  WorkflowNodeDefination,
} from "@quan-erp/shared-backend-core";
import metadata from "../../../module.metadata.json" with { type: "json" };

const inputSchema = {
  type: "number",
} as const satisfies PropsType;
type Props = SchemaToType<typeof inputSchema>;

const returnSchema = {
  type: "object",
  properties: {
    bookingId: { type: "number" },
    bookingSource: { type: "string" },
  },
} as const satisfies PropsType;
type ReturnType = SchemaToType<typeof returnSchema>;

export type Args = {
  bookingId: number;
  bookingSource: string;
};

export class OnBookingWorkflowNode
  implements IWorkflowNode<Props, ReturnType, Args>
{
  static NODE_ID = "bookings";

  process(
    context: ExecutionContext,
    id: string,
    props: Props,
    args: Args,
  ): PromisableReturn<NodeResultType<ReturnType>> {
    return NodeResult.single(args);
  }

  nextToExecute(
    context: ExecutionContext,
    uid: string,
    args: NodeResultType<ReturnType>,
  ): PromisableReturn<string[]> | PromisableReturn<null> {
    return null;
  }

  getDefination(): WorkflowNodeDefination {
    return {
      type: `${metadata.name}/${OnBookingWorkflowNode.NODE_ID}`,
      group: ["any"],
      displayName: "On Hotel Booked",
      description: "Triggers when a hotel is booked",
      props: inputSchema,
      isTriggerable: true,
      returnType: {
        type: "array",
        items: returnSchema,
      },
    };
  }
}

Module တွင် မှတ်ပုံတင်ခြင်း

workflowNodes တွင် node class ထည့်ရပါသည် — backend mount လုပ်ပြီး editor သို့ definition ပေးပါသည်။

TSXmodule

import { Module } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OnBookingWorkflowNode } from "./workflow/on-booking.workflow.js";

@Module({
  name: metadata.name,
  providers: [],
  controllers: [],
  entities: [],
  workflowNodes: [OnBookingWorkflowNode],
})
export class MyPluginModule {}

Programmatic trigger

isTriggerable node များအတွက် builtin WorkflowService ကို inject လုပ်ရပါသည်။ init id `${metadata.name}/${NODE_ID}` ဖြင့် active workflow ရှာပြီး Args နှင့် execute လုပ်ရပါသည်။

TSXexecuteWorkflow

import {
  ContainerRegistryManager,
  Controller,
  Inject,
  Post,
  ResponseDto,
  WorkflowService,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OnBookingWorkflowNode } from "../workflow/on-booking.workflow.js";

@Controller("/bookings")
export class BookingController {
  @Inject(WorkflowService, ContainerRegistryManager.BUILTIN_PLUGIN)
  workflowService: WorkflowService;

  @Post("/")
  async createBooking() {
    // … create booking …
    const workflows = await this.workflowService.findByInitId(
      `${metadata.name}/${OnBookingWorkflowNode.NODE_ID}`,
      { active: true },
    );

    await Promise.all(
      workflows.map((w) =>
        this.workflowService.executeWorkflow({
          workflow: w,
          args: {
            bookingId: 1,
            bookingSource: "web",
          },
        }),
      ),
    );

    return ResponseDto.okWithEmpty();
  }
}

@WorkflowEntry (HTTP step)

Controller method ကို workflow engine က discover / invoke လုပ်နိုင်အောင် mark လုပ်ရပါသည်။ name၊ description နှင့် response နှင့် ကိုက်သော returnType schema ပေးရပါသည်။

TSX@WorkflowEntry

import {
  Controller,
  Get,
  WorkflowEntry,
} from "@quan-erp/shared-backend-core";

@Controller("/branch")
export class BranchController {
  @Get("/")
  @WorkflowEntry({
    name: "get-branch",
    description: "get all branches",
    returnType: {
      type: "object",
      properties: {
        payload: {
          type: "array",
          items: {
            type: "object",
            properties: {
              id: { type: "number" },
              name: { type: "string" },
            },
          },
        },
      },
    },
  })
  async list() {
    /* … */
  }
}

Checklist

Schemas: props နှင့် returnType အတွက် PropsType + SchemaToType
IWorkflowNode ပေါ်တွင် process, nextToExecute, getDefination
type: `${metadata.name}/${NODE_ID}` — plugin prefix မပျောက်ရပါ
@Module({ workflowNodes }) တွင် မှတ်ပုံတင်ရပါသည်
Triggerable: domain event တွင် WorkflowService ဖြင့် fire လုပ်ရပါသည်
Editor props မသုံးမီ context.pipeData.resolve(props)
NodeResult.single(...) ဖြင့် ပြန်ပေးရပါသည်