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

package/src/components/xform/docs//346/240/221/350/241/250rowField/346/224/266/346/225/233-/350/220/275/345/234/260/346/226/207/346/241/243.md

@@ -0,0 +1,1427 @@
+# 树表 rowField 收敛——最终落地方案
+
+> 日期：2026-07-28  
+> 范围：xform `data-table` 且 `isTreeTable: true` 的编辑、复制与提交链路  
+> 状态：方案已定稿；本文是后续实现、测试和验收基线，不代表代码已经按本文完成  
+> 核心修正：`rowField` 是树关系键，不等同于数据库物理 ID；复制时不能一律把
+> `node[rowField]` 改成 `row_*`
+
+## 1. 目标与边界
+
+本次改造要同时解决以下问题：
+
+1. `treeConfig.rowField`、`parentField`、`children`、`mapChildren` 在新增、编辑、
+   复制、展开、排序和提交链路中使用同一套字段解析结果；
+2. 复制树表时清空原记录的物理 ID，避免覆盖原数据或产生主键冲突；
+3. `rowField` 是产品编码等业务键时保留原值，不擅自生成新的业务编码；
+4. `rowField` 是纯技术树键时，复制后允许生成新的 `row_*` 临时键，并同步重映射
+   整棵子树的 `parentField`；
+5. 单行保存与整表提交使用同一套递归清洗规则；
+6. 平铺数据、嵌套数据、懒加载数据以及 VXE 的 `children`/`mapChildren` 双份引用
+   都能正确组装，节点不丢失、不重复；
+7. 临时值、VXE 内部字段和旧单物理 ID 不进入最终提交对象；
+8. 所有提交前处理基于副本完成，不修改表格当前编辑态数据。
+
+本次不改变后端的树结构协议，不修改通用的
+`src/resources/js/base/common.js`，也不把业务编码生成职责移到通用树表组件。
+
+## 2. 标识语义必须拆开
+
+| 名称 | 示例 | 职责 | 复制规则 |
+|---|---|---|---|
+| 物理 ID `physicalIdField` | `id: 10086` | 数据库记录身份、更新/删除定位 | 一律清空 |
+| 业务树键 `rowField` | `code: "P001"` | 产品编码等有业务含义且被父字段引用的值 | 默认保留 |
+| 技术树键 `rowField` | `nodeKey: "N001"` | 仅用于前端或后端挂树，无业务含义 | 可重新生成 |
+| 父键 `parentField` | `parentCode: "P001"` | 引用父节点的 `rowField` 值 | 随树键策略同步 |
+| VXE 行键 `_X_ROW_KEY` | 内部值 | 当前表格实例定位 | 不提交、不主动重建 |
+| 前端临时树键标记 | `_X_TREE_TEMP_KEY` | 精确标识哪个 `rowField` 值是前端临时值 | 不提交 |
+
+从本方案开始，代码和文档中不再把 `rowField` 命名为 `idField`。两者名称混用正是
+“产品编码被当作物理 ID 重新生成”的根因之一。
+
+### 2.1 产品编码场景
+
+配置如下：
+
+```js
+treeConfig: {
+  rowField: "code",
+  parentField: "parentCode",
+  children: "children",
+  transform: true,
+}
+```
+
+原节点：
+
+```js
+{ id: 100, code: "P001", parentCode: null }
+```
+
+复制后的正确结果是：
+
+```js
+{ id: null, code: "P001", parentCode: null }
+```
+
+即：清空物理 `id`，保留产品编码 `code`。禁止把 `code` 改成 `row_*`。
+
+### 2.2 使用业务键作为 rowField 的前置条件
+
+`rowField` 在一张树表的有效数据范围内必须唯一、非空且稳定。如果产品编码允许重复、
+尚未确定，或者编辑过程中可能频繁变化，就不适合直接作为 `rowField`，应新增独立的
+技术树键，例如：
+
+```js
+treeConfig: {
+  rowField: "f_tree_key",
+  parentField: "f_parent_key",
+}
+```
+
+产品编码继续保存在 `code`，不再承担树关系身份。
+
+### 2.3 字面量 id 的兼容边界
+
+现有通用表单清洗和请求层会把字面量字段 `id` 中的 `row_*` 识别为临时物理 ID。
+本次不修改该跨项目约定，因此 xform 树表强制：
+
+```js
+rowField === "id"  =>  physicalIdField === "id"
+```
+
+禁止把字面量 `id` 配成另一个业务键，同时把物理 ID 指向其他字段。若业务编码可能是
+`row_001`，字段必须命名为 `code` 等非 `id` 名称。配置校验发现该不安全组合时应中止
+初始化，而不是期待树表清洗器绕过请求层的二次处理。
+
+## 3. 最终配置契约
+
+### 3.1 treeConfig 是树结构唯一事实源
+
+系统默认、宿主 `dataTableOption.config.treeConfig` 和表单脚本
+`tableConfig.config.treeConfig` 合并后，只生成一次 `resolvedTreeConfig`：
+
+```js
+{
+  rowField,
+  parentField,
+  children,
+  mapChildren,
+  hasChild,
+  lazy,
+  transform,
+}
+```
+
+初始化前的数据规范化使用 `resolvedTreeConfig`；同一配置随后写入
+`tableOption.config.treeConfig` 创建 VXE。表格挂载后再校验
+`$grid.treeConfig` 与 `resolvedTreeConfig` 的关键字段完全一致。
+
+因此，唯一事实源是“合并完成的 `resolvedTreeConfig`”，不是尚未创建的 `$grid`。
+挂载后的新增、复制、展开、排序和提交可读取 `$grid.treeConfig`，但不得再次自行合并
+或推导另一套字段。
+
+禁止在新增、复制、展开、排序或提交逻辑中写死 `id`、`f_parent`、
+`f_children`。
+
+xform 基础配置必须显式声明：
+
+```js
+mapChildren: "_X_ROW_CHILD"
+```
+
+不能只依赖 VXE 全局 `treeOpts` 的隐式默认值。配置合并完成后，
+`resolveTreeFields(resolvedTreeConfig)` 读取最终有效配置，并同时覆盖默认和自定义
+`mapChildren` 场景。
+
+### 3.2 新增 xform 专用身份、复制与提交配置
+
+```js
+treeIdentityConfig: {
+  physicalIdField: "id",
+  // 保持现有 xform 新增根节点协议
+  rootParentValue: 0,
+  // 未配置时仅在 rowField === physicalIdField 时视为 true
+  serverGeneratesRowField: undefined,
+  persistedRowFieldChangeStrategy: "reject",
+  changePersistedRowField: null,
+  validateExternalParentKey: null,
+},
+
+treeCopyConfig: {
+  // 未配置时按 rowField 与 physicalIdField 的关系自动推导
+  rowFieldStrategy: undefined,
+  orphanParentStrategy: "detach",
+  lazyStrategy: "reject",
+  generateRowField: null,
+},
+
+treeSubmitConfig: {
+  orphanParentStrategy: "preserve",
+  unloadedChildrenStrategy: "reject",
+  successReconcileStrategy: "reload",
+},
+```
+
+字段含义：
+
+| 字段 | 可选值 | 含义 |
+|---|---|---|
+| `treeIdentityConfig.physicalIdField` | 字段名 | 数据库物理 ID，默认 `id`；供复制、持久化判断和提交清洗共同使用 |
+| `treeIdentityConfig.rootParentValue` | `null` / `0` / `"0"` 等 | 新增、复制脱离和规范提交时统一写出的根父值；默认 `0`，保持现有 xform 协议 |
+| `treeIdentityConfig.serverGeneratesRowField` | `true` / `false` | 临时树键提交时能否清空并由服务端生成；默认仅在 `rowField === physicalIdField` 时为 `true` |
+| `treeIdentityConfig.persistedRowFieldChangeStrategy` | `reject` / `transactional` | 已持久化业务树键能否修改；默认禁止 |
+| `treeIdentityConfig.changePersistedRowField` | 函数 | `transactional` 时必填，由后端事务更新父节点键及全部子引用 |
+| `treeIdentityConfig.validateExternalParentKey` | 函数 | 可选；确认不在当前节点集合中的父键是正式外部键 |
+| `treeCopyConfig.rowFieldStrategy` | `preserve` / `regenerate` / `custom` | 复制时如何处理树关系键；未配置时自动推导 |
+| `treeCopyConfig.orphanParentStrategy` | `detach` / `preserve` | 复制范围不包含原父节点时，转为根或保留外部父引用 |
+| `treeCopyConfig.lazyStrategy` | `reject` / `loadAll` | 复制范围含未加载后代时拒绝，或先递归加载完整子树 |
+| `treeCopyConfig.generateRowField` | 函数 | `custom` 必填；`regenerate` 可用它生成正式键 |
+| `treeSubmitConfig.orphanParentStrategy` | `preserve` / `reject` | 正常提交遇到集合外父引用时保留或阻止提交 |
+| `treeSubmitConfig.unloadedChildrenStrategy` | `reject` / `loadAll` / `omit` | 未加载后代的提交策略；`omit` 仅在后端明确支持部分树语义时启用 |
+| `treeSubmitConfig.successReconcileStrategy` | `reload` | 服务端生成任一物理/树身份后恢复编辑态；本次落地只支持强制重新加载 |
+
+默认策略按字段语义推导：
+
+```js
+const strategy =
+  configuredStrategy ??
+  (rowField === physicalIdField ? "regenerate" : "preserve");
+```
+
+因此：
+
+- 默认 `rowField: "id"` 时，复制节点会先快照旧键，再生成新的临时树键；
+- `rowField: "code"`、`physicalIdField: "id"` 时，复制节点保留 `code`，
+  只清空 `id`；
+- 业务确有特殊规则时，显式使用 `custom`，不通过字段名前缀猜测。
+
+当 `rowField === physicalIdField` 时增加不可绕过的配置守卫：
+
+- 禁止显式 `preserve`，否则会把旧物理 ID 清空后又原样写回；
+- 本次落地只允许生成带 `_X_TREE_TEMP_KEY` 的新临时键，并要求
+  `serverGeneratesRowField: true`；
+- 暂不允许生成无临时标记的客户端永久主键，因为现有持久化判断按
+  `physicalIdField` 是否有值执行，会把复制行误判为已落库；
+- 如果未来要支持客户端生成永久物理主键，必须另行引入独立新行状态或
+  `isPersistedRow` 回调，不能仅扩展生成器。
+
+`custom` 以及带生成器的 `regenerate` 回调建议签名：
+
+```js
+generateRowField({
+  node,
+  oldValue,
+  parentNode,
+  oldParentKey,
+  newParentKey,
+  parentCopy,
+  fields,
+  makeTempKey,
+})
+```
+
+`parentNode` 指原父节点，`parentCopy` 指已经生成的新父副本；根节点的
+`newParentKey` 为 `rootParentValue`，复制范围外父节点按 orphan 策略得到正式外部键
+或根值。
+
+回调返回：
+
+```js
+{ value: "new-value", temporary: false }
+```
+
+也可直接返回原始值；原始值默认视为正式值。返回临时值时必须显式设置
+`temporary: true`。`regenerate` 未提供生成器时才使用默认 `row_*` 临时键。
+当 `serverGeneratesRowField: false` 时，提交前仍为临时键必须阻止提交；
+`regenerate` 必须通过生成器返回永久值。
+
+`generateRowField` 必须是同步函数，返回 Promise 视为配置错误。需要后端号段时，
+复制 UI 先 `await resolveGeneratedRowFields()` 批量取得号段，再把预取 Map 或同步
+allocator 传给纯函数 `copyTreeData()`；网络请求不能藏进同步生成器。
+
+`validateExternalParentKey` 同样只允许同步返回严格 boolean。需要远程确认时，UI 在
+复制/提交 preflight 阶段先批量 `await` 校验并填充 `knownFormalKeyRegistry`；
+纯函数收到 Promise 必须报配置错误，不能把 truthy Promise 当成校验通过。
+
+配置优先级：
+
+```text
+系统默认
+  < 宿主 dataTableOption.treeIdentityConfig / treeCopyConfig / treeSubmitConfig
+  < 表单脚本 tableConfig.treeIdentityConfig / treeCopyConfig / treeSubmitConfig
+```
+
+三项配置都是 xform 业务配置，不塞入 VXE 的 `config.treeConfig`。
+
+## 4. 根节点、类型和 transform 约束
+
+### 4.1 根父值
+
+统一根父值口径：
+
+```js
+null
+undefined
+""
+0
+"0"
+```
+
+因此，真实 `rowField` 值不得使用 `0`、`"0"` 或空值；否则无法同时表达
+“真实节点键”和“根节点哨兵”。
+
+上面五种值是读取兼容口径；新增、复制脱离以及规范提交统一写
+`treeIdentityConfig.rootParentValue`。配置为 `0` 或 `"0"` 的旧接口可保持原协议，
+但同一张表内不得混用多个根输出值。
+
+配置合并时必须满足：
+
+```js
+isRootParent(rootParentValue) === true
+```
+
+`-1`、`"ROOT"` 等读取口径无法识别的值应中止初始化，不能写出后再被下一轮当作孤儿。
+
+### 4.2 类型归一
+
+VXE/xe-utils 的部分建树路径使用严格比较，仅在提交时 `String()` 比较并不能修复
+显示阶段的 number/string 分叉。数据进入 VXE 前应执行一次关系归一：
+
+1. 以 `normalizeTreeKey(value)` 建立规范键索引；
+2. `1` 与 `"1"` 视为同一关系键，若两者同时作为 `rowField` 出现则判为冲突；
+3. 当 `parentField: "1"` 唯一匹配到 `rowField: 1` 时，把父字段规范为实际父键值
+   `1`，使值和类型完全一致；
+4. 找不到父节点的真实外部父键保留原值；
+5. 归一只能在数据装载、插入或显式键变更时执行，不能只在提交出口补救。
+
+### 4.3 入表前统一为规范平铺模型
+
+`transform: true` 接收的事实源必须是规范平铺数组。初始加载、`setValue`、复制插入和
+懒加载返回值进入 VXE 前统一执行：
+
+1. 遍历平铺、`children`、`mapChildren` 的每一次节点 occurrence；每次先记录
+   `(容器父节点, 当前节点)` 嵌套边，再判断节点是否已经见过；
+2. `WeakSet` 只阻止同一对象的 payload 重复收集和子树重复递归，不能删除第二个
+   容器产生的 occurrence 边；因此同一对象挂在两个父节点下或挂到自身 children
+   仍会被后续图校验发现；
+3. 规范化 `rowField` 是唯一主身份，缺失、根哨兵或重复都按树契约处理，不能用
+   其他字段替代；
+4. `_X_ROW_KEY` 和已持久化物理 ID 只建立独立的交叉校验索引：任一辅助标识同时
+   指向两个不同 `rowField`，或同一 `rowField` 的多实例携带冲突物理 ID，立即失败；
+5. 同一规范 `rowField` 出现多个对象实例时，以 `fullData`/显式平铺对象为优先来源；
+   除 children 容器外的业务字段不一致则直接报冲突，不能静默覆盖；
+6. 规范化后的 `parentField` 是父子关系权威；
+7. 嵌套边只用于补全“没有 `parentField` 属性”的 nested-only 节点；
+8. 节点显式父键与嵌套位置冲突、同一节点存在多个父节点、自指或形成有向环时，
+   中止装载并给出节点键；
+9. 补齐父键、统一值类型后移除旧 children 容器，输出唯一平铺数组；
+10. 原始入参不修改，规范数组作为后续 VXE 模型。
+
+不能把嵌套原数据直接交给 VXE transform 后再补救，因为建树过程可能覆盖原
+`children` 并导致尚未平铺的后代丢失。
+
+### 4.4 transform
+
+xform 树表当前所有提交与编辑语义都建立在 `transform: true` 上，因此它是强约束，
+不是可选能力：
+
+- 默认配置显式写入 `transform: true`；
+- 宿主配置和表单脚本合并完成后再次校验；
+- 发现 `false` 时记录明确错误并强制恢复为 `true`，避免平铺子节点提交丢失；
+- `rowField`、`parentField`、`children`、`mapChildren`、`hasChild` 必须存在且互不相同；
+- `physicalIdField` 仅允许与 `rowField` 相同，不得等于父键、children 容器、
+  `hasChild` 或 `_X_TREE_TEMP_KEY` 等内部保留字段；
+- 任一业务字段不得使用 `_X_ROW_KEY`、`_X_ROW_CHILD`、`_X_TREE_TEMP_KEY`
+  等内部保留名；
+- 字段缺失或碰撞时中止树表初始化并给出所有冲突字段。
+
+## 5. 公共树工具
+
+新增：
+
+```text
+src/components/xform/utils/treeTableUtil.js
+```
+
+该文件只承载无 UI、可单测的纯函数：
+
+```js
+resolveTreeFields(treeConfig)
+resolveTreeIdentityConfig(context)
+resolveTreeCopyConfig(context)
+resolveTreeSubmitConfig(context)
+isRootParent(value)
+normalizeTreeKey(value)
+treeKeyEquals(left, right)
+getTreeNodeIdentity(row, context)
+normalizeTreeRelations(rows, fields)
+collectTreeNodes(sources, fields)
+validateTreeGraph(nodes, edges, context)
+canonicalizeTreeInput(sources, context)
+getTreeLoadState(row, context)
+syncTreeKeyReferences(rows, oldValue, newValue, fields)
+copyTreeData(source, fields, copyConfig)
+sanitizeTreeRow(row, context)
+buildTreeSubmitData(sources, context)
+```
+
+上述工具全部保持同步、无网络副作用。`loadAll` 的递归请求由组件编排层负责，不放进
+`buildTreeSubmitData()`、`copyTreeData()` 或 `getSubData2()`。
+
+`resolveTreeFields()` 返回：
+
+```js
+{
+  rowField,
+  parentField,
+  childrenField,
+  mapChildrenField,
+  hasChildField,
+  lazy,
+}
+```
+
+这里明确使用 `rowField`，不再返回有歧义的 `idField`。
+
+## 6. 临时树键协议
+
+### 6.1 生成
+
+新增节点缺少正式 `rowField` 时：
+
+```js
+const tempKey = `row_${uniqueValue}`;
+row[rowField] = tempKey;
+row._X_TREE_TEMP_KEY = tempKey;
+```
+
+每张树表同时维护不进入表单数据的 `temporaryKeyRegistry`。所有新临时键先注册再使用；
+正式值回填或行删除后注销。服务端装载数据中的正式树键/外部父键记录在
+`knownFormalKeyRegistry`，供孤儿父键校验使用。
+
+判断临时值必须同时满足：
+
+```js
+row[rowField] === row._X_TREE_TEMP_KEY
+```
+
+不能再把“字符串以 `row_` 开头”作为通用判断，因为合法产品编码也可能叫
+`row_001`。
+
+### 6.2 正式值回填
+
+当产品选择器或父节点保存响应把临时键替换为正式值时：
+
+1. 校验新值不为空、不属于根哨兵，并在当前树中唯一；
+2. 找出所有 `parentField` 指向旧临时键的直接子节点；
+3. 把这些父引用同步改成新业务键；
+4. 删除 `_X_TREE_TEMP_KEY`；
+5. 刷新 VXE 树关系，但保留现有 `_X_ROW_KEY` 和当前编辑/展开状态。
+
+如果新值冲突，拒绝本次替换并给出业务提示，不能偷偷生成另一个编码。
+当 `rowField === physicalIdField` 时，父节点保存成功后必须先从响应读取正式物理 ID，
+完成“旧临时键 -> 新 ID”的整表引用同步，再允许保存其子节点。
+
+### 6.3 兼容旧数据
+
+历史代码可能只写入了 `row_*`，没有 `_X_TREE_TEMP_KEY`。兼容规则仅允许：
+
+- `rowField === physicalIdField === "id"` 时，旧 `id` 的 `row_*` 前缀可作为一次性
+  兼容清洗；
+- 自定义 `rowField` 不使用前缀兜底，防止清掉合法业务值；
+- 新代码生成的临时树键必须带显式标记。
+
+## 7. 新增与编辑流程
+
+### 7.1 新增根节点
+
+1. 解析最终 `treeConfig`；
+2. 创建表单默认行；
+3. 若业务已经提供合法 `rowField`，直接使用且不加临时标记；
+4. 否则生成带 `_X_TREE_TEMP_KEY` 的临时树键；
+5. `parentField` 写 `treeIdentityConfig.rootParentValue`；
+6. 插入 VXE 后恢复激活行。
+
+### 7.2 新增子节点
+
+除上述步骤外：
+
+```js
+child[parentField] = parent[rowField];
+```
+
+父节点的 `rowField` 为空、冲突或尚未完成归一时禁止新增子节点。
+
+### 7.3 编辑 rowField
+
+`rowField` 改动不是普通单元格赋值，必须走统一入口：
+
+```js
+changeTreeRowField(row, newValue)
+```
+
+该入口负责唯一性校验、子节点父引用同步、临时标记清除以及树状态刷新。
+
+可编辑边界：
+
+- 新增、尚未持久化的行：允许把临时键替换为正式业务键，并同步当前子节点；
+- `rowField === physicalIdField` 且行已持久化：物理主键不可编辑，直接拒绝；
+- `rowField !== physicalIdField` 且行已持久化：默认
+  `persistedRowFieldChangeStrategy: "reject"`，不能只保存父行；
+- 业务必须修改已持久化树键时，只能使用 `transactional`：
+  `changePersistedRowField` 由后端在一个事务中更新父节点树键及所有直接子节点
+  `parentField`，包括前端尚未懒加载的子节点；接口成功后前端再同步已加载行并刷新树；
+- 事务失败时保留旧键和旧父引用，不能出现父行已更新、子行仍指旧键的半成功状态。
+
+普通单行保存接口不得承担已持久化树键变更。
+
+## 8. 复制流程
+
+复制分两遍完成，禁止边递归边改父键。
+
+### 8.1 收集节点
+
+`collectTreeNodes()` 同时接受：
+
+- VXE `fullData`（transform 下通常是树根数组，需要递归收集）；
+- `childrenField` 嵌套节点；
+- `mapChildrenField` 懒加载/映射节点。
+
+复制前先结合 `hasChildField` 和 VXE 懒加载状态判断完整性：
+
+- `lazy: false` 时当前规范快照视为完整，不根据 `hasChildField` 推断缺失；
+- `lazy: true` 时只认 `isTreeNodeLoaded(row)` 的状态，不用 children 长度猜测；
+- 节点声明有子项但尚未加载时，默认 `lazyStrategy: "reject"`，整次复制不执行；
+- `lazyStrategy: "loadAll"` 时，先递归等待所有目标后代加载完成，再从统一快照复制；
+- 缺少 loader 或任一加载失败时按 `reject` 处理；
+- 不提供“悄悄复制当前可见部分”的默认行为，避免生成残树。
+
+去重分两层：
+
+1. 每次访问节点先记录 occurrence 父边；`WeakSet` 只去除同一对象的重复 payload
+   和重复递归，不去除第二个容器父边；
+2. 以规范化 `rowField` 为逻辑主身份合并不同对象实例；`_X_ROW_KEY` 和已持久化
+   物理 ID 只做交叉一致性校验，不作为复合键，也不覆盖 `rowField` 唯一约束。
+
+多实例的业务字段一致时只保留权威平铺实例；内容冲突、同键不同物理 ID 或同一节点
+出现多个父边时终止复制，不能任选一份数据。
+
+收集结束后先完成父边冲突、自指和环校验，再生成父节点优先的拓扑顺序。生成器不得
+按原数组偶然顺序执行。
+
+### 8.2 第一遍：生成节点映射
+
+在清空任何字段之前，先对全部原节点建立不可变快照：
+
+```js
+{
+  oldRowKey: node[rowField],
+  oldParentKey: node[parentField],
+  oldPhysicalId: node[physicalIdField],
+}
+```
+
+然后按父到子的拓扑顺序对每个快照创建副本。调用子节点生成器前，内部父节点的
+`newRowKey` 和 `parentCopy` 必须已经存在：
+
+1. 先按快照和 orphan 策略确定 `resolvedNewParentKey`：根节点使用
+   `rootParentValue`，内部父节点读取已建立的映射，外部父节点完成正式性校验或转根；
+2. 把 `resolvedNewParentKey` 作为 `newParentKey`，基于 `oldRowKey`
+   按 `rowFieldStrategy` 计算
+   `{ value: newRowKey, temporary }`；
+3. 清空 `physicalIdField`；
+4. 删除源节点带来的 `_X_ROW_KEY`、`_X_ROW_CHILD`、旧 `_X_TREE_TEMP_KEY`
+   等内部字段；
+5. 把 `newRowKey` 写回副本的 `rowField`；当两字段相同时，该步骤必须发生在
+   清空物理 ID 之后；
+6. 当 `temporary: true` 时显式写
+   `copy._X_TREE_TEMP_KEY = newRowKey`；正式值保持无标记；
+7. 清空创建人、创建时间、更新人、更新时间等复制态字段；
+8. 建立 `oldRowKey -> newRowKey` 映射，并把 `resolvedNewParentKey` 存入副本上下文。
+
+所有父引用重映射只能读取快照，不能读取已经清洗的副本。该顺序专门保证默认
+`rowField === physicalIdField === "id"` 的多层树不会断链。
+
+第一遍结束后必须校验所有 `newRowKey` 在复制集合内唯一；复制插入现有表时还要与
+目标表当前全部 `rowField` 做全局唯一性校验。生成器发生碰撞时整次复制失败，不能
+覆盖映射或只保留其中一个节点。
+
+策略行为：
+
+| 策略 | rowField 处理 | 典型场景 |
+|---|---|---|
+| `preserve` | 保留原值，不加临时标记 | 产品编码、组织编码等业务键 |
+| `regenerate` | 默认生成带标记的 `row_*`；配置生成器时也可产生永久键 | 纯技术树键或 `rowField === physicalIdField` |
+| `custom` | 使用业务回调结果 | 后端号段、组合键等特殊规则 |
+
+`preserve` 只接受已经确认的正式源树键。若源节点满足
+`node[rowField] === node._X_TREE_TEMP_KEY`，或源键命中 `temporaryKeyRegistry`，
+复制必须失败并提示先完成业务选择/保存；也可以由调用方明确改用
+`regenerate`/`custom` 生成新键。不得删除源 marker 后把原临时值当作正式键。
+
+如果是“同一张表内复制子树”，`preserve` 导致键冲突时必须拒绝插入并提示；
+不能为绕过冲突而静默改变产品编码。
+
+### 8.3 第二遍：重建父引用
+
+第一遍已经在调用生成器前得到 `resolvedNewParentKey`。第二遍只把它写入副本
+`parentField` 并做整体验证；第一遍的决策规则如下：
+
+1. 原父节点也在复制集合中：使用映射后的新父键；
+2. 原父节点不在复制集合中且策略为 `detach`：改为
+   `treeIdentityConfig.rootParentValue`；
+3. 原父节点不在复制集合中且策略为 `preserve`：仅当父键在
+   `knownFormalKeyRegistry` 中，或 `validateExternalParentKey` 明确通过时保留；
+4. 外部父键命中 `temporaryKeyRegistry` 时拒绝复制并要求把父节点纳入复制范围或
+   先保存父节点；未知来源的父键默认拒绝，不能按 `row_` 前缀猜测；
+5. 第二遍写入全部已解析父键，校验新父边无冲突、无自指、无环；
+6. `copyTreeData()` 返回移除了旧 children 容器的规范平铺数组，直接交给
+   `transform: true` 的 VXE；只有提交出口才重建嵌套 `childrenField`。
+
+### 8.4 产品编码复制示例
+
+原数据：
+
+```js
+[
+  { id: 100, code: "P001", parentCode: null },
+  { id: 101, code: "P002", parentCode: "P001" },
+]
+```
+
+采用：
+
+```js
+treeIdentityConfig: {
+  physicalIdField: "id",
+  rootParentValue: null,
+},
+treeCopyConfig: {
+  rowFieldStrategy: "preserve",
+}
+```
+
+复制结果：
+
+```js
+[
+  { id: null, code: "P001", parentCode: null },
+  { id: null, code: "P002", parentCode: "P001" },
+]
+```
+
+产品编码和父子引用均保持业务含义，只有物理 ID 被清空。
+
+### 8.5 技术树键复制示例
+
+原数据：
+
+```js
+[
+  { id: 100, nodeKey: "N001", parentKey: null },
+  { id: 101, nodeKey: "N002", parentKey: "N001" },
+]
+```
+
+该例明确约定服务端生成并回填技术树键：
+
+```js
+treeIdentityConfig: {
+  physicalIdField: "id",
+  serverGeneratesRowField: true,
+},
+treeCopyConfig: {
+  rowFieldStrategy: "regenerate",
+}
+```
+
+复制后的编辑态：
+
+```js
+[
+  {
+    id: null,
+    nodeKey: "row_a",
+    parentKey: null,
+    _X_TREE_TEMP_KEY: "row_a",
+  },
+  {
+    id: null,
+    nodeKey: "row_b",
+    parentKey: "row_a",
+    _X_TREE_TEMP_KEY: "row_b",
+  },
+]
+```
+
+这里重新生成是合理的，因为 `nodeKey` 是技术身份，不是产品编码。
+
+`regenerate` 生成的是前端临时键，提交时会被清空。只有后端能够根据嵌套结构生成
+正式树键并恢复父子关系时才能使用默认生成器；如果后端要求前端提交正式树键，
+必须为 `regenerate` 配置永久键生成器，或使用 `custom` 返回
+`temporary: false` 的永久值。
+
+### 8.6 默认 id 树复制示例
+
+原数据：
+
+```js
+[
+  { id: 100, f_parent: null },
+  { id: 101, f_parent: 100 },
+]
+```
+
+第一遍先快照 `100 -> null`、`101 -> 100`，再生成副本：
+
+```js
+[
+  {
+    id: "row_a",
+    f_parent: null,
+    _X_TREE_TEMP_KEY: "row_a",
+  },
+  {
+    id: "row_b",
+    f_parent: "row_a",
+    _X_TREE_TEMP_KEY: "row_b",
+  },
+]
+```
+
+第二遍父映射读取的是旧快照中的 `100`，不是已经改写的副本。最终提交时两个临时
+`id` 被清空，子节点通过嵌套结构表达其父子关系。
+
+## 9. 整表提交组装
+
+整表提交统一调用：
+
+```js
+buildTreeSubmitData(sources, context)
+```
+
+不得依赖 VXE 当前是否恰好已生成 `children` 的副作用。算法顺序固定如下：
+
+1. 读取每个 `hasChildField` 节点的懒加载状态，并先执行未加载策略；
+2. 从平铺、`childrenField`、`mapChildrenField` 遍历当前允许提交的所有 occurrence，
+   每次先记录容器父边；
+3. 再按对象引用和规范化 `rowField` 去重节点 payload，保留全部 occurrence 边；
+4. 以规范化 `parentField` 为权威；嵌套边只补全没有父字段的 nested-only 节点；
+5. 校验 `rowField` 唯一性、根哨兵冲突、多父、自指和有向环；
+6. 若仍有临时 `rowField` 且 `serverGeneratesRowField: false`，在清洗前阻止提交；
+7. 在清理临时值之前，根据原始树键快照父子拓扑；
+8. 克隆节点，后续操作只处理副本；
+9. 删除副本上的旧 `childrenField` 和 `mapChildrenField`；
+10. 按已验证的父边重建唯一 `childrenField`；
+11. 根节点父值规范为 `treeIdentityConfig.rootParentValue`；
+12. 递归执行 `sanitizeTreeRow()`；
+13. 返回顶层提交数组。
+
+### 9.1 懒加载完整性
+
+“未加载”不等于“已加载且为空”：
+
+- `lazy: false`：当前规范快照视为完整，`hasChildField: true` 只作为业务元数据，
+  不触发未加载判断；
+- `lazy: true`：通过 VXE 已加载状态读取适配器 `isTreeNodeLoaded(row)` 判断，
+  不能根据 `children.length === 0` 猜测；
+- `unloadedChildrenStrategy: "reject"`：默认行为，存在未加载后代时阻止整表提交；
+- `loadAll`：递归加载并等待完成，再重新取得一致性快照；
+- `omit`：仅在后端明确约定“缺少 `childrenField` 表示该子树未参与本次更新”时使用；
+  未加载节点必须省略 children 字段，不能写 `children: []`；
+- 已加载且确实为空的节点可以输出 `children: []`，表示已知空集合。
+
+`hasChildField` 不能只被解析却不参与算法。复制只允许 `reject` 或 `loadAll`，
+整表提交的 `omit` 必须经过接口联调确认，防止被后端解释为删除全部后代。
+运行时上下文必须同时提供 `isTreeNodeLoaded` 和 `loadTreeChildren` 适配器；
+`loadAll` 缺少 loader、任一请求失败或加载后状态仍不完整时统一按 `reject` 结束，
+不生成部分提交体。
+
+异步边界固定如下：
+
+```text
+保存/提交 UI 动作
+  -> await ensureAllTreeChildrenLoaded（仅 loadAll）
+  -> 重新读取 VXE 最新一致性快照
+  -> 同步 buildSubmitPayload / buildTreeSubmitData
+  -> 发请求
+```
+
+复制 UI 动作同样先 `await`，再同步调用 `copyTreeData()`。现有
+`getSubData2()`/`getRealFormData()` 保持同步且非阻断：普通字段脚本、确认文案等
+读取时只返回当前已加载数据，不触发网络，也不因树不完整而抛错。严格的完整性校验
+只放在新增的显式提交序列化入口 `buildSubmitPayload()` 中；保存动作必须使用该入口，
+该入口以显式 `mode: "submit"` 调用同步的 `getSubData2()` 和
+`buildTreeSubmitData()`。默认读取模式不执行提交完整性拒绝。不能再把普通
+`getRealFormData()` 的当前快照直接当作完整提交体，也禁止把 Promise 塞进现有
+同步取值链。
+
+### 9.2 根和孤儿节点
+
+- `parentField` 为任一读取兼容根值：顶层节点，并规范输出为 `rootParentValue`；
+- 父键能匹配本次节点集合：挂到匹配父节点下；
+- 父键非空但父节点不在本次集合：
+  - 命中 `temporaryKeyRegistry`，或能在全表上下文找到仍带临时标记的父节点时，
+    拒绝提交并要求包含/先保存父节点；
+  - `treeSubmitConfig.orphanParentStrategy: "preserve"` 仅在父键来自
+    `knownFormalKeyRegistry`，或 `validateExternalParentKey` 明确通过时，才作为
+    顶层输出并保留外部父键；
+  - 来源未知且无法确认正式性的父键默认拒绝；
+  - `reject` 时阻止提交并报告节点；
+- `treeCopyConfig.orphanParentStrategy` 只控制复制范围之外的父引用，不改变正常
+  整表提交的孤儿规则；
+- 如果后端不支持“顶层携带外部父键”，应先明确并调整接口契约，不能在提交端静默
+  清空父键或丢弃节点。
+
+### 9.3 递归清洗规则
+
+每个节点都执行，而不是只处理顶层：
+
+1. `physicalIdField`：
+   - 普通编辑的真实物理 ID 保留；
+   - 复制态的原物理 ID 已在复制阶段清空；
+   - 当该字段同时也是带标记的临时 `rowField` 时，编辑态可持有新 `row_*`，
+     提交清洗时再置空；
+2. `rowField`：
+   - 值与 `_X_TREE_TEMP_KEY` 相等且 `serverGeneratesRowField: true` 时清空；
+   - 值仍为临时键但服务端不负责生成时，必须在清洗前报错，不能提交 `null`；
+   - 产品编码等正式值保留；
+   - 默认 `id` 兼容历史 `row_*` 前缀；
+3. `parentField`：
+   - 指向本次新增父节点临时键时，在嵌套关系已经表达父子关系后清空；
+   - 指向本次集合外、已经确认正式的父节点时保留；
+4. 删除 `_X_ROW_KEY`、`_X_ROW_CHILD`、`_X_TREE_TEMP_KEY` 及其他 VXE 内部字段；
+5. 删除 `mapChildrenField`；
+6. 仅保留重建后的 `childrenField`，并继续递归清洗。
+
+同一业务节点在最终 JSON 中只能出现一次。
+
+### 9.4 提交成功后的身份回填
+
+提交清洗只作用于请求副本，表格原对象仍保留临时键。只要本次请求存在
+`physicalIdField` 为空/临时的新节点，或存在需要服务端生成/改变 `rowField` 的节点，
+接口成功后必须强制重新查询表格/表单，以服务端正式
+`physicalIdField`、`rowField`、`parentField` 替换整个编辑态。重新加载完成前不开放
+下一次保存或子行编辑；reload 失败时保留当前临时编辑态、提示用户重试，不能把本次
+保存标记为完整结束。
+
+本次落地不支持仅靠响应数组顺序或业务字段猜测逐节点映射。自定义保存成功回调也不得
+跳过 reload；否则再次保存会重复新增，子行会继续被判定为未持久化。未来若要支持
+无 reload 回填，必须另行设计后端可回显的专用 client token 协议，不能复用已在请求
+副本中清空的临时 `rowField`。
+
+## 10. 单行保存
+
+单行保存不能继续只调用仅认识字面量 `id` 的通用清洗器。统一流程为：
+
+```text
+检查父节点是否已经持久化
+  -> 校验当前 rowField 是否可提交
+  -> 克隆当前行及必要上下文
+  -> 同步树键引用
+  -> sanitizeTreeRow(mode: "single")
+  -> commonDataUtil.handleForm
+  -> 发起请求
+  -> 合并服务端正式身份并同步所有直接子节点引用
+```
+
+默认采用“父节点先保存”策略：
+
+- `mode: "single"` 的请求对象必须删除 `childrenField` 和 `mapChildrenField`，
+  只序列化当前行；完整表格上下文仅用于关系校验和成功后的引用同步，不能把父行下的
+  未保存子节点一起发到单行接口；
+- 当前行是子节点，且其父节点的 `physicalIdField` 为空或仍为临时状态时，禁止单独
+  保存子节点，并提示先保存父节点；
+- 父对象不在当前单行上下文时，同样先校验父键来源：命中
+  `temporaryKeyRegistry` 时拒绝；只有 `knownFormalKeyRegistry` 或
+  `validateExternalParentKey` 确认后才保留；来源未知默认拒绝；
+- 不能清空临时 `parentField` 后把子节点当根保存，也不能把 `row_*` 发给后端；
+- 父节点保存成功后，无论 `rowField` 与物理 ID 是否为同一字段，只要服务端返回的
+  正式 `rowField` 与旧临时键不同，都必须调用 `syncTreeKeyReferences()` 更新所有
+  直接子节点；
+- 配置 `serverGeneratesRowField: true` 时，保存响应必须返回正式 `rowField`；
+  缺失时视为保存协议错误，不能清除本地临时标记；
+- 自定义业务 `rowField` 仍是临时值且服务端不生成时，保存前阻止并提示完成业务选择；
+- `rowField === "id"` 时已由配置约束保证 `physicalIdField === "id"`，因此后续
+  `commonDataUtil.handleForm` 和请求层对临时 `id` 的处理不会误伤独立业务编码；
+- 原始行不因请求清洗而丢失编辑态数据；
+- 单行保存与整表提交对同一节点使用同一字段清洗规则。
+
+若某个后端确实支持“子行携带未保存父行一起级联保存”，应另建显式批量接口适配，
+不复用单行保存路径。
+
+整表提交使用 `mode: "tree"`，只有该模式才重建并递归保留 `childrenField`。
+
+## 11. 展开、排序、删除和持久化判断
+
+以下链路必须复用 `resolveTreeFields()`、`isRootParent()` 和
+`treeKeyEquals()`：
+
+- 首次自动展开和 `expandAll`；
+- 懒加载参数组装；
+- 上移、下移、同级排序；
+- 删除父节点及收集后代；
+- 按树键定位和激活行；
+- `hasSaveRow`、`hasEditingRow` 等状态判断。
+
+不得使用：
+
+```js
+!row[parentField]
+ids.includes(row[rowField])
+row.id
+```
+
+来替代统一口径。
+
+`tableTreeMixins` 实际被 xform 编辑树表直接混入，不能再视为独立、不相关模块。
+其中的持久化判断应读取显式 `physicalIdField`；其他写死 `id` 的方法若不属于 xform
+调用路径，要用调用检索和测试锁定边界，而不是凭目录位置排除。
+
+## 12. 文件级改造清单
+
+### 12.1 新增
+
+`src/components/xform/utils/treeTableUtil.js`
+
+- 放置字段解析、关系归一、复制、递归收集、递归清洗和提交组装纯函数；
+- 不依赖 Vue 组件实例，确保可直接单测。
+
+### 12.2 修改
+
+`src/components/xform/form-render/container-item/data-table-mixin.js`
+
+- 合并并校验最终 `treeConfig`；
+- 读取 `treeIdentityConfig`、`treeCopyConfig`、`treeSubmitConfig`；
+- 初始数据、`setValue`、复制插入和懒加载结果入 VXE 前先规范成唯一平铺模型；
+- 新增/编辑/单行保存统一走树工具；
+- 未保存父节点下的子节点禁止单行保存，父保存响应统一回填树键；
+- 自动展开、排序、懒加载、定位逻辑统一键比较；
+- `mapChildren` 显式默认值和 `transform` 约束落地。
+
+`src/components/xform/form-render/indexMixin.js`
+
+- `handleCopyTreeData` 改为明确区分物理 ID 和 `rowField`；
+- 复制先快照旧键，返回规范平铺副本，不复制/重建旧 children 容器；
+- 新增异步提交编排入口 `buildSubmitPayload()`：先完成 `loadAll`，再同步序列化；
+- `getSubData2` 增加显式 read/submit 上下文；普通读取保持同步非阻断，提交模式调用
+  递归的 `buildTreeSubmitData`；
+- 复制与整表提交不再只处理顶层节点，并执行懒加载完整性策略。
+
+`src/components/xform/mixins/defaultHandle.js`
+
+- 默认保存不能继续在 validate 回调中同步取得 `getReqFormData()` 后直接请求；
+- 保存流程改为 `await buildSubmitPayload()`，取得严格提交快照后再调用接口；
+- 保存成功后按 9.4 的触发条件 `await reload`，完成前不结束保存状态；
+- 自定义保存入口必须遵守同一异步提交与 reload 契约；
+- `getReqFormData()`、`getRealFormData()` 保留为同步只读 API，不承担提交完整性保证。
+
+`src/mixins/tableTree/index.js`
+
+- xform 实际使用的持久化/编辑态判断改为读取 `physicalIdField`；
+- 不在 xform 调用路径中的方法只做边界核实，不顺带扩大重构范围。
+
+### 12.3 明确不修改
+
+`src/resources/js/base/common.js`
+
+这是跨业务通用清洗器，不应让它理解 xform 树表的动态 `rowField` 和临时标记。
+树表专属清洗应在调用通用清洗器之前完成。字面量 `id` 保留为物理 ID 的强约束，
+保证现有通用清洗和请求层的二次临时 ID 处理仍然安全。
+
+## 13. 测试方案
+
+### 13.1 工具函数单测
+
+至少覆盖：
+
+1. 五种根父值；
+2. `0`/`"0"` 作为真实树键时被拒绝；
+3. number/string 父子键归一；
+4. 归一后键冲突；
+5. 平铺数据建树；
+6. 仅 `children` 的嵌套数据；
+7. 仅 `mapChildren` 的懒加载数据；
+8. 同一节点同时出现在两种 children 中只收集一次；
+9. 孤儿节点保留外部父键；
+10. 新增节点临时标记；
+11. 正式键回填并同步子节点；
+12. 合法业务值 `row_001` 不被清理；
+13. 默认 `id` 历史临时值兼容；
+14. 复制时清空物理 ID；
+15. `preserve` 保留产品编码；
+16. `regenerate` 重建技术键和父映射；
+17. `custom` 返回正式值；
+18. `custom` 返回临时值；
+19. 递归清洗所有层级；
+20. 内部字段全部移除；
+21. 默认 `rowField === physicalIdField === "id"` 的三层复制先快照再映射；
+22. 同一对象引用去重；
+23. 不同对象实例、同一稳定身份且内容一致时合并；
+24. 不同对象实例、同一稳定身份但内容冲突时失败；
+25. `parentField` 与嵌套边冲突、多父、自指和多节点环；
+26. 未加载子树与已加载空子树的区别；
+27. 临时业务 `rowField` 且服务端不生成时拒绝提交；
+28. `rootParentValue` 为 `null`、`0`、`"0"` 的规范输出；
+29. 默认与自定义 `mapChildren` 解析；
+30. 复制和提交的孤儿策略互不串用；
+31. `rowField === physicalIdField` 时显式 `preserve` 和永久键生成被拒绝；
+32. 复制生成键在复制集合及目标表中的碰撞；
+33. 同一对象 occurrence 挂在两个父节点下或挂到自身时仍能检出；
+34. `preserve` 遇到源临时树键时拒绝；
+35. 外部父键分别命中临时 registry、正式 registry 和未知来源；
+36. 非法 `rootParentValue` 与所有字段碰撞组合；
+37. 同步生成器返回 Promise 时拒绝；
+38. 外部父键同步校验器返回 Promise 时拒绝；
+39. 父到子拓扑生成中，子组合键正确使用父副本的 `newParentKey`。
+
+### 13.2 组件/集成测试
+
+至少覆盖：
+
+- 宿主 `dataTableOption.config.treeConfig` 局部覆写后字段不丢失；
+- 表单脚本覆写后的最终配置校验；
+- nested-only 输入先规范平铺，再进入真实 VXE，全部后代仍存在；
+- `transform: false` 被拦截并恢复，且节点数量和父子结构正确；
+- 新增根、新增子、编辑树键；
+- 已持久化物理主键编辑被拒绝；
+- 已持久化业务树键不能走普通单行保存；
+- `transactional` 树键变更覆盖后端成功、失败回滚和未加载子节点；
+- 产品选择器把临时键替换为产品编码；
+- 自定义 `rowField` 单行保存；
+- 父行已有 children 时，单行请求体仍只包含当前父行；
+- 新父节点未保存时，子节点单行保存被阻止；
+- 父节点保存响应回填正式树键后，所有直接子节点父引用被同步；
+- 产品编码树复制；
+- 技术键树复制；
+- 默认 `rowField === physicalIdField === "id"` 的多层树复制；
+- 同字段身份配置的非法 `preserve`/永久键策略被拦截；
+- 复制生成器碰撞时整次失败且表格数据不变；
+- 同表复制业务键冲突提示；
+- 未加载子树复制的 `reject` 与 `loadAll`；
+- 未加载节点提交的 `reject`、`loadAll`，以及经联调启用的 `omit`；
+- `lazy: false` 不因 `hasChild: true` 误判未加载；
+- `lazy: true` 只读取 VXE 加载状态，缺少 loader/加载失败不生成部分数据；
+- 远程号段先异步预取、纯复制阶段同步分配；
+- 默认和自定义 `mapChildren`；
+- number/string 数据分别通过初始加载、`setValue`、懒加载进入表格；
+- 每个入口都断言 VXE 根节点数量、每个逻辑节点只出现一次、最终请求体只出现一次；
+- 首次自动展开的 `"0"` 根值；
+- 删除、上下移、排序按统一键工作；
+- 完整提交与单行保存清洗结果一致；
+- 新增/复制节点保存成功后必须等待 reload，reload 失败不得开放下一次保存；
+- 普通 `getRealFormData()` 在懒树未加载时仍同步返回当前快照且不抛提交校验错误；
+- 表格编辑态对象在提交前后深比较不变。
+
+### 13.3 回归测试
+
+- 默认 `rowField: "id"` 的既有树表；
+- 非树普通表新增、编辑、复制、提交；
+- 查询表、分页表、懒加载表；
+- 导出仍使用后端物理 ID，不随 `rowField` 改动；
+- 现有 Jest、ESLint 和构建检查。
+
+## 14. 验收样例
+
+### 14.1 产品编码树复制
+
+输入：
+
+```js
+dataTableOption: {
+  config: {
+    treeConfig: {
+      rowField: "code",
+      parentField: "parentCode",
+      children: "children",
+      mapChildren: "_X_ROW_CHILD",
+      transform: true,
+    },
+  },
+  treeIdentityConfig: {
+    physicalIdField: "id",
+    rootParentValue: null,
+  },
+  treeCopyConfig: {
+    rowFieldStrategy: "preserve",
+  },
+}
+```
+
+最终提交：
+
+```js
+[
+  {
+    id: null,
+    code: "P001",
+    parentCode: null,
+    children: [
+      {
+        id: null,
+        code: "P002",
+        parentCode: "P001",
+      },
+    ],
+  },
+]
+```
+
+验收点：`code` 未改变，原物理 ID 未提交，无 `_X_*` 字段。
+
+### 14.2 技术树键复制
+
+前置配置：
+
+```js
+treeIdentityConfig: {
+  physicalIdField: "id",
+  serverGeneratesRowField: true,
+}
+```
+
+编辑态允许：
+
+```js
+{
+  id: null,
+  nodeKey: "row_a",
+  _X_TREE_TEMP_KEY: "row_a",
+}
+```
+
+提交态：
+
+```js
+{
+  id: null,
+  nodeKey: null,
+}
+```
+
+子节点已经嵌套在父节点下时，其指向 `row_a` 的临时父键也应清空。
+
+### 14.3 新节点选择产品
+
+过程：
+
+```text
+临时 code = row_a
+  -> 用户选择 P001
+  -> code = P001
+  -> 所有直接子节点 parentCode: row_a -> P001
+  -> 删除 _X_TREE_TEMP_KEY
+```
+
+验收点：最终提交保留 `P001`，不会因前缀规则被清掉。
+
+### 14.4 默认 id 树复制
+
+输入父子键为 `id: 100`、`id: 101 / f_parent: 100`。复制后必须先得到两个不同的
+临时 `id`，子节点指向复制后父节点的临时 `id`；提交后两个临时 ID 均清空，子节点
+只嵌套在复制后的父节点下一次。
+
+### 14.5 未保存父节点下的单行保存
+
+父节点物理 ID 仍为空时，单独保存其子节点必须在前端被阻止，不发送请求。父节点保存
+成功并返回正式 `rowField` 后，先同步子节点 `parentField`，再允许保存子节点。
+
+### 14.6 懒加载完整性
+
+节点 `hasChild: true` 且后代未加载时：
+
+- 默认复制和整表提交均被阻止；
+- `loadAll` 必须等完整后代加载结束再重取快照；
+- 只有明确启用并联调过 `omit` 的提交才可继续，且请求中不得出现该节点的
+  `children: []`。
+
+### 14.7 已持久化树键变更
+
+已落库父节点的物理主键编辑必须被拒绝。独立业务 `rowField` 默认同样不可直接编辑；
+启用 `transactional` 后，验收请求必须由专用接口一次更新父键和全部子引用，模拟
+接口失败时前端与后端都保持旧关系。
+
+## 15. 已审查问题与落地点
+
+| 已发现问题 | 最终落地点 |
+|---|---|
+| 自定义 `rowField` 单行保存泄漏 `row_*` | `sanitizeTreeRow` 同时服务单行与整表 |
+| `getSubData2` 只清理顶层 | `collectTreeNodes` + 递归组装/清洗 |
+| 复制自定义 `rowField` 时保留旧物理 `id` | `physicalIdField` 独立并在复制第一遍清空 |
+| 产品编码被改成新 `row_*` | 默认 `preserve`，禁止混同物理 ID |
+| rowField 与物理 ID 同字段却显式 preserve/永久生成 | 配置守卫，仅允许服务端生成的带标记临时键 |
+| 技术树键复制后父引用仍指向旧树 | 两遍复制和旧键到新键映射 |
+| 只靠 `row_` 前缀判断临时值 | `_X_TREE_TEMP_KEY` 精确标记 |
+| 正式树键变化后子节点断链 | `changeTreeRowField` 同步引用 |
+| 已持久化树键只改前端/父行导致后端断链 | 默认禁止；特殊场景走后端事务级联接口 |
+| `transform: false` 时子节点丢失 | 合并后强制校验并恢复为 `true` |
+| nested-only 数据直接进入 transform 后代丢失 | 入 VXE 前统一规范平铺 |
+| number/string 混用导致 VXE 与提交口径不同 | 数据入表前关系类型归一 |
+| `_X_ROW_CHILD` 和不同实例导致重复 | 对象引用 + 稳定身份去重，冲突失败 |
+| 父字段、嵌套边冲突或形成环 | 父字段为权威并执行多父/自指/环校验 |
+| 默认 id 复制先清 ID 后映射断链 | 清洗前快照旧 rowField/parentField |
+| 未加载子树被当成空树 | `hasChild` 加载态和 reject/loadAll/omit 协议 |
+| 未保存父节点下的子行单独保存 | 默认阻止，父保存回填正式键后再开放 |
+| 临时业务键被清成 null | `serverGeneratesRowField` 契约与提交前阻断 |
+| `tableTreeMixins` 写死 `row.id` | 纳入 xform 调用边界与物理 ID 配置 |
+
+## 16. 实施顺序
+
+### 阶段一：纯函数和测试先行
+
+1. 建立 `treeTableUtil.js`；
+2. 完成根值、键归一、稳定身份去重、图校验、规范平铺、复制和递归清洗单测；
+3. 用产品编码、默认 id 和独立技术树键样例锁定策略差异；
+4. 用未加载/已加载空子树锁定懒加载语义。
+
+### 阶段二：优先修复数据安全出口
+
+1. 复制时清空物理 ID；
+2. 默认 id 复制先快照再映射；
+3. 单行保存接入专属清洗和“父节点先保存”守卫；
+4. `getSubData2` 接入递归提交组装及加载完整性校验；
+5. 防止临时键、旧 ID 和内部字段进入请求。
+
+### 阶段三：运行时链路收敛
+
+1. 所有入表入口接入规范平铺、类型归一和图校验；
+2. 新增、树键编辑和保存响应回填接入统一入口；
+3. 首次展开、懒加载、排序、删除、定位统一键比较；
+4. `mapChildren` 和 `transform` 配置守卫；
+5. 核实并修复 xform 实际调用的 `tableTreeMixins` 方法。
+
+### 阶段四：回归与发布
+
+1. 执行单测、组件测试、ESLint 和构建；
+2. 对默认 `id` 树表和自定义业务键树表各做一次接口联调；
+3. 检查复制、新增、单行保存、整表提交请求体；
+4. 确认无旧物理 ID、无临时键、无 `_X_*` 字段后再发布。
+
+## 17. 完成标准
+
+全部满足后才可标记为落地完成：
+
+- [ ] `rowField` 与物理 ID 在命名、配置和实现中已拆分；
+- [ ] 复制产品编码树时编码保持不变；
+- [ ] 复制技术键树时整棵子树完成新键映射；
+- [ ] 所有复制节点的旧物理 ID 已清空；
+- [ ] 默认 id 多层树复制使用旧键快照且父映射正确；
+- [ ] `rowField === physicalIdField` 不会保留或写回任何旧/永久物理 ID；
+- [ ] 所有复制新树键在复制集合和目标表内唯一；
+- [ ] 新增节点使用显式临时标记；
+- [ ] 正式树键回填会同步直接子节点父引用；
+- [ ] 已持久化物理主键不可编辑，业务树键不会通过普通单行保存半更新；
+- [ ] 未保存父节点下的子节点不会走单行保存请求；
+- [ ] 单行保存不会携带当前行的 children/mapChildren 子树；
+- [ ] 单行保存和整表提交均递归清洗；
+- [ ] 平铺、嵌套、懒加载数据无丢失、无重复；
+- [ ] 未加载子树不会被当作已加载空树；
+- [ ] `lazy: false/true` 使用正确完整性口径，加载失败不产生部分请求；
+- [ ] 不同实例重复、父边冲突、自指和环均有明确失败行为；
+- [ ] 同一对象的每个 occurrence 父边都参与图校验；
+- [ ] 外部父键只有经正式 registry/validator 确认后才能提交；
+- [ ] number/string 父子关系在进入 VXE 前已归一；
+- [ ] 默认根输出仍为现有协议 `0`，特殊接口通过配置显式修改；
+- [ ] 非法根值、字段名碰撞和异步键生成器会在运行前被拦截；
+- [ ] 默认和自定义 `mapChildren` 均从最终有效配置解析；
+- [ ] `transform: false` 不会进入运行态；
+- [ ] VXE 内部字段和临时标记不进入请求；
+- [ ] 提交组装不修改表格原对象；
+- [ ] 新身份落库后强制 reload，完成前不会再次保存；
+- [ ] 普通同步取值 API 不触发加载，也不执行提交完整性拒绝；
+- [ ] 默认 `rowField: "id"` 的既有功能回归通过；
+- [ ] 新增测试覆盖本文测试矩阵。
+
+---
+
+<details>
+<summary>附录：此前实现记录（已被上文方案取代，仅保留审查追溯）</summary>
+
+以下内容记录了第一版实现及当时的判断，其中“`rowField` 等同物理 ID”、
+“复制一律重建 `rowField`”以及“`tableTreeMixins` 不在 xform 范围”等结论均不再作为
+实现依据。
+
+## 一、背景与问题定性
+
+### 1.1 起因
+
+`getSubData2()` 提交树表数据时，根节点过滤条件为：
+
+```js
+item[parentField] === 0 || item[parentField] === null
+```
+
+存在两个缺陷：
+
+1. **口径过窄**：后端回来的父字段常见 `""`、`"0"`，这些根行连同整棵子树被过滤丢失；
+2. **判定时机错误**：过滤前的清洗会把 `"row_"` 开头的临时父 id 置 `null`，
+   新增子行（父行也是新增、id 为 `row_xxx`）因此被误判为根节点——既作为顶层提交，
+   又嵌在父行 `f_children` 里，提交数据重复、层级错乱。
+
+### 1.2 根因（rowField 三链分叉）
+
+排查发现问题不止提交端。整个树表存在**三条并存的"树主键"取值链**，
+仅在默认值 `id` 上巧合重合：
+
+| 链 | 取值方式 | 来源 |
+|---|---|---|
+| A | vxe 内部 `treeOpts.rowField` | `Object.assign({}, 全局默认, treeConfig prop)`，全局默认 `'id'`；transform 建树（xe-utils `toArrayTree`）以它为 key |
+| B | 业务代码 `$grid.treeConfig.rowField \|\| "id"` | 读原样 prop；改造前字面量未声明 rowField，恒 undefined → 落到 `"id"` |
+| C | 写死字面量 `.id` | 新增行临时 id、父子挂接 `parent?.id`、行定位、自动展开、回显排序等十余处 |
+
+**触发面**（任一即分叉）：
+
+- 源码给 treeConfig 字面量加 rowField；
+- 宿主页面传 `dataTableOption.config.treeConfig`（改造前为**整对象替换**，
+  漏写任何键都会连 rowField/parentField/children 一起丢掉）——运行时可达，无需改 xform 源码。
+
+分叉后果：新增行 key 为 undefined 全部挤进 `treeMap[undefined]` 层级全乱、
+新增子节点全部变根、`row_` 临时 id 泄漏提交、行定位/自动展开/回显排序失效。
+
+### 1.3 rowField 的语义
+
+`rowField` 是扁平树数据里 **parentField 外键所引用的那一列的列名**。
+`toArrayTree` 按 `treeMap[row[parentField]].push(row)` 挂树、
+"父值不在全表 rowField 值集合中"判根。本项目约定 `f_parent` 存父行的 `id` 值。
+
+三个易混标识的分工：
+
+- `rowField`（=id）——业务主键，父子关系锚点，提交给后端；
+- `_X_ROW_KEY`——vxe 内部行 key，仅表格实例内定位（展开恢复、getRowById），不参与建树；
+- `f_children` / `_X_ROW_CHILD`——建树产物（children / mapChildren），不是数据源。
+
+## 二、落地内容
+
+决策：**rowField 保持可配置，treeConfig 为唯一事实源**（方案 b；"全链写死 id" 被否）。
+现状 rowField 仍为 `"id"`，本次改造语义零变化，收敛的是"配置变化时链条不再分叉"。
+
+### 2.1 `form-render/container-item/data-table-mixin.js`
+
+**① treeConfig 显式声明 rowField（`buildTableOption`，treeConfig 字面量）**
+
+```js
+treeConfig = {
+  lazy: false,
+  rowField: "id",        // ← 唯一声明点，此前隐式依赖 vxe 全局默认
+  children: "f_children",
+  hasChild: "f_has_child",
+  parentField: "f_parent",
+  transform: true,
+  ...
+}
+```
+
+**② 新增统一读取口 `getTreeFields($grid)`**（`getGridTable` 旁）
+
+```js
+getTreeFields($grid) → { idField, parentField, childrenField, hasChildField }
+```
+
+- `idField` 兜底 `"id"`（与 vxe 全局默认一致）；
+- 其余键**不设兜底**：保持调用方原有空值守卫语义
+  （非树表 treeConfig 缺失时，`addTreeRows` 的 `if (parentField)` 不应凭空写入 `f_parent`）。
+
+**③ 链 C 写死点全部改走配置**（12 处调用点）
+
+| 场景 | 方法 | 改造 |
+|---|---|---|
+| 新增行临时 id | `addTreeRow` / `addTreeRows` / `addEditRow` | `newRow.id = "row_..."` → `newRow[idField] = ...` |
+| 父子挂接 | 同上三处 | `parent?.id` → `parent?.[idField]` |
+| 新增后激活 | `addTreeRow` 两处调用 + `setActiveRowById` 内部比较 | 按 `idField` 传参与查找 |
+| 回显父子排序 | `handleTreeData` | nodeMap 构建与 `addChildNodes` 递归入口按 `idField` |
+| 首载自动展开 | proxyConfig query 回调 | `expandIds.includes(item[idField])` 两处 |
+| 懒加载参数 | `loadMethod` | `[parentField]: row[idField]` |
+
+**④ 顺手修复的现行 bug：treeNodeParam**
+
+原代码读不存在的 `widget.options.parentField`（widgetsConfig 从未定义该选项），
+生成 `{undefined: id}` 脏参数。改为从 treeConfig 字面量取 parentField/rowField，
+并移到 treeConfig 声明之后。
+注：该参数仅在 `treeNodeUrl` 路径（`components/table/index.js`）被消费，
+xform 树表不走此路径（treeNodeUrl 为注释状态），修复属于纠正死代码语义。
+
+**⑤ 宿主覆写通道改深合并**
+
+```js
+let hostTableConfig = dataTableConfig.config || {};
+if (treeConfig && hostTableConfig.treeConfig) {
+  hostTableConfig = {
+    ...hostTableConfig,
+    treeConfig: { ...treeConfig, ...hostTableConfig.treeConfig },
+  };
+}
+```
+
+- 宿主经 `dataTableOption.config.treeConfig` 只改单键（如 expandAll）不再冲掉其余键；
+- 新建对象合并，不改宿主经 `$attrs` 传入的原对象；
+- 非树表宿主传 treeConfig 原样透传，行为不变；
+- 与表单脚本通道（`extendDeeply(tableOption, tableConfig)`，本身即深合并）语义拉平。
+
+**⑥ 既有 5 处 `rowField || "id"` 统一走 helper**
+
+`collectDescendantKeys`、`moveUpRow`、`moveDownRow`、`openSortRowDialog`、`confirmTreeMoveDialog`。
+
+### 2.2 `form-render/indexMixin.js` — `getSubData2` 提交端修复
+
+树表分支重写（此前轮次落地，与本轮共同构成完整链路）：
+
+1. `idField = $grid.treeConfig.rowField || "id"`，判根与 vxe 建树同源；
+2. **判根先于清洗**：先按原始父子关系算 `isRootFlags`，再清临时 id，
+   杜绝临时父 id 被清后误判为根；
+3. 判根口径与 `toArrayTree` 一致：父值为空（`null/undefined/""/0/"0"`）视为根；
+   父值非空但父行不在本表数据（过滤/查询后的孤儿行，如 `f_parent=10086` 而
+   10086 未被查出）**也收进顶层数组且保留 parentField 原值**，
+   由后端据此挂回既有父节点——不丢数据、不篡改层级；
+   id 比较统一 `String()` 归一防类型不匹配；
+4. 临时 id 双清：`clearTempValue` 对 `idField`、字面量 `id`（两者不同才多清一次）、
+   `parentField` 各清一遍。原因：临时 id 有两个写入方——`addTreeRow/addTreeRows`
+   写 `row.id`，`handleCopyTreeData` 写 `row[rowField]`，提交出口把两条来源都兜住。
+
+**依赖的后端契约**：顶层数组允许出现 parentField 非空的行（孤儿行），
+应按 parentField 挂接既有节点而非一律当根写入。若后端为"顶层即根"实现，需后端配合。
+
+## 三、明确不动的部分
+
+| 项 | 原因 |
+|---|---|
+| 导出勾选 ids（`item.id`，约 2926 行附近） | 按决策保持——导出接口收物理 id，不随 rowField 走 |
+| `mixins/tableTree/`（a-link 非编辑树表生态） | 独立体系（parentField 为 `parent`），不在 xform 范围 |
+| `handleCopyTreeData`（indexMixin） | 本就走 `rowField \|\| "id"`，与收敛后链路一致 |
+
+## 四、验证结果
+
+- ESLint：`data-table-mixin.js` 56 条 = 改前基线（全为存量 operator-linebreak），零新增；
+  `indexMixin.js` 由 178 → 174（helper 替换掉 4 条历史风格错误）；
+- Jest：8 套 99 例全过（现有用例不覆盖树表链路，属回归性验证）；
+- Babel parse OK；同作用域无变量重复声明；
+- `setActiveRowById` 无 mixin 之外调用方；`loadMethod` 里 `tableConfig?.treeNodeParam`
+  读的是表单脚本配置（与被搬动的局部变量无关），时序与引用均验证通过。
+
+## 五、后续约定（重要）
+
+1. **树表父子关联代码一律经 `getTreeFields($grid)` 取列名，禁止写死 `id`/`f_parent`**——
+   写死会在配置变化时与 vxe 建树分叉（treeConfig 字面量处有注释锚点）；
+2. **真要把 rowField 配成非 `id` 列，前端已就绪但必须后端同步**：
+   主键列、`row_` 前缀新行识别落点、父子挂接列的接口契约都会变，
+   前端单方面改配置会把错误转移到接口层；
+3. 宿主/脚本覆写 treeConfig 均为深合并，只写想改的键即可。
+
+## 六、遗留敞口（未处理，单独排期)
+
+| # | 位置 | 问题 |
+|---|---|---|
+| 1 | `indexMixin.js` `treeSubTables`（复制单据） | 默认 `parent_id` ≠ 表格 `f_parent`，漏配时复制树层级指向原单节点 |
+| 2 | `moveUpRow`/`moveDownRow`/`openSortRowDialog` 同级过滤 | `===` 无 String 归一，number/string 混用会漏匹配 |
+| 3 | `toArrayTree` 副作用 | 子树同时挂 `f_children` + `_X_ROW_CHILD`（mapChildren 全局默认）在原始行上，提交体积随深度翻倍，需评估提交前是否剔除 `_X_ROW_CHILD` |
+| 4 | `treeNodeParam` 闭包 | 读字面量 treeConfig 而非运行时合并后的 `$grid.treeConfig`；仅 treeNodeUrl 路径消费（xform 未用），暂无影响 |
+| 5 | `f_wbs`/`f_has_child` 等 `f_` 前缀约定 | 散落写死，改 parentField 命名需连带梳理 |
+
+## 七、分支同步状态
+
+| 分支 | getSubData2 修复 | data-table-mixin 收敛 |
+|---|---|---|
+| corejs（本仓库） | ✅ | ✅ |
+| `sf-cloud-web-vue-tw@haier_publish_dev` | ✅（同步时移除了原树表分支内一行 `debugger` 调试遗留） | ❌ 按指示暂缓，待通知后同步 |
+
+</details>