@nocobase/plugin-flow-engine 2.1.0-alpha.45 → 2.1.0-alpha.46

package/dist/server/flow-surfaces/blueprint/normalize-document.js

@@ -588,12 +588,16 @@ function prepareFlowSurfaceApplyBlueprintDocument(input) {
   if (tabs.length > 1 && (page == null ? void 0 : page.enableTabs) === false) {
     (0, import_errors.throwBadRequest)(`flowSurfaces applyBlueprint page.enableTabs cannot be false when tabs.length > 1`);
   }
+  const normalizedPage = tabs.length === 1 ? {
+    ...page || {},
+    enableTabs: false
+  } : page;
   return {
     version: "1",
     mode,
     ...target ? { target } : {},
     ...navigation ? { navigation } : {},
-    ...page ? { page } : {},
+    ...normalizedPage ? { page: normalizedPage } : {},
     ...defaults ? { defaults } : {},
     tabs,
     assets,

package/dist/server/flow-surfaces/catalog.js

@@ -119,6 +119,10 @@ const FILTER_GROUP_SCHEMA = {
   additionalProperties: false,
   "x-flowSurfaceFormat": "filter-group"
 };
+const LINKAGE_RULES_SCHEMA = {
+  type: "array",
+  "x-flowSurfaceFormat": "linkage-rules"
+};
 const DEFAULT_DIRECT_EVENTS = ["beforeRender"];
 const ACTION_DIRECT_EVENTS = ["click", "beforeRender"];
 const ACTION_OBJECT_EVENTS = ["click"];
@@ -207,7 +211,7 @@ const ACTION_BUTTON_SETTINGS_GROUP = {
     "general.type": STRING_SCHEMA,
     "general.danger": BOOLEAN_SCHEMA,
     "general.color": STRING_SCHEMA,
-    "linkageRules.value": ARRAY_SCHEMA
+    "linkageRules.value": LINKAGE_RULES_SCHEMA
   }
 };
 const TRIGGER_WORKFLOWS_SETTINGS_GROUP = {
@@ -302,7 +306,7 @@ const EVENT_SETTINGS_GROUP = {
   allowedPaths: ["linkageRules.value"],
   eventBindingSteps: ["linkageRules"],
   pathSchemas: {
-    "linkageRules.value": ARRAY_SCHEMA
+    "linkageRules.value": LINKAGE_RULES_SCHEMA
   }
 };
 const CREATE_FORM_SETTINGS_EVENT_ONLY_GROUP = {
@@ -323,7 +327,7 @@ const DETAILS_SETTINGS_GROUP = {
     ...FORM_LAYOUT_PATH_SCHEMAS,
     "dataScope.filter": FILTER_GROUP_SCHEMA,
     "defaultSorting.sort": ARRAY_SCHEMA,
-    "linkageRules.value": ARRAY_SCHEMA
+    "linkageRules.value": LINKAGE_RULES_SCHEMA
   }
 };
 const FILTER_FORM_BLOCK_SETTINGS_GROUP = {
@@ -350,7 +354,7 @@ const BLOCK_CARD_SETTINGS_GROUP = {
     "titleDescription.description": STRING_SCHEMA,
     "blockHeight.heightMode": BLOCK_HEIGHT_MODE_SCHEMA,
     "blockHeight.height": NUMBER_SCHEMA,
-    "linkageRules.value": ARRAY_SCHEMA
+    "linkageRules.value": LINKAGE_RULES_SCHEMA
   }
 };
 const CALENDAR_SETTINGS_GROUP = {
@@ -2191,7 +2195,7 @@ CALENDAR_READONLY_ACTION_CONTRACT.domains.stepParams = groupedDomain({
     mergeStrategy: "deep",
     eventBindingSteps: ["linkageRules"],
     pathSchemas: {
-      "linkageRules.value": ARRAY_SCHEMA
+      "linkageRules.value": LINKAGE_RULES_SCHEMA
     }
   }
 });

package/dist/server/flow-surfaces/chart-config.js

@@ -64,7 +64,91 @@ __export(chart_config_exports, {
 module.exports = __toCommonJS(chart_config_exports);
 var import_lodash = __toESM(require("lodash"));
 var import_errors = require("./errors");
+var import_filter_group = require("./filter-group");
 const CHART_REPAIR_HINT = "This is a chart payload shape problem. Repair the current chart query/visual mappings and keep the chart block type. Do not change this block type to table, jsBlock, actionPanel, gridCard, or another block type. KPI / summary numbers should use jsBlock; charts are for trends, distributions, rankings, and visual analysis.";
+const CHART_FORBIDDEN_FALLBACKS = [
+  "table",
+  "list",
+  "jsBlock",
+  "actionPanel",
+  "gridCard",
+  "markdown",
+  "drop chart",
+  "defer chart"
+];
+const CHART_REPAIR_STEPS = [
+  "Keep the block type as chart.",
+  "Repair the chart query and visual mappings on the current chart payload.",
+  "Retry the chart payload instead of replacing the chart with another block type, omitting it, or deferring it."
+];
+const CHART_EXPECTED_SHAPE = {
+  settings: {
+    query: {
+      mode: "builder",
+      resource: {
+        dataSourceKey: "main",
+        collectionName: "employees"
+      },
+      measures: [
+        {
+          field: "id",
+          aggregation: "count",
+          alias: "employeeCount"
+        }
+      ]
+    },
+    visual: {
+      mode: "basic",
+      type: "bar",
+      mappings: {
+        x: "status",
+        y: "employeeCount"
+      }
+    }
+  }
+};
+function withChartRepairDetails(details = {}) {
+  return {
+    ...details,
+    requiredBlockType: "chart",
+    fixStrategy: "repair_same_block_type",
+    repairHint: CHART_REPAIR_HINT,
+    repairSteps: CHART_REPAIR_STEPS,
+    expectedShape: CHART_EXPECTED_SHAPE,
+    repairExample: {
+      settings: {
+        query: {
+          mode: "builder",
+          resource: {
+            dataSourceKey: "main",
+            collectionName: "<collectionName>"
+          },
+          measures: [
+            {
+              field: "id",
+              aggregation: "count",
+              alias: "recordCount"
+            }
+          ],
+          dimensions: [
+            {
+              field: "<dimensionField>"
+            }
+          ]
+        },
+        visual: {
+          mode: "basic",
+          type: "bar",
+          mappings: {
+            x: "<dimensionField>",
+            y: "recordCount"
+          }
+        }
+      }
+    },
+    forbiddenFallbacks: CHART_FORBIDDEN_FALLBACKS
+  };
+}
 function withChartRepairMessage(message) {
   return `${message}. ${CHART_REPAIR_HINT}`;
 }
@@ -86,10 +170,6 @@ const CHART_SORT_DIRECTIONS = ["asc", "desc"];
 const CHART_SORT_NULLS = ["default", "first", "last"];
 const CHART_LABEL_TYPES = ["value", "percent"];
 const CHART_FUNNEL_SORTS = ["descending", "ascending"];
-const EMPTY_FILTER_GROUP = {
-  logic: "$and",
-  items: []
-};
 const CHART_SAFE_DEFAULT_HINTS = [
   {
     key: "builder_basic_minimal",
@@ -375,6 +455,17 @@ function normalizeFieldPathValue(input, label, options = {}) {
   }
   throw new import_errors.FlowSurfaceBadRequestError(`${label} must be a string or string[]`);
 }
+function normalizeChartQueryFieldPathValue(input, label, options = {}) {
+  const normalized = normalizeFieldPathValue(input, label, options);
+  if (typeof normalized !== "string" || !normalized.includes(".")) {
+    return normalized;
+  }
+  const segments = normalized.split(".").map((segment) => segment.trim());
+  if (segments.some((segment) => !segment)) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label} cannot contain empty path segments`);
+  }
+  return segments;
+}
 function aliasOfFieldValue(input) {
   if (Array.isArray(input)) {
     return input.filter(Boolean).map((item) => String(item)).join(".");
@@ -406,7 +497,7 @@ function fromPersistedOrder(input) {
   return CHART_SORT_DIRECTION_SET.has(normalized) ? normalized : void 0;
 }
 function createEmptyFilterGroup() {
-  return import_lodash.default.cloneDeep(EMPTY_FILTER_GROUP);
+  return import_lodash.default.cloneDeep(import_filter_group.FLOW_SURFACE_EMPTY_FILTER_GROUP);
 }
 function assertAllowedKeys(input, allowed, label) {
   const unknownKeys = Object.keys(input).filter((key) => !allowed.has(key));
@@ -482,25 +573,29 @@ function normalizeMergedChartResource(query, options = {}) {
 function normalizeChartMeasure(input, index) {
   const label = `chart query.measures[${index}]`;
   const normalized = ensurePlainObject(input, label);
+  const field = normalizeChartQueryFieldPathValue(normalized.field, `${label}.field`, { required: true });
+  const alias = normalizeOptionalTrimmedString(normalized.alias, `${label}.alias`);
   const aggregation = normalizeOptionalEnumValue(
     normalized.aggregation,
     CHART_QUERY_AGGREGATION_SET,
     `${label}.aggregation`
   );
   return buildDefinedObject({
-    field: normalizeFieldPathValue(normalized.field, `${label}.field`, { required: true }),
+    field,
     aggregation,
-    alias: normalizeOptionalTrimmedString(normalized.alias, `${label}.alias`),
+    alias: alias || (Array.isArray(field) && field.length > 1 ? aliasOfFieldValue(field) : void 0),
     distinct: normalizeOptionalBoolean(normalized.distinct, `${label}.distinct`)
   });
 }
 function normalizeChartDimension(input, index) {
   const label = `chart query.dimensions[${index}]`;
   const normalized = ensurePlainObject(input, label);
+  const field = normalizeChartQueryFieldPathValue(normalized.field, `${label}.field`, { required: true });
+  const alias = normalizeOptionalTrimmedString(normalized.alias, `${label}.alias`);
   return buildDefinedObject({
-    field: normalizeFieldPathValue(normalized.field, `${label}.field`, { required: true }),
+    field,
     format: normalizeOptionalTrimmedString(normalized.format, `${label}.format`),
-    alias: normalizeOptionalTrimmedString(normalized.alias, `${label}.alias`)
+    alias: alias || (Array.isArray(field) && field.length > 1 ? aliasOfFieldValue(field) : void 0)
   });
 }
 function normalizeBuilderCountMeasureFieldForRuntime(measure, dimensions) {
@@ -511,6 +606,12 @@ function normalizeBuilderCountMeasureFieldForRuntime(measure, dimensions) {
   if (!fallbackDimension) {
     return measure;
   }
+  if (Array.isArray(fallbackDimension.field) && fallbackDimension.field.length > 1) {
+    return measure;
+  }
+  if (typeof fallbackDimension.field === "string" && fallbackDimension.field.includes(".")) {
+    return measure;
+  }
   return {
     ...measure,
     field: import_lodash.default.cloneDeep(fallbackDimension.field)
@@ -525,18 +626,113 @@ function normalizeChartSortingItem(input, index) {
     `${label}.${hasOwn(normalized, "direction") ? "direction" : "order"}`
   );
   return buildDefinedObject({
-    field: normalizeFieldPathValue(normalized.field, `${label}.field`, { required: true }),
+    field: normalizeChartQueryFieldPathValue(normalized.field, `${label}.field`, { required: true }),
     order: toPersistedOrder(direction),
     nulls: normalizeOptionalEnumValue(normalized.nulls, CHART_SORT_NULLS_SET, `${label}.nulls`)
   });
 }
+function isFilterGroupLike(input) {
+  return import_lodash.default.isPlainObject(input) && isBackendQueryLogicKey(input.logic) && Array.isArray(input.items);
+}
+function assertFilterGroupKeys(input, label) {
+  if (!isFilterGroupLike(input)) {
+    return;
+  }
+  const unsupportedKeys = Object.keys(input).filter((key) => key !== "logic" && key !== "items");
+  if (unsupportedKeys.length) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label} does not support: ${unsupportedKeys.join(", ")}`);
+  }
+  if (Array.isArray(input.items)) {
+    input.items.forEach((item, index) => {
+      assertFilterGroupKeys(item, `${label}.items[${index}]`);
+    });
+  }
+}
+function isBackendQueryLogicKey(key) {
+  return key === "$and" || key === "$or";
+}
+function getBackendQueryLogicKey(input, label) {
+  const keys = Object.keys(input);
+  const logicKeys = keys.filter(isBackendQueryLogicKey);
+  if (!logicKeys.length) {
+    return void 0;
+  }
+  if (logicKeys.length > 1 || keys.length > 1) {
+    throw new import_errors.FlowSurfaceBadRequestError(
+      `${label}: cannot convert backend query filter with mixed logical and field conditions`
+    );
+  }
+  return logicKeys[0];
+}
+function convertBackendFieldConditionToFilterItems(field, condition, label) {
+  if (!field.trim() || field.startsWith("$")) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label}: cannot convert backend query filter field "${field}"`);
+  }
+  if (!import_lodash.default.isPlainObject(condition)) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label}.${field}: backend query filter condition must be an object`);
+  }
+  const operators = Object.keys(condition);
+  if (!operators.length) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label}.${field}: backend query filter condition cannot be empty`);
+  }
+  return operators.map((operator) => {
+    if (!operator.startsWith("$")) {
+      (0, import_filter_group.assertFlowSurfaceFilterOperator)(operator, `${label}.${field}.${operator}`);
+    }
+    if (!operator.startsWith("$") || isBackendQueryLogicKey(operator)) {
+      throw new import_errors.FlowSurfaceBadRequestError(
+        `${label}.${field}: cannot convert backend query filter operator "${operator}"`
+      );
+    }
+    return {
+      path: field,
+      operator,
+      value: import_lodash.default.cloneDeep(condition[operator])
+    };
+  });
+}
+function convertBackendQueryFilterToFilterGroup(input, label) {
+  const logicKey = getBackendQueryLogicKey(input, label);
+  if (logicKey) {
+    const operands = input[logicKey];
+    if (!Array.isArray(operands)) {
+      throw new import_errors.FlowSurfaceBadRequestError(`${label}.${logicKey}: backend query filter operands must be an array`);
+    }
+    return {
+      logic: logicKey,
+      items: operands.map(
+        (operand, index) => convertBackendQueryOperandToFilterItem(operand, `${label}.${logicKey}[${index}]`)
+      )
+    };
+  }
+  return {
+    logic: "$and",
+    items: Object.entries(input).flatMap(
+      ([field, condition]) => convertBackendFieldConditionToFilterItems(field, condition, label)
+    )
+  };
+}
+function convertBackendQueryOperandToFilterItem(input, label) {
+  if (isFilterGroupLike(input)) {
+    throw new import_errors.FlowSurfaceBadRequestError(`${label}: cannot mix filter groups with backend query filters`);
+  }
+  const group = convertBackendQueryFilterToFilterGroup(ensurePlainObject(input, label), label);
+  if (group.logic === "$and" && group.items.length === 1) {
+    return group.items[0];
+  }
+  return group;
+}
 function normalizeFilterGroupValue(input, label) {
   if (import_lodash.default.isUndefined(input) || import_lodash.default.isNull(input)) {
     return void 0;
   }
   const normalized = ensurePlainObject(input, label);
-  validateFilterGroupPaths(normalized, label);
-  return import_lodash.default.cloneDeep(normalized);
+  assertFilterGroupKeys(normalized, label);
+  const filterGroup = !Object.keys(normalized).length || isFilterGroupLike(normalized) ? (0, import_filter_group.normalizeFlowSurfaceFilterGroupValue)(normalized, label, { strictDateValues: true }) : (0, import_filter_group.normalizeFlowSurfaceFilterGroupValue)(convertBackendQueryFilterToFilterGroup(normalized, label), label, {
+    strictDateValues: true
+  });
+  validateFilterGroupPaths(filterGroup, label);
+  return filterGroup;
 }
 function validateFilterGroupPaths(input, label) {
   const items = Array.isArray(input == null ? void 0 : input.items) ? input.items : [];
@@ -568,6 +764,7 @@ function inferQueryMode(query) {
 }
 function validateLooseChartQuery(query) {
   inferQueryMode(query);
+  validateChartQueryFilterOperators(query);
   if (!hasOwn(query, "resource") || !hasOwn(query, "collectionPath")) {
     return;
   }
@@ -582,6 +779,11 @@ function validateLooseChartQuery(query) {
     );
   }
 }
+function validateChartQueryFilterOperators(query) {
+  if (hasOwn(query, "filter")) {
+    normalizeFilterGroupValue(query.filter, "chart query.filter");
+  }
+}
 function canStrictNormalizeChartQuery(query) {
   validateLooseChartQuery(query);
   const mode = inferQueryMode(query);
@@ -605,7 +807,10 @@ function mergeChartQuerySection(current, patch) {
   const nextMode = inferQueryMode(normalizedPatch);
   const modeChanged = currentMode && currentMode !== nextMode;
   const base = modeChanged ? {} : current || {};
-  const merged = mergeReplaceArrays(base, normalizedPatch);
+  const merged = mergeReplaceArrays(base, import_lodash.default.omit(normalizedPatch, ["filter"]));
+  if (hasOwn(normalizedPatch, "filter")) {
+    merged.filter = import_lodash.default.cloneDeep(normalizedPatch.filter);
+  }
   if (nextMode !== "builder") {
     return merged;
   }
@@ -1092,10 +1297,9 @@ function assertBasicVisualMappingsAgainstBuilderQuery(builderVisual, query) {
         ),
         void 0,
         {
-          details: {
-            repairHint: CHART_REPAIR_HINT,
+          details: withChartRepairDetails({
             allowedOutputs: Array.from(allowedOutputs)
-          }
+          })
         }
       );
     }

package/dist/server/flow-surfaces/contract-guard.js

@@ -165,7 +165,7 @@ class FlowSurfaceContractGuard {
       if (typeof on === "string" && !allowedDirectEvents.has(eventName)) {
         (0, import_errors.throwBadRequest)(`flowSurfaces flow '${key}' event '${eventName}' is not allowed on '${node == null ? void 0 : node.use}'`);
       }
-      if (typeof on !== "string" && !allowedObjectEvents.has(eventName)) {
+      if (typeof on !== "string" && !allowedObjectEvents.has(eventName) && !allowedDirectEvents.has(eventName)) {
         (0, import_errors.throwBadRequest)(`flowSurfaces flow '${key}' event '${eventName}' is not allowed on '${node == null ? void 0 : node.use}'`);
       }
       const phase = onObj == null ? void 0 : onObj.phase;
@@ -349,33 +349,67 @@ function collectSchemaValueErrors(value, schema, path) {
 function normalizeDomainValue(value, contract, context) {
   const normalized = import_lodash.default.cloneDeep(value);
   Object.entries(contract.pathSchemas || {}).forEach(([path, schema]) => {
-    if (!import_lodash.default.has(normalized, path) || !isFilterGroupSchema(schema)) {
+    if (!import_lodash.default.has(normalized, path)) {
       return;
     }
-    import_lodash.default.set(normalized, path, normalizeFilterGroupValue(import_lodash.default.get(normalized, path), context, path));
+    if (isFilterGroupSchema(schema)) {
+      import_lodash.default.set(normalized, path, normalizeFilterGroupValue(import_lodash.default.get(normalized, path), context, path));
+    } else if (isLinkageRulesSchema(schema)) {
+      import_lodash.default.set(normalized, path, normalizeLinkageRulesValue(import_lodash.default.get(normalized, path), context, path));
+    }
   });
   return normalized;
 }
 function normalizeGroupValue(value, groupContract, context) {
   const normalized = import_lodash.default.cloneDeep(value);
   Object.entries(groupContract.pathSchemas || {}).forEach(([path, schema]) => {
-    if (!import_lodash.default.has(normalized, path) || !isFilterGroupSchema(schema)) {
+    if (!import_lodash.default.has(normalized, path)) {
       return;
     }
-    import_lodash.default.set(normalized, path, normalizeFilterGroupValue(import_lodash.default.get(normalized, path), context, path));
+    if (isFilterGroupSchema(schema)) {
+      import_lodash.default.set(normalized, path, normalizeFilterGroupValue(import_lodash.default.get(normalized, path), context, path));
+    } else if (isLinkageRulesSchema(schema)) {
+      import_lodash.default.set(normalized, path, normalizeLinkageRulesValue(import_lodash.default.get(normalized, path), context, path));
+    }
   });
   return normalized;
 }
 function isFilterGroupSchema(schema) {
   return (schema == null ? void 0 : schema["x-flowSurfaceFormat"]) === "filter-group";
 }
+function isLinkageRulesSchema(schema) {
+  return (schema == null ? void 0 : schema["x-flowSurfaceFormat"]) === "linkage-rules";
+}
 function normalizeFilterGroupValue(value, context, path) {
   const domainPath = context.groupKey ? `${context.domain}.${context.groupKey}.${path}` : `${context.domain}.${path}`;
   return (0, import_filter_group.normalizeFlowSurfaceFilterGroupValue)(
     value,
-    `flowSurfaces updateSettings domain '${domainPath}' on '${context.use}' expects FilterGroup like ${import_filter_group.FLOW_SURFACE_FILTER_GROUP_EXAMPLE}`
+    `flowSurfaces updateSettings domain '${domainPath}' on '${context.use}' expects FilterGroup like ${import_filter_group.FLOW_SURFACE_FILTER_GROUP_EXAMPLE}`,
+    { strictDateValues: true }
   );
 }
+function normalizeLinkageRulesValue(value, context, path) {
+  if (!Array.isArray(value)) {
+    return value;
+  }
+  return value.map((rule, index) => {
+    if (!import_lodash.default.isPlainObject(rule) || !import_lodash.default.has(rule, "condition")) {
+      return rule;
+    }
+    const normalizedRule = import_lodash.default.cloneDeep(rule);
+    const domainPath = context.groupKey ? `${context.domain}.${context.groupKey}.${path}[${index}].condition` : `${context.domain}.${path}[${index}].condition`;
+    import_lodash.default.set(
+      normalizedRule,
+      "condition",
+      (0, import_filter_group.normalizeFlowSurfaceCompatibleFilterGroupValue)(
+        import_lodash.default.get(normalizedRule, "condition"),
+        `flowSurfaces updateSettings domain '${domainPath}' on '${context.use}' expects FilterGroup or backend query filter like ${import_filter_group.FLOW_SURFACE_FILTER_GROUP_EXAMPLE}`,
+        { strictDateValues: true }
+      )
+    );
+    return normalizedRule;
+  });
+}
 function isContractDefinedFlowGroup(groupContract) {
   if (!groupContract) {
     return false;

package/dist/server/flow-surfaces/default-block-actions.js

@@ -104,6 +104,8 @@ const FLOW_SURFACE_DEFAULT_BLOCK_ACTIONS = {
   ],
   calendar: [
     { type: "filter", scope: "actions" },
+    { type: "turnPages", scope: "actions" },
+    { type: "selectView", scope: "actions" },
     { type: "refresh", scope: "actions" },
     {
       type: "addNew",

package/dist/server/flow-surfaces/errors.d.ts

@@ -8,6 +8,7 @@
  */
 export type FlowSurfaceErrorType = 'bad_request' | 'forbidden' | 'conflict' | 'internal_error';
 export interface FlowSurfaceErrorItem {
+    index?: number;
     message: string;
     type: FlowSurfaceErrorType;
     code: string;
@@ -48,6 +49,20 @@ export declare class FlowSurfaceAggregateError extends FlowSurfaceError {
     readonly errors: FlowSurfaceErrorItem[];
     constructor(errors: FlowSurfaceErrorItemInput[], message?: string);
     toResponseBody(): {
+        message: string;
+        errorCount: number;
+        details: {
+            requiredBlockPolicy?: {
+                requiredBlockTypes: string[];
+                fixStrategy: string;
+                doNotReplaceOrDrop: boolean;
+            };
+            errorCount: number;
+            mustFixAllErrorsBeforeRetry: boolean;
+            retryPolicy: string;
+            sameWriteRetryRequired: boolean;
+            agentInstruction: string;
+        };
         errors: FlowSurfaceErrorItem[];
     };
 }

package/dist/server/flow-surfaces/errors.js

@@ -88,14 +88,27 @@ class FlowSurfaceInternalError extends FlowSurfaceError {
 }
 class FlowSurfaceAggregateError extends FlowSurfaceError {
   errors;
-  constructor(errors, message = "flowSurfaces authoring validation failed") {
-    const normalizedErrors = errors.map((error) => normalizeFlowSurfaceErrorItemInput(error));
-    super(message, 400, "bad_request", "FLOW_SURFACE_AUTHORING_VALIDATION_FAILED");
+  constructor(errors, message) {
+    const normalizedErrors = errors.map(
+      (error, index) => normalizeFlowSurfaceErrorItemInput({
+        ...error,
+        index: index + 1
+      })
+    );
+    super(
+      message || buildAggregateBadRequestMessage(normalizedErrors.length),
+      400,
+      "bad_request",
+      "FLOW_SURFACE_AUTHORING_VALIDATION_FAILED"
+    );
     this.name = "FlowSurfaceAggregateError";
     this.errors = normalizedErrors;
   }
   toResponseBody() {
     return {
+      message: this.message,
+      errorCount: this.errors.length,
+      details: buildAggregateBadRequestDetails(this.errors),
       errors: this.errors
     };
   }
@@ -162,6 +175,9 @@ function buildDefinedErrorItem(input) {
     code: input.code,
     status: input.status
   };
+  if (typeof input.index !== "undefined") {
+    output.index = input.index;
+  }
   if (typeof input.path !== "undefined") {
     output.path = input.path;
   }
@@ -176,6 +192,7 @@ function buildDefinedErrorItem(input) {
 function normalizeFlowSurfaceErrorItemInput(input) {
   return buildDefinedErrorItem({
     message: input.message,
+    index: input.index,
     type: input.type || "bad_request",
     code: input.code || "FLOW_SURFACE_AUTHORING_VALIDATION_ERROR",
     status: input.status || 400,
@@ -184,6 +201,35 @@ function normalizeFlowSurfaceErrorItemInput(input) {
     details: input.details
   });
 }
+function buildAggregateBadRequestMessage(errorCount) {
+  return `flowSurfaces authoring validation failed with ${errorCount} error(s); fix all errors before retrying the same write`;
+}
+function buildAggregateBadRequestDetails(errors) {
+  const requiredBlockTypes = Array.from(
+    new Set(
+      errors.map((error) => {
+        var _a;
+        return (_a = error.details) == null ? void 0 : _a.requiredBlockType;
+      }).filter(
+        (requiredBlockType) => typeof requiredBlockType === "string" && !!requiredBlockType
+      )
+    )
+  );
+  return {
+    errorCount: errors.length,
+    mustFixAllErrorsBeforeRetry: true,
+    retryPolicy: "fix_all_errors_before_retry_same_write",
+    sameWriteRetryRequired: true,
+    agentInstruction: "Read the complete errors[] array. Fix every listed error in one payload revision before retrying the same write. Do not fix only the first error and immediately retry. Do not drop, defer, or replace required chart, jsBlock, or JS/RunJS work to bypass validation.",
+    ...requiredBlockTypes.length ? {
+      requiredBlockPolicy: {
+        requiredBlockTypes,
+        fixStrategy: "repair_same_block_type",
+        doNotReplaceOrDrop: true
+      }
+    } : {}
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlowSurfaceAggregateError,

package/dist/server/flow-surfaces/event-flow-normalizer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+export type FlowSurfaceEventFlowRecord = Record<string, unknown>;
+export type FlowSurfaceEventFlowRegistry = Record<string, FlowSurfaceEventFlowRecord>;
+export declare function buildFlowSurfaceEmptyEventCondition(): {
+    logic: string;
+    items: any[];
+};
+export declare function normalizeFlowSurfaceEventFlowOn(on: unknown): unknown;
+export declare function normalizeFlowSurfaceEventFlow(actionName: string, key: string, flowInput: unknown): FlowSurfaceEventFlowRecord;
+export declare function normalizeFlowSurfaceEventFlowRegistry(actionName: string, flowRegistry: Record<string, unknown>): FlowSurfaceEventFlowRegistry;
+export declare function normalizeFlowSurfaceEventFlowRegistry<T>(actionName: string, flowRegistry: T): T;
+export declare function isFlowSurfaceBeforeAllEventFlow(flow: unknown): boolean;