chore(plugin-workflow): add comments (#3959)

packages/plugins/@nocobase/plugin-workflow-request/package.json

@@ -9,6 +9,9 @@
   "main": "./dist/server/index.js",
   "homepage": "https://docs.nocobase.com/handbook/workflow-request",
   "homepage.zh-CN": "https://docs-cn.nocobase.com/handbook/workflow-request",
+  "dependencies": {
+    "axios": "^0.26.1"
+  },
   "devDependencies": {
     "antd": "5.x",
     "react": "18.x",

packages/plugins/@nocobase/plugin-workflow/package.json

@@ -19,7 +19,6 @@
     "@formily/react": "2.x",
     "@types/ejs": "^3.1.1",
     "antd": "5.x",
-    "axios": "^0.26.1",
     "classnames": "^2.3.1",
     "cron-parser": "4.4.0",
     "dayjs": "^1.11.8",

packages/plugins/@nocobase/plugin-workflow/src/client/index.tsx

@@ -58,8 +58,20 @@ export default class PluginWorkflowClient extends Plugin {
   }
 
   async load() {
-    this.addRoutes();
+    this.app.router.add('admin.workflow.workflows.id', {
-    this.addComponents();
+      path: getWorkflowDetailPath(':id'),
+      element: <WorkflowPage />,
+    });
+
+    this.app.router.add('admin.workflow.executions.id', {
+      path: getWorkflowExecutionsPath(':id'),
+      element: <ExecutionPage />,
+    });
+
+    this.app.addComponents({
+      WorkflowPage,
+      ExecutionPage,
+    });
 
     this.app.pluginSettingsManager.add(NAMESPACE, {
       icon: 'PartitionOutlined',
@@ -82,24 +94,6 @@ export default class PluginWorkflowClient extends Plugin {
     this.registerInstruction('update', UpdateInstruction);
     this.registerInstruction('destroy', DestroyInstruction);
   }
-
-  addComponents() {
-    this.app.addComponents({
-      WorkflowPage,
-      ExecutionPage,
-    });
-  }
-
-  addRoutes() {
-    this.app.router.add('admin.workflow.workflows.id', {
-      path: getWorkflowDetailPath(':id'),
-      element: <WorkflowPage />,
-    });
-    this.app.router.add('admin.workflow.executions.id', {
-      path: getWorkflowExecutionsPath(':id'),
-      element: <ExecutionPage />,
-    });
-  }
 }
 
 export * from './Branch';

packages/plugins/@nocobase/plugin-workflow/src/client/nodes/index.tsx

@@ -90,6 +90,9 @@ export function useNodeContext() {
   return useContext(NodeContext);
 }
 
+/**
+ * @experimental
+ */
 export function useAvailableUpstreams(node, filter?) {
   const stack: any[] = [];
   if (!node) {
@@ -104,6 +107,9 @@ export function useAvailableUpstreams(node, filter?) {
   return stack;
 }
 
+/**
+ * @experimental
+ */
 export function useUpstreamScopes(node) {
   const stack: any[] = [];
   if (!node) {

packages/plugins/@nocobase/plugin-workflow/src/client/triggers/index.tsx

@@ -330,6 +330,9 @@ export const TriggerConfig = () => {
   );
 };
 
+/**
+ * @experimental
+ */
 export function useTrigger() {
   const workflowPlugin = usePlugin(WorkflowPlugin);
   const { workflow } = useFlowContext();

packages/plugins/@nocobase/plugin-workflow/src/server/Plugin.ts

@@ -260,7 +260,7 @@ export default class PluginWorkflowServer extends Plugin {
     });
   }
 
-  toggle(workflow: WorkflowModel, enable?: boolean) {
+  private toggle(workflow: WorkflowModel, enable?: boolean) {
     const type = workflow.get('type');
     const trigger = this.triggers.get(type);
     if (!trigger) {
@@ -511,6 +511,13 @@ export default class PluginWorkflowServer extends Plugin {
     return processor;
   }
 
+  /**
+   * @experimental
+   * @param {string} dataSourceName
+   * @param {Transaction} transaction
+   * @param {boolean} create
+   * @returns {Trasaction}
+   */
   useDataSourceTransaction(dataSourceName = 'main', transaction, create = false) {
     // @ts-ignore
     const { db } = this.app.dataSourceManager.dataSources.get(dataSourceName).collectionManager;

packages/plugins/@nocobase/plugin-workflow/src/server/Processor.ts

@@ -25,11 +25,35 @@ export default class Processor {
   };
 
   logger: Logger;
+
+  /**
+   * @experimental
+   */
   transaction: Transaction;
+
+  /**
+   * @experimental
+   */
   nodes: FlowNodeModel[] = [];
+
+  /**
+   * @experimental
+   */
   nodesMap = new Map<number, FlowNodeModel>();
+
+  /**
+   * @experimental
+   */
   jobsMap = new Map<number, JobModel>();
+
+  /**
+   * @experimental
+   */
   jobsMapByNodeKey: { [key: string]: any } = {};
+
+  /**
+   * @experimental
+   */
   lastSavedJob: JobModel | null = null;
 
   constructor(
@@ -194,7 +218,7 @@ export default class Processor {
     return this.exit(job.status);
   }
 
-  async recall(node, job) {
+  private async recall(node, job) {
     const { instructions } = this.options.plugin;
     const instruction = instructions.get(node.type);
     if (typeof instruction.resume !== 'function') {
@@ -206,7 +230,7 @@ export default class Processor {
     return this.exec(instruction.resume.bind(instruction), node, job);
   }
 
-  async exit(s?: number) {
+  public async exit(s?: number) {
     if (typeof s === 'number') {
       const status = (<typeof Processor>this.constructor).StatusMap[s] ?? Math.sign(s);
       await this.execution.update({ status }, { transaction: this.transaction });
@@ -216,6 +240,11 @@ export default class Processor {
   }
 
   // TODO(optimize)
+  /**
+   * @experimental
+   * @param {JobModel | Record<string, any>} payload
+   * @returns {JobModel}
+   */
   async saveJob(payload) {
     const { database } = <typeof ExecutionModel>this.execution.constructor;
     const { transaction } = this;
@@ -243,13 +272,19 @@ export default class Processor {
     return job;
   }
 
+  /**
+   * @experimental
+   */
   getBranches(node: FlowNodeModel): FlowNodeModel[] {
     return this.nodes
       .filter((item) => item.upstream === node && item.branchIndex !== null)
       .sort((a, b) => Number(a.branchIndex) - Number(b.branchIndex));
   }
 
-  // find the first node in current branch
+  /**
+   * @experimental
+   * find the first node in current branch
+   */
   findBranchStartNode(node: FlowNodeModel, parent?: FlowNodeModel): FlowNodeModel | null {
     for (let n = node; n; n = n.upstream) {
       if (!parent) {
@@ -265,7 +300,10 @@ export default class Processor {
     return null;
   }
 
-  // find the node start current branch
+  /**
+   * @experimental
+   * find the node start current branch
+   */
   findBranchParentNode(node: FlowNodeModel): FlowNodeModel | null {
     for (let n = node; n; n = n.upstream) {
       if (n.branchIndex !== null) {
@@ -275,6 +313,9 @@ export default class Processor {
     return null;
   }
 
+  /**
+   * @experimental
+   */
   findBranchEndNode(node: FlowNodeModel): FlowNodeModel | null {
     for (let n = node; n; n = n.downstream) {
       if (!n.downstream) {
@@ -284,6 +325,9 @@ export default class Processor {
     return null;
   }
 
+  /**
+   * @experimental
+   */
   findBranchParentJob(job: JobModel, node: FlowNodeModel): JobModel | null {
     for (let j: JobModel | undefined = job; j; j = this.jobsMap.get(j.upstreamId)) {
       if (j.nodeId === node.id) {
@@ -293,6 +337,9 @@ export default class Processor {
     return null;
   }
 
+  /**
+   * @experimental
+   */
   findBranchLastJob(node: FlowNodeModel, job: JobModel): JobModel | null {
     const allJobs = Array.from(this.jobsMap.values());
     const branchJobs = [];
@@ -310,6 +357,9 @@ export default class Processor {
     return null;
   }
 
+  /**
+   * @experimental
+   */
   public getScope(sourceNodeId: number) {
     const node = this.nodesMap.get(sourceNodeId);
     const systemFns = {};
@@ -337,6 +387,9 @@ export default class Processor {
     };
   }
 
+  /**
+   * @experimental
+   */
   public getParsedValue(value, sourceNodeId: number, additionalScope?: object) {
     const template = parse(value);
     const scope = Object.assign(this.getScope(sourceNodeId), additionalScope);