cloud-web-corejs 1.0.54-dev.8 → 1.0.54-dev.800

package/src/components/xform/utils/treeTableUtil.js

@@ -0,0 +1,1265 @@
+export const TREE_TEMP_KEY_FIELD = "_X_TREE_TEMP_KEY";
+export const DEFAULT_MAP_CHILDREN_FIELD = "_X_ROW_CHILD";
+
+const INTERNAL_TREE_FIELDS = new Set([
+  "_X_ROW_KEY",
+  "_X_ROW_CHILD",
+  TREE_TEMP_KEY_FIELD,
+]);
+
+let tempKeySeed = 0;
+
+const hasOwn = (target, key) =>
+  Object.prototype.hasOwnProperty.call(target || {}, key);
+
+const isObject = (value) =>
+  value !== null && typeof value === "object";
+
+const cloneValue = (value, seen = new WeakMap()) => {
+  if (!isObject(value)) return value;
+  if (value instanceof Date) return new Date(value.getTime());
+  if (seen.has(value)) return seen.get(value);
+  if (Array.isArray(value)) {
+    let result = [];
+    seen.set(value, result);
+    value.forEach((item) => result.push(cloneValue(item, seen)));
+    return result;
+  }
+  let prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return value;
+  }
+  let result = {};
+  seen.set(value, result);
+  Object.keys(value).forEach((key) => {
+    result[key] = cloneValue(value[key], seen);
+  });
+  return result;
+};
+
+const normalizeRegistryValue = (value) =>
+  isRootParent(value) ? null : normalizeTreeKey(value);
+
+const registryHas = (registry, value) => {
+  if (!registry || typeof registry.forEach !== "function") return false;
+  let normalized = normalizeRegistryValue(value);
+  let matched = false;
+  registry.forEach((item) => {
+    if (normalizeRegistryValue(item) === normalized) matched = true;
+  });
+  return matched;
+};
+
+const assertSyncResult = (value, name) => {
+  if (value && typeof value.then === "function") {
+    throw new Error(`${name} 必须同步返回，不能返回 Promise`);
+  }
+  return value;
+};
+
+const callExternalParentValidator = (validator, value, row, operation) => {
+  if (typeof validator !== "function") return false;
+  let result = assertSyncResult(
+    validator(value, row, operation),
+    "validateExternalParentKey"
+  );
+  if (typeof result !== "boolean") {
+    throw new Error("validateExternalParentKey 必须返回 boolean");
+  }
+  return result;
+};
+
+const stableSerialize = (value, seen = new WeakSet()) => {
+  if (value === null) return "null";
+  let valueType = typeof value;
+  if (valueType === "undefined") return "undefined";
+  if (valueType === "string") return `string:${JSON.stringify(value)}`;
+  if (valueType === "number") {
+    if (Number.isNaN(value)) return "number:NaN";
+    if (!Number.isFinite(value)) return `number:${String(value)}`;
+    return `number:${value}`;
+  }
+  if (valueType === "boolean") return `boolean:${value}`;
+  if (valueType === "bigint") return `bigint:${value.toString()}`;
+  if (valueType === "function" || valueType === "symbol") {
+    throw new Error(`树节点包含无法比较的 ${valueType} 字段`);
+  }
+  if (value instanceof Date) {
+    return `date:${value.toISOString()}`;
+  }
+  if (value instanceof RegExp) {
+    return `regexp:${value.toString()}`;
+  }
+  if (seen.has(value)) {
+    throw new Error("树节点业务字段存在循环引用，无法校验多实例一致性");
+  }
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = `array:[${value
+      .map((item) => stableSerialize(item, seen))
+      .join(",")}]`;
+  } else {
+    result = `object:{${Object.keys(value)
+      .sort()
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${stableSerialize(value[key], seen)}`
+      )
+      .join(",")}}`;
+  }
+  seen.delete(value);
+  return result;
+};
+
+const getComparableSnapshot = (row, fields) => {
+  let result = {};
+  Object.keys(row || {})
+    .filter(
+      (key) =>
+        key !== fields.childrenField
+        && key !== fields.mapChildrenField
+        && !INTERNAL_TREE_FIELDS.has(key)
+    )
+    .sort()
+    .forEach((key) => {
+      result[key] = row[key];
+    });
+  return stableSerialize(result);
+};
+
+const validateFieldNames = (fields, identityConfig) => {
+  let relationFields = [
+    fields.rowField,
+    fields.parentField,
+    fields.childrenField,
+    fields.mapChildrenField,
+    fields.hasChildField,
+  ];
+  let relationSet = new Set(relationFields);
+  if (relationSet.size !== relationFields.length) {
+    throw new Error(`树表字段不能重复：${relationFields.join(", ")}`);
+  }
+  [
+    fields.rowField,
+    fields.parentField,
+    fields.childrenField,
+    fields.hasChildField,
+  ].forEach((field) => {
+    if (INTERNAL_TREE_FIELDS.has(field)) {
+      throw new Error(`树表业务字段不能使用内部字段名：${field}`);
+    }
+  });
+  if (
+    INTERNAL_TREE_FIELDS.has(fields.mapChildrenField)
+    && fields.mapChildrenField !== DEFAULT_MAP_CHILDREN_FIELD
+  ) {
+    throw new Error(
+      `mapChildren 不能使用内部字段名：${fields.mapChildrenField}`
+    );
+  }
+  if (!identityConfig) return;
+  let physicalIdField = identityConfig.physicalIdField;
+  if (
+    physicalIdField !== fields.rowField
+    && relationSet.has(physicalIdField)
+  ) {
+    throw new Error(
+      `physicalIdField 只能与 rowField 相同，不能使用：${physicalIdField}`
+    );
+  }
+  if (INTERNAL_TREE_FIELDS.has(physicalIdField)) {
+    throw new Error(`physicalIdField 不能使用内部字段名：${physicalIdField}`);
+  }
+};
+
+export const isRootParent = (value) =>
+  value === null
+  || value === undefined
+  || value === ""
+  || value === 0
+  || value === "0";
+
+export const normalizeTreeKey = (value) =>
+  isRootParent(value) ? "" : String(value);
+
+export const treeKeyEquals = (left, right) => {
+  if (isRootParent(left) || isRootParent(right)) {
+    return isRootParent(left) && isRootParent(right);
+  }
+  return normalizeTreeKey(left) === normalizeTreeKey(right);
+};
+
+export const resolveTreeFields = (
+  treeConfig = {},
+  { strict = false } = {}
+) => {
+  let fields = {
+    rowField: hasOwn(treeConfig, "rowField")
+      ? treeConfig.rowField
+      : "id",
+    parentField: hasOwn(treeConfig, "parentField")
+      ? treeConfig.parentField
+      : "f_parent",
+    childrenField: hasOwn(treeConfig, "children")
+      ? treeConfig.children
+      : "f_children",
+    mapChildrenField:
+      hasOwn(treeConfig, "mapChildren")
+        ? treeConfig.mapChildren
+        : DEFAULT_MAP_CHILDREN_FIELD,
+    hasChildField: hasOwn(treeConfig, "hasChild")
+      ? treeConfig.hasChild
+      : "f_has_child",
+    lazy: !!treeConfig.lazy,
+    transform: treeConfig.transform !== false,
+  };
+  if (strict) {
+    [
+      "rowField",
+      "parentField",
+      "childrenField",
+      "mapChildrenField",
+      "hasChildField",
+    ].forEach((key) => {
+      if (!fields[key] || typeof fields[key] !== "string") {
+        throw new Error(`treeConfig.${key} 不能为空`);
+      }
+    });
+    if (treeConfig.transform === false) {
+      throw new Error("xform 树表必须启用 treeConfig.transform");
+    }
+    validateFieldNames(fields);
+  }
+  return fields;
+};
+
+export const resolveTreeIdentityConfig = (
+  treeConfig = {},
+  config = {}
+) => {
+  let fields = resolveTreeFields(treeConfig);
+  let identityConfig = {
+    physicalIdField: hasOwn(config, "physicalIdField")
+      ? config.physicalIdField
+      : "id",
+    rootParentValue:
+      config.rootParentValue === undefined ? 0 : config.rootParentValue,
+    serverGeneratesRowField:
+      config.serverGeneratesRowField === undefined
+        ? fields.rowField === (config.physicalIdField || "id")
+        : !!config.serverGeneratesRowField,
+    persistedRowFieldChangeStrategy:
+      config.persistedRowFieldChangeStrategy || "reject",
+    changePersistedRowField: config.changePersistedRowField || null,
+    validateExternalParentKey:
+      config.validateExternalParentKey || null,
+  };
+  if (!isRootParent(identityConfig.rootParentValue)) {
+    throw new Error(
+      `rootParentValue 不是有效根值：${identityConfig.rootParentValue}`
+    );
+  }
+  if (
+    !identityConfig.physicalIdField
+    || typeof identityConfig.physicalIdField !== "string"
+  ) {
+    throw new Error("physicalIdField 不能为空");
+  }
+  if (
+    fields.rowField === "id"
+    && identityConfig.physicalIdField !== "id"
+  ) {
+    throw new Error(
+      'rowField 为 "id" 时 physicalIdField 必须同时为 "id"'
+    );
+  }
+  if (
+    !["reject", "transactional"].includes(
+      identityConfig.persistedRowFieldChangeStrategy
+    )
+  ) {
+    throw new Error("persistedRowFieldChangeStrategy 配置无效");
+  }
+  if (
+    identityConfig.persistedRowFieldChangeStrategy === "transactional"
+    && typeof identityConfig.changePersistedRowField !== "function"
+  ) {
+    throw new Error(
+      "transactional 模式必须配置 changePersistedRowField"
+    );
+  }
+  validateFieldNames(fields, identityConfig);
+  return identityConfig;
+};
+
+export const resolveTreeCopyConfig = (
+  fields,
+  identityConfig,
+  config = {}
+) => {
+  let rowFieldStrategy
+    = config.rowFieldStrategy
+    || (fields.rowField === identityConfig.physicalIdField
+      ? "regenerate"
+      : "preserve");
+  if (!["preserve", "regenerate", "custom"].includes(rowFieldStrategy)) {
+    throw new Error(`rowFieldStrategy 配置无效：${rowFieldStrategy}`);
+  }
+  if (
+    fields.rowField === identityConfig.physicalIdField
+    && rowFieldStrategy !== "regenerate"
+  ) {
+    throw new Error(
+      "rowField 与 physicalIdField 相同时复制只能使用 regenerate"
+    );
+  }
+  if (
+    fields.rowField === identityConfig.physicalIdField
+    && !identityConfig.serverGeneratesRowField
+  ) {
+    throw new Error(
+      "rowField 与 physicalIdField 相同时必须由服务端生成正式身份"
+    );
+  }
+  if (
+    config.orphanParentStrategy
+    && !["detach", "preserve"].includes(config.orphanParentStrategy)
+  ) {
+    throw new Error("treeCopyConfig.orphanParentStrategy 配置无效");
+  }
+  if (
+    config.lazyStrategy
+    && !["reject", "loadAll"].includes(config.lazyStrategy)
+  ) {
+    throw new Error("treeCopyConfig.lazyStrategy 配置无效");
+  }
+  if (
+    rowFieldStrategy === "custom"
+    && typeof config.generateRowField !== "function"
+  ) {
+    throw new Error("custom 复制策略必须配置 generateRowField");
+  }
+  if (
+    rowFieldStrategy === "regenerate"
+    && !config.generateRowField
+    && !identityConfig.serverGeneratesRowField
+  ) {
+    throw new Error(
+      "服务端不生成 rowField 时，regenerate 必须配置正式键生成器"
+    );
+  }
+  return {
+    rowFieldStrategy,
+    orphanParentStrategy: config.orphanParentStrategy || "detach",
+    lazyStrategy: config.lazyStrategy || "reject",
+    generateRowField: config.generateRowField || null,
+  };
+};
+
+export const resolveTreeSubmitConfig = (config = {}) => {
+  let result = {
+    orphanParentStrategy: config.orphanParentStrategy || "preserve",
+    unloadedChildrenStrategy:
+      config.unloadedChildrenStrategy || "reject",
+    successReconcileStrategy:
+      config.successReconcileStrategy || "reload",
+  };
+  if (!["preserve", "reject"].includes(result.orphanParentStrategy)) {
+    throw new Error("treeSubmitConfig.orphanParentStrategy 配置无效");
+  }
+  if (
+    !["reject", "loadAll", "omit"].includes(
+      result.unloadedChildrenStrategy
+    )
+  ) {
+    throw new Error("treeSubmitConfig.unloadedChildrenStrategy 配置无效");
+  }
+  if (result.successReconcileStrategy !== "reload") {
+    throw new Error("当前仅支持 successReconcileStrategy: reload");
+  }
+  return result;
+};
+
+export const makeTreeTempKey = () => {
+  tempKeySeed += 1;
+  return `row_${Date.now()}_${tempKeySeed}_${Math.floor(
+    Math.random() * 1000000
+  )}`;
+};
+
+export const markTemporaryTreeKey = (
+  row,
+  rowField,
+  value = makeTreeTempKey()
+) => {
+  row[rowField] = value;
+  row[TREE_TEMP_KEY_FIELD] = value;
+  return value;
+};
+
+export const isTemporaryTreeKey = (
+  row,
+  rowField,
+  identityConfig = {}
+) => {
+  if (!row || !rowField) return false;
+  let value = row[rowField];
+  if (
+    row[TREE_TEMP_KEY_FIELD] !== undefined
+    && row[TREE_TEMP_KEY_FIELD] !== null
+  ) {
+    return value === row[TREE_TEMP_KEY_FIELD];
+  }
+  return (
+    rowField === "id"
+    && (identityConfig.physicalIdField || "id") === "id"
+    && typeof value === "string"
+    && value.startsWith("row_")
+  );
+};
+
+export const clearTemporaryTreeKey = (row, rowField) => {
+  if (!row) return;
+  if (
+    rowField
+    && row[TREE_TEMP_KEY_FIELD] === row[rowField]
+  ) {
+    row[rowField] = null;
+  }
+  delete row[TREE_TEMP_KEY_FIELD];
+};
+
+export const getTreeLoadState = (
+  row,
+  { fields, isTreeNodeLoaded } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  if (!resolvedFields.lazy || !row?.[resolvedFields.hasChildField]) {
+    return {
+      complete: true,
+      loaded: true,
+      requiresLoad: false,
+    };
+  }
+  if (typeof isTreeNodeLoaded !== "function") {
+    return {
+      complete: false,
+      loaded: false,
+      requiresLoad: true,
+      reason: "missing-loader-state",
+    };
+  }
+  let loaded = !!assertSyncResult(
+    isTreeNodeLoaded(row),
+    "isTreeNodeLoaded"
+  );
+  return {
+    complete: loaded,
+    loaded,
+    requiresLoad: !loaded,
+  };
+};
+
+export const collectTreeNodes = (
+  source,
+  { fields, identityConfig } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let nodes = [];
+  let edges = [];
+  let occurrences = [];
+  let nodeMeta = new Map();
+  let visitedObjects = new WeakSet();
+  let keyMap = new Map();
+  let nodeIndexMap = new Map();
+  let auxiliaryRowKeyMap = new Map();
+  let physicalIdMap = new Map();
+  let physicalIdByRowKey = new Map();
+
+  let registerAuxiliaryIdentity = (
+    index,
+    value,
+    rowKey,
+    label
+  ) => {
+    if (value === null || value === undefined || value === "") return;
+    let normalized = normalizeTreeKey(value);
+    let previousRowKey = index.get(normalized);
+    if (previousRowKey && previousRowKey !== rowKey) {
+      throw new Error(`${label} ${value} 同时指向多个树节点`);
+    }
+    index.set(normalized, rowKey);
+  };
+
+  let visit = (items, parent, sourceField, priority) => {
+    if (!Array.isArray(items)) return;
+    items.forEach((node, index) => {
+      if (!isObject(node) || Array.isArray(node)) return;
+      let rowValue = node[resolvedFields.rowField];
+      if (isRootParent(rowValue)) {
+        throw new Error(
+          `树节点 ${resolvedFields.rowField} 不能为空或根哨兵`
+        );
+      }
+      let key = normalizeTreeKey(rowValue);
+      let temporaryMarker
+        = node[TREE_TEMP_KEY_FIELD] === rowValue
+          ? node[TREE_TEMP_KEY_FIELD]
+          : null;
+      registerAuxiliaryIdentity(
+        auxiliaryRowKeyMap,
+        node._X_ROW_KEY,
+        key,
+        "_X_ROW_KEY"
+      );
+      if (identityConfig?.physicalIdField) {
+        let physicalId = node[identityConfig.physicalIdField];
+        registerAuxiliaryIdentity(
+          physicalIdMap,
+          physicalId,
+          key,
+          identityConfig.physicalIdField
+        );
+        if (
+          physicalId !== null
+          && physicalId !== undefined
+          && physicalId !== ""
+        ) {
+          let normalizedPhysicalId = normalizeTreeKey(physicalId);
+          let previousPhysicalId = physicalIdByRowKey.get(key);
+          if (
+            physicalIdByRowKey.has(key)
+            && previousPhysicalId !== normalizedPhysicalId
+          ) {
+            throw new Error(
+              `树节点 ${rowValue} 存在冲突的物理 ID`
+            );
+          }
+          physicalIdByRowKey.set(key, normalizedPhysicalId);
+        }
+      }
+      if (parent) {
+        edges.push({
+          parent,
+          child: node,
+          parentKey: parent[resolvedFields.rowField],
+          childKey: rowValue,
+          sourceField,
+        });
+      }
+      occurrences.push({
+        node,
+        parent,
+        sourceField,
+        index,
+      });
+
+      let currentMeta = keyMap.get(key);
+      if (!currentMeta) {
+        let meta = {
+          key,
+          node,
+          priority,
+          snapshot: getComparableSnapshot(node, resolvedFields),
+          temporaryMarker,
+        };
+        keyMap.set(key, meta);
+        nodeMeta.set(key, meta);
+        nodeIndexMap.set(key, nodes.length);
+        nodes.push(node);
+      } else if (currentMeta.node !== node) {
+        let nextSnapshot = getComparableSnapshot(node, resolvedFields);
+        if (currentMeta.snapshot !== nextSnapshot) {
+          throw new Error(
+            `树节点 ${rowValue} 存在内容冲突的多个对象实例`
+          );
+        }
+        if (
+          currentMeta.temporaryMarker !== null
+          && temporaryMarker !== null
+          && currentMeta.temporaryMarker !== temporaryMarker
+        ) {
+          throw new Error(`树节点 ${rowValue} 存在冲突的临时标记`);
+        }
+        if (
+          currentMeta.temporaryMarker === null
+          && temporaryMarker !== null
+        ) {
+          currentMeta.temporaryMarker = temporaryMarker;
+        }
+        if (priority > currentMeta.priority) {
+          currentMeta.node = node;
+          currentMeta.priority = priority;
+          currentMeta.snapshot = nextSnapshot;
+          nodes[nodeIndexMap.get(key)] = node;
+        }
+      }
+
+      if (visitedObjects.has(node)) return;
+      visitedObjects.add(node);
+      visit(
+        node[resolvedFields.childrenField],
+        node,
+        resolvedFields.childrenField,
+        2
+      );
+      if (
+        resolvedFields.mapChildrenField
+        !== resolvedFields.childrenField
+      ) {
+        visit(
+          node[resolvedFields.mapChildrenField],
+          node,
+          resolvedFields.mapChildrenField,
+          1
+        );
+      }
+    });
+  };
+
+  visit(Array.isArray(source) ? source : [], null, null, 3);
+  return {
+    nodes,
+    edges,
+    occurrences,
+    nodeMeta,
+  };
+};
+
+export const validateTreeGraph = (
+  nodes,
+  edges,
+  { fields } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let nodeByKey = new Map();
+  let valueByKey = new Map();
+  nodes.forEach((node) => {
+    let value = node[resolvedFields.rowField];
+    let key = normalizeTreeKey(value);
+    if (nodeByKey.has(key) && nodeByKey.get(key) !== node) {
+      throw new Error(`树键重复：${value}`);
+    }
+    nodeByKey.set(key, node);
+    valueByKey.set(key, value);
+  });
+
+  let nestedParents = new Map();
+  edges.forEach((edge) => {
+    let parentKey = normalizeTreeKey(edge.parentKey);
+    let childKey = normalizeTreeKey(edge.childKey);
+    if (parentKey === childKey) {
+      throw new Error(`树节点不能指向自身：${edge.childKey}`);
+    }
+    let previous = nestedParents.get(childKey);
+    if (previous && previous !== parentKey) {
+      throw new Error(`树节点存在多个父节点：${edge.childKey}`);
+    }
+    nestedParents.set(childKey, parentKey);
+  });
+
+  let parentKeyByChild = new Map();
+  nodes.forEach((node) => {
+    let childValue = node[resolvedFields.rowField];
+    let childKey = normalizeTreeKey(childValue);
+    let ownsParent = hasOwn(node, resolvedFields.parentField);
+    let parentValue = node[resolvedFields.parentField];
+    let nestedParentKey = nestedParents.get(childKey);
+
+    if (ownsParent) {
+      if (isRootParent(parentValue)) {
+        if (nestedParentKey) {
+          throw new Error(`根节点嵌套在其他父节点下：${childValue}`);
+        }
+        parentKeyByChild.set(childKey, null);
+        return;
+      }
+      let explicitParentKey = normalizeTreeKey(parentValue);
+      if (
+        nestedParentKey
+        && explicitParentKey !== nestedParentKey
+      ) {
+        throw new Error(`父字段与嵌套位置冲突：${childValue}`);
+      }
+      if (explicitParentKey === childKey) {
+        throw new Error(`树节点不能指向自身：${childValue}`);
+      }
+      parentKeyByChild.set(childKey, explicitParentKey);
+      return;
+    }
+
+    parentKeyByChild.set(childKey, nestedParentKey || null);
+  });
+
+  let visitState = new Map();
+  let visit = (key) => {
+    let state = visitState.get(key);
+    if (state === 1) {
+      throw new Error(`树结构存在环：${valueByKey.get(key) || key}`);
+    }
+    if (state === 2) return;
+    visitState.set(key, 1);
+    let parentKey = parentKeyByChild.get(key);
+    if (parentKey && nodeByKey.has(parentKey)) visit(parentKey);
+    visitState.set(key, 2);
+  };
+  nodeByKey.forEach((node, key) => visit(key));
+
+  return {
+    nodeByKey,
+    valueByKey,
+    parentKeyByChild,
+  };
+};
+
+export const canonicalizeTreeInput = (
+  source,
+  { fields, identityConfig, strict = true } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let collected = collectTreeNodes(source, {
+    fields: resolvedFields,
+    identityConfig,
+  });
+  let graph = validateTreeGraph(collected.nodes, collected.edges, {
+    fields: resolvedFields,
+  });
+  let cloneByKey = new Map();
+  collected.nodes.forEach((node) => {
+    let key = normalizeTreeKey(node[resolvedFields.rowField]);
+    let clone = cloneValue(node);
+    delete clone[resolvedFields.childrenField];
+    delete clone[resolvedFields.mapChildrenField];
+    let temporaryMarker
+      = collected.nodeMeta.get(key)?.temporaryMarker;
+    if (temporaryMarker !== null && temporaryMarker !== undefined) {
+      clone[TREE_TEMP_KEY_FIELD] = temporaryMarker;
+    }
+    cloneByKey.set(key, clone);
+  });
+
+  collected.nodes.forEach((node) => {
+    let key = normalizeTreeKey(node[resolvedFields.rowField]);
+    let clone = cloneByKey.get(key);
+    let parentKey = graph.parentKeyByChild.get(key);
+    if (parentKey && graph.nodeByKey.has(parentKey)) {
+      clone[resolvedFields.parentField]
+        = graph.nodeByKey.get(parentKey)[resolvedFields.rowField];
+    } else if (
+      !hasOwn(clone, resolvedFields.parentField)
+      && identityConfig
+    ) {
+      clone[resolvedFields.parentField]
+        = identityConfig.rootParentValue;
+    }
+  });
+
+  if (strict) {
+    let normalizedKeys = new Set();
+    cloneByKey.forEach((clone) => {
+      let key = normalizeTreeKey(clone[resolvedFields.rowField]);
+      if (normalizedKeys.has(key)) {
+        throw new Error(
+          `树键归一后冲突：${clone[resolvedFields.rowField]}`
+        );
+      }
+      normalizedKeys.add(key);
+    });
+  }
+  return collected.nodes.map((node) =>
+    cloneByKey.get(normalizeTreeKey(node[resolvedFields.rowField]))
+  );
+};
+
+export const syncTreeKeyReferences = (
+  rows,
+  oldValue,
+  newValue,
+  { fields } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let visited = new WeakSet();
+  let visit = (items) => {
+    if (!Array.isArray(items)) return;
+    items.forEach((row) => {
+      if (!isObject(row) || visited.has(row)) return;
+      visited.add(row);
+      if (
+        treeKeyEquals(row[resolvedFields.parentField], oldValue)
+      ) {
+        row[resolvedFields.parentField] = newValue;
+      }
+      visit(row[resolvedFields.childrenField]);
+      visit(row[resolvedFields.mapChildrenField]);
+    });
+  };
+  visit(rows);
+  return rows;
+};
+
+const normalizeGeneratedValue = (result, fallbackTemporary) => {
+  if (isObject(result) && !Array.isArray(result)) {
+    return {
+      value: result.value,
+      temporary:
+        result.temporary === undefined
+          ? fallbackTemporary
+          : !!result.temporary,
+    };
+  }
+  return {
+    value: result,
+    temporary: fallbackTemporary,
+  };
+};
+
+const getTopologicalOrder = (nodes, graph, fields) => {
+  let nodeOrder = new Map();
+  nodes.forEach((node, index) => {
+    nodeOrder.set(normalizeTreeKey(node[fields.rowField]), index);
+  });
+  let childrenByParent = new Map();
+  let inDegree = new Map();
+  nodes.forEach((node) => {
+    let key = normalizeTreeKey(node[fields.rowField]);
+    inDegree.set(key, 0);
+  });
+  graph.parentKeyByChild.forEach((parentKey, childKey) => {
+    if (!parentKey || !graph.nodeByKey.has(parentKey)) return;
+    if (!childrenByParent.has(parentKey)) {
+      childrenByParent.set(parentKey, []);
+    }
+    childrenByParent.get(parentKey).push(childKey);
+    inDegree.set(childKey, (inDegree.get(childKey) || 0) + 1);
+  });
+  let queue = Array.from(inDegree.keys())
+    .filter((key) => inDegree.get(key) === 0)
+    .sort((left, right) => nodeOrder.get(left) - nodeOrder.get(right));
+  let result = [];
+  while (queue.length) {
+    let key = queue.shift();
+    result.push(graph.nodeByKey.get(key));
+    let children = childrenByParent.get(key) || [];
+    children
+      .sort((left, right) => nodeOrder.get(left) - nodeOrder.get(right))
+      .forEach((childKey) => {
+        inDegree.set(childKey, inDegree.get(childKey) - 1);
+        if (inDegree.get(childKey) === 0) queue.push(childKey);
+      });
+  }
+  if (result.length !== nodes.length) {
+    throw new Error("树结构存在环，无法生成复制顺序");
+  }
+  return result;
+};
+
+export const copyTreeData = (
+  source,
+  {
+    fields,
+    identityConfig,
+    copyConfig,
+    targetRows = [],
+    temporaryKeyRegistry,
+    knownFormalKeyRegistry,
+  } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let resolvedIdentity
+    = identityConfig
+    || resolveTreeIdentityConfig(
+      {
+        rowField: resolvedFields.rowField,
+        parentField: resolvedFields.parentField,
+        children: resolvedFields.childrenField,
+        mapChildren: resolvedFields.mapChildrenField,
+        hasChild: resolvedFields.hasChildField,
+      },
+      {}
+    );
+  let resolvedCopy
+    = copyConfig
+    || resolveTreeCopyConfig(resolvedFields, resolvedIdentity, {});
+  let canonicalRows = canonicalizeTreeInput(source, {
+    fields: resolvedFields,
+    identityConfig: resolvedIdentity,
+    strict: true,
+  });
+  let collected = collectTreeNodes(canonicalRows, {
+    fields: resolvedFields,
+    identityConfig: resolvedIdentity,
+  });
+  let graph = validateTreeGraph(collected.nodes, collected.edges, {
+    fields: resolvedFields,
+  });
+  let orderedNodes = getTopologicalOrder(
+    collected.nodes,
+    graph,
+    resolvedFields
+  );
+  let mapping = new Map();
+  let copyByOldKey = new Map();
+  let resolvedParentByOldKey = new Map();
+  let usedNewKeys = new Set();
+  let targetKeys = new Set();
+  let targetTemporaryKeys = new Set();
+  let generatedTemporaryKeys = new Set();
+  if (Array.isArray(targetRows) && targetRows.length) {
+    let targetCollected = collectTreeNodes(targetRows, {
+      fields: resolvedFields,
+      identityConfig: resolvedIdentity,
+    });
+    targetCollected.nodes.forEach((row) => {
+      targetKeys.add(
+        normalizeTreeKey(row[resolvedFields.rowField])
+      );
+      if (
+        isTemporaryTreeKey(
+          row,
+          resolvedFields.rowField,
+          resolvedIdentity
+        )
+      ) {
+        targetTemporaryKeys.add(row[resolvedFields.rowField]);
+      }
+    });
+    targetCollected.nodeMeta.forEach((meta) => {
+      if (meta.temporaryMarker !== null) {
+        targetTemporaryKeys.add(meta.temporaryMarker);
+      }
+    });
+  }
+
+  orderedNodes.forEach((node) => {
+    let oldValue = node[resolvedFields.rowField];
+    let oldKey = normalizeTreeKey(oldValue);
+    let oldParentValue = node[resolvedFields.parentField];
+    let oldParentKey = graph.parentKeyByChild.get(oldKey);
+    let newParentValue = resolvedIdentity.rootParentValue;
+    let parentNode = null;
+    let parentCopy = null;
+
+    if (oldParentKey && graph.nodeByKey.has(oldParentKey)) {
+      parentNode = graph.nodeByKey.get(oldParentKey);
+      newParentValue = mapping.get(oldParentKey);
+      parentCopy = copyByOldKey.get(oldParentKey);
+    } else if (oldParentKey) {
+      if (resolvedCopy.orphanParentStrategy === "preserve") {
+        if (
+          registryHas(temporaryKeyRegistry, oldParentValue)
+          || registryHas(targetTemporaryKeys, oldParentValue)
+        ) {
+          throw new Error(`外部父键仍为临时值：${oldParentValue}`);
+        }
+        let isFormal
+          = registryHas(knownFormalKeyRegistry, oldParentValue)
+          || callExternalParentValidator(
+            resolvedIdentity.validateExternalParentKey,
+            oldParentValue,
+            node,
+            "copy"
+          );
+        if (!isFormal) {
+          throw new Error(`无法确认外部父键：${oldParentValue}`);
+        }
+        newParentValue = oldParentValue;
+      }
+    }
+
+    let generated;
+    if (resolvedCopy.rowFieldStrategy === "preserve") {
+      if (
+        isTemporaryTreeKey(
+          node,
+          resolvedFields.rowField,
+          resolvedIdentity
+        )
+        || registryHas(temporaryKeyRegistry, oldValue)
+      ) {
+        throw new Error(`不能保留临时树键：${oldValue}`);
+      }
+      generated = {
+        value: oldValue,
+        temporary: false,
+      };
+    } else if (resolvedCopy.generateRowField) {
+      let result = assertSyncResult(
+        resolvedCopy.generateRowField({
+          node,
+          oldValue,
+          parentNode,
+          oldParentKey: oldParentValue,
+          newParentKey: newParentValue,
+          parentCopy,
+          fields: resolvedFields,
+          makeTempKey: makeTreeTempKey,
+        }),
+        "generateRowField"
+      );
+      generated = normalizeGeneratedValue(result, false);
+    } else {
+      generated = {
+        value: makeTreeTempKey(),
+        temporary: true,
+      };
+    }
+    if (isRootParent(generated.value)) {
+      throw new Error(`复制生成的树键无效：${generated.value}`);
+    }
+    if (
+      resolvedFields.rowField === resolvedIdentity.physicalIdField
+      && !generated.temporary
+    ) {
+      throw new Error(
+        "rowField 与 physicalIdField 相同时复制键必须是临时值"
+      );
+    }
+
+    let newKey = normalizeTreeKey(generated.value);
+    if (usedNewKeys.has(newKey) || targetKeys.has(newKey)) {
+      throw new Error(`复制生成的树键冲突：${generated.value}`);
+    }
+    usedNewKeys.add(newKey);
+
+    let copy = cloneValue(node);
+    delete copy[resolvedFields.childrenField];
+    delete copy[resolvedFields.mapChildrenField];
+    INTERNAL_TREE_FIELDS.forEach((field) => delete copy[field]);
+    copy[resolvedIdentity.physicalIdField] = null;
+    copy[resolvedFields.rowField] = generated.value;
+    copy[resolvedFields.parentField] = newParentValue;
+    if (generated.temporary) {
+      copy[TREE_TEMP_KEY_FIELD] = generated.value;
+      generatedTemporaryKeys.add(generated.value);
+    }
+    [
+      "create_by",
+      "_create_by",
+      "create_date",
+      "modify_by",
+      "_modify_by",
+      "modify_date",
+      "head_table_id",
+      "objectForeignId",
+    ].forEach((field) => {
+      if (field === "head_table_id" || field === "objectForeignId") {
+        delete copy[field];
+      } else if (hasOwn(copy, field)) {
+        copy[field] = null;
+      }
+    });
+    mapping.set(oldKey, generated.value);
+    copyByOldKey.set(oldKey, copy);
+    resolvedParentByOldKey.set(oldKey, newParentValue);
+  });
+
+  let copiedRows = canonicalRows.map((row) => {
+    let oldKey = normalizeTreeKey(row[resolvedFields.rowField]);
+    let copy = copyByOldKey.get(oldKey);
+    copy[resolvedFields.parentField]
+      = resolvedParentByOldKey.get(oldKey);
+    return copy;
+  });
+  let copiedGraph = collectTreeNodes(copiedRows, {
+    fields: resolvedFields,
+    identityConfig: resolvedIdentity,
+  });
+  validateTreeGraph(copiedGraph.nodes, copiedGraph.edges, {
+    fields: resolvedFields,
+  });
+  generatedTemporaryKeys.forEach((value) => {
+    temporaryKeyRegistry?.add?.(value);
+  });
+  return copiedRows;
+};
+
+export const sanitizeTreeRow = (
+  row,
+  {
+    fields,
+    identityConfig,
+    mode = "tree",
+    temporaryParentKeys,
+    temporaryKeyRegistry,
+    allowUnresolvedTemporary = false,
+  } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let resolvedIdentity
+    = identityConfig
+    || resolveTreeIdentityConfig(
+      {
+        rowField: resolvedFields.rowField,
+        parentField: resolvedFields.parentField,
+        children: resolvedFields.childrenField,
+        mapChildren: resolvedFields.mapChildrenField,
+        hasChild: resolvedFields.hasChildField,
+      },
+      {}
+    );
+  let result = cloneValue(row);
+  let children = result[resolvedFields.childrenField];
+  let temporary
+    = isTemporaryTreeKey(
+      result,
+      resolvedFields.rowField,
+      resolvedIdentity
+    )
+    || registryHas(
+      temporaryKeyRegistry,
+      result[resolvedFields.rowField]
+    );
+  if (temporary) {
+    if (resolvedIdentity.serverGeneratesRowField) {
+      result[resolvedFields.rowField] = null;
+    } else if (!allowUnresolvedTemporary) {
+      throw new Error(
+        `${resolvedFields.rowField} 仍是临时值，不能提交`
+      );
+    }
+  }
+  let parentTemporaryKeys
+    = temporaryParentKeys || temporaryKeyRegistry;
+  if (
+    parentTemporaryKeys
+    && registryHas(
+      parentTemporaryKeys,
+      result[resolvedFields.parentField]
+    )
+  ) {
+    result[resolvedFields.parentField] = null;
+  }
+
+  INTERNAL_TREE_FIELDS.forEach((field) => delete result[field]);
+  delete result[resolvedFields.mapChildrenField];
+  delete result[resolvedFields.childrenField];
+  if (mode === "tree" && Array.isArray(children) && children.length) {
+    result[resolvedFields.childrenField] = children.map((child) =>
+      sanitizeTreeRow(child, {
+        fields: resolvedFields,
+        identityConfig: resolvedIdentity,
+        mode,
+        temporaryParentKeys: parentTemporaryKeys,
+        temporaryKeyRegistry,
+        allowUnresolvedTemporary,
+      })
+    );
+  }
+  return result;
+};
+
+export const buildTreeSubmitData = (
+  source,
+  {
+    fields,
+    identityConfig,
+    submitConfig,
+    strict = true,
+    temporaryKeyRegistry,
+    knownFormalKeyRegistry,
+  } = {}
+) => {
+  let resolvedFields = fields || resolveTreeFields();
+  let resolvedIdentity
+    = identityConfig
+    || resolveTreeIdentityConfig(
+      {
+        rowField: resolvedFields.rowField,
+        parentField: resolvedFields.parentField,
+        children: resolvedFields.childrenField,
+        mapChildren: resolvedFields.mapChildrenField,
+        hasChild: resolvedFields.hasChildField,
+      },
+      {}
+    );
+  let resolvedSubmit
+    = submitConfig || resolveTreeSubmitConfig({});
+  let canonicalRows = canonicalizeTreeInput(source, {
+    fields: resolvedFields,
+    identityConfig: resolvedIdentity,
+    strict,
+  });
+  let collected = collectTreeNodes(canonicalRows, {
+    fields: resolvedFields,
+    identityConfig: resolvedIdentity,
+  });
+  let graph = validateTreeGraph(collected.nodes, collected.edges, {
+    fields: resolvedFields,
+  });
+  let tempKeys = new Set();
+  temporaryKeyRegistry?.forEach?.((value) => tempKeys.add(value));
+  canonicalRows.forEach((row) => {
+    if (
+      isTemporaryTreeKey(
+        row,
+        resolvedFields.rowField,
+        resolvedIdentity
+      )
+    ) {
+      tempKeys.add(row[resolvedFields.rowField]);
+    }
+  });
+
+  let cloneByKey = new Map();
+  canonicalRows.forEach((row) => {
+    let key = normalizeTreeKey(row[resolvedFields.rowField]);
+    let clone = cloneValue(row);
+    delete clone[resolvedFields.childrenField];
+    delete clone[resolvedFields.mapChildrenField];
+    cloneByKey.set(key, clone);
+  });
+
+  let roots = [];
+  canonicalRows.forEach((row) => {
+    let key = normalizeTreeKey(row[resolvedFields.rowField]);
+    let clone = cloneByKey.get(key);
+    let parentKey = graph.parentKeyByChild.get(key);
+    let parentValue = row[resolvedFields.parentField];
+    if (!parentKey) {
+      clone[resolvedFields.parentField]
+        = resolvedIdentity.rootParentValue;
+      roots.push(clone);
+      return;
+    }
+    if (graph.nodeByKey.has(parentKey)) {
+      let parentClone = cloneByKey.get(parentKey);
+      if (!Array.isArray(parentClone[resolvedFields.childrenField])) {
+        parentClone[resolvedFields.childrenField] = [];
+      }
+      parentClone[resolvedFields.childrenField].push(clone);
+      return;
+    }
+
+    if (registryHas(tempKeys, parentValue)) {
+      throw new Error(`父键仍指向未提交的临时节点：${parentValue}`);
+    }
+    if (resolvedSubmit.orphanParentStrategy === "reject") {
+      throw new Error(`父节点不在提交集合中：${parentValue}`);
+    }
+    let formal
+      = !strict
+      || registryHas(knownFormalKeyRegistry, parentValue)
+      || callExternalParentValidator(
+        resolvedIdentity.validateExternalParentKey,
+        parentValue,
+        row,
+        "submit"
+      );
+    if (!formal) {
+      throw new Error(`无法确认外部父键：${parentValue}`);
+    }
+    roots.push(clone);
+  });
+
+  return roots.map((row) =>
+    sanitizeTreeRow(row, {
+      fields: resolvedFields,
+      identityConfig: resolvedIdentity,
+      mode: "tree",
+      temporaryParentKeys: tempKeys,
+      temporaryKeyRegistry: tempKeys,
+      allowUnresolvedTemporary: !strict,
+    })
+  );
+};