cloud-web-corejs 1.0.54-dev.73 → 1.0.54-dev.730

package/src/components/xform/docs//345/257/271/346/257/224/345/212/237/350/203/275/350/220/275/345/234/260/346/226/271/346/241/210.md

@@ -0,0 +1,569 @@
+# xform 表单对比（变更前/变更后）功能落地方案
+
+> **实现状态：已落地。** 涉及文件：
+> - 新增 `form-render/compareView.vue`（对比提示组件；感叹号固定在字段前、flex 布局不失焦不顶起输入框，文案 `$t1` 国际化）
+> - 新增 `form-render/compareDelList.vue`（查看删除数据弹窗；vxe-grid、列取当前数据表格字段/标题/宽度、固定高度铺满、系统弹框样式、`$t1` 国际化）
+> - `form-render/indexMixin.js`：状态 `isCompare/oldFormData/compareRowKey/compareExcludeTypes/compareExcludeFields`；provide 下发（含 `isCompareExcludeField`）；公开方法 `enableCompare/disableCompare/setOldSubData/getDelData/openCompareDelList`；取数 `loadOldData`（主表 getOne + 表头附件各自 getList + data-table 子表 getList，均带 `attachmentType/thirdtabm`）；一行接入 `initChangeFromSource`(模式A)/`enableCompareBySource`(模式B)；清洗 `sanitizeChangeData`（系统字段清理、树表 id/parent_id 重生成 `regenerateTreeIds`、附件白名单 `attachmentKeepFields`、`defaultFields/subDefaultFields` 不覆盖取默认、`subSourceFields` 原单字段/表头回填）；行级样式 `getCompareRowClass`（变更行/新增行）、字段级排除 `isCompareExcludeField`（`create_by/create_date/modify_by/modify_date` 等系统字段默认排除）
+> - `form-render/index.vue`：注册并挂载 compareDelList
+> - `field-widget/fieldMixin.js`：`compareEquals`（原始值判定）、`resolveDisplayValue`（值→label）、`resolveCompareOldDisplay`（关联类从原单行取伴随 label）；各映射组件 override（select/radio/checkbox/status/switch/cascader/vabSearch/autocomplete）
+> - `field-widget/form-item-wrapper.vue`：inject 对比接口、`isCompareOn/compareOldRow/compareIsDiff/compareOldDisplay/compareRowIsNew`（新增行不逐格显示感叹号）、按类型+字段名排除
+> - `container-item/data-table-mixin.js` + `data-table-item.vue`：`rowClassName` 注入变更行/新增行整行高亮；`getSubTableCurrentRows` 读实时表格数据
+> - `mixins/defaultHandle.js`：`getReqFormData` 提交前递归剥除对比快照字段 `hData`
+> - `widget-panel/widgetsConfig.js` + `widget-panel/index.vue`：业务组件标签页下新增「对比组件」分组（对比 / 关闭对比 / 查看删除明细 3 个按钮，默认展开）
+
+
+> 参考实现：`2023/yx2-vue/sf-cloud-web-vue-tw@std/src/views/yx/certificate/agreementChange/edit.vue`
+> 目标组件：`src/components/xform/`（form-render + field-widget）
+
+## 〇、接入指南（配置流程）
+
+> 面向业务配置人员：如何给一张「变更单」接上对比。form-render 已内置能力，业务侧只需配置按钮 onClick 脚本、表单 onMounted 脚本，以及列表页一段 autoAdd。
+
+### 前置：后端接口
+推荐用内置的**通用多包加载 `loadOldData`**，它直接复用原单模板的标准读脚本（主表 `getOne`、data-table 子表 `getList`），**无需为对比新增后端接口** —— 只要原单本身的表单读脚本可按 id 查询即可。
+
+仅当需要自定义取数时，才手动取数 + `enableCompare`。**取原单数据统一走 `loadOldData`（内部用 `formHttp` 按模板脚本发包），不要用 `formRef.$http` 直接打 url。** 需要额外定制请求时用 `formRef.formHttp({ scriptCode, data, success })`。
+
+### 相关入口（本项目现有机制）
+- 列表打开详情：`openEditDialog(row, param, option)` —— `row=null` 走新增（无 dataId）；`param` 为业务参数，详情用 `getFormParam()` 读取。列表 xform 宿主：`src/views/user/form/view/list.vue`。
+- 详情表单读打开参数：`this.getFormParam()`（`defaultHandle.js`，返回 `formRef.param`）。
+- 按钮/表单脚本上下文：`this` 为组件，`this.getFormRef()` 拿 form-render 实例；注入参数含 `dataId`。
+
+### 数据流（三跳）
+```
+原单详情「变更」按钮
+  └─ router.push 到「变更单列表路由」，query 带 sourceId + autoAdd
+        ↓
+变更单列表页 (list.vue 宿主)
+  └─ mounted 读 $route.query，autoAdd 时调
+        openEditDialog(null, { sourceId }, { formCode: addFormCode })
+        ↓
+变更单详情表单 onMounted
+  └─ 无 dataId：sourceId = getFormParam().sourceId
+     → getOld(sourceId) → setFormData + enableCompare  （模式A 自动对比）
+```
+
+### 第 1 跳：原单「变更」按钮 onClick
+从「对比组件」拖入**变更**按钮（`compare-change-button`），预置 onClick 直接调内置方法（`dataId` 为注入参数）：
+```js
+this.getFormRef().goChangeBill(dataId, '变更单formCode');   // 把 '变更单formCode' 改成实际编号
+```
+> **`goChangeBill(sourceId, formCode, options)`（form-render 内置）**：跳到变更单列表并携带 sourceId 打开新增。
+> - 目标列表路径：默认复用当前路由、把**最后一段替换为 `formCode`**（同基兄弟列表约定）；不符合时用 `options.listPath` 指定完整路径。
+> - 打开参数走 `query.param`(JSON)：`{ sourceId, autoAdd:1 }`（可用 `options.param` 追加）。
+> - 跳转方式：先 `store.dispatch('tagsView/delCachedView', view)` 清缓存视图，再 `router.replace(view)`，确保列表按新参数重载。
+
+### 第 2 跳：变更单列表页自动打开新增详情
+变更单列表页（xform 宿主 `list.vue` 或其业务包装）`mounted`/`activated` 里加（`param` 由 `query.param` 解析到 `this.param`）：
+```js
+let p = this.param || {};
+if (p.autoAdd) {
+  // row=null → 新增；param 带 sourceId，详情用 getFormParam() 取
+  this.openEditDialog(null, { sourceId: p.sourceId }, { formCode: this.addFormCode });
+}
+```
+> 唯一需在列表页新增的一小段（读 param → 调现有 `openEditDialog`）。
+
+### 第 3 跳：变更单详情表单 onMounted（模式 A 自动对比）
+**推荐：一行接入 `initChangeFromSource`** —— 内部自动按原单模板多包拉取（主表 + 所有 data-table 子表）→ 清洗 → 填充新单 → 开启对比。无需逐个子表写发包。
+```js
+if (!dataId) {                              // dataId 注入参数，无=新建
+  let f = this.getFormRef();
+  let sourceId = f.getFormParam() && f.getFormParam().sourceId;
+  f.initChangeFromSource(sourceId, {
+    sourceFormCode: '原单formCode',        // 用原单模板拉原单数据（原单≠变更单模板时）
+    compareRowKey: 'uuid',
+    sanitize: {                             // 传给 sanitizeChangeData
+      defaultFields: ['billType'],          // 主表字段不吃原单值、保留变更单默认值
+      subDefaultFields: { 明细A: ['status'] }, // 明细列不吃原单值
+      subSourceFields: { 明细A: 'f_source_id' }, // 原明细 id 回填
+      treeSubTables: ['分类明细'],
+    },
+  });
+}
+```
+> `initChangeFromSource` = `loadOldData`(自动多包) + `sanitizeChangeData`(清洗) + `setFormData`(新单) + `enableCompare`(原始旧数据为基准)。
+>
+> **模板解析**：传 `sourceFormCode` 时，内部按 `/formTemplate/getByFormCode` 拉**原单模板**，用其 widgetList 枚举原单子表、entity、formCode 来发包（原单与变更单模板不同时用这个）；不传则复用当前变更单模板（结构一致时）。也可用 `reportTemplate/formCode/formVersion/entity` 精确覆盖。
+
+**手动版（需自定义拆解逻辑时）**：仍用 `loadOldData` 取数（内部 formHttp），只是手动清洗/填充/对比。`setFormData` 用清洗后数据，`enableCompare` 用原始旧数据；`uuid` 不被清理，新旧行仍匹配。
+```js
+f.loadOldData(sourceId, { sourceFormCode: '原单formCode' }).then(oldData => {
+  let newData = f.sanitizeChangeData(oldData, { defaultFields:['billType'] });
+  f.setFormData(newData);
+  f.enableCompare(oldData, { compareRowKey: 'uuid' });
+  // 子表多包补充：f.setOldSubData('子表字段名', 子表旧行);
+});
+```
+`sanitizeChangeData(oldData, options)` 选项：
+- `masterClearFields`：覆盖主表默认清理字段（默认含 id/createBy/createDate/modifyBy/modifyDate/_createBy/_modifyBy 及其 snake_case 形式）；
+- `subExtraClearFields`：仅子表额外清理的外键字段，默认 `head_table_id/headTableId/alias_id/object_foreign_id`；
+- `defaultFields`（主表）/ `subDefaultFields`（明细 `{keyName:[列prop]}`）：这些字段**不吃原单值**，保留变更单自身值/默认值；
+- `subSourceFields`：`{ 明细keyName: 配置 }`，原明细行/原单表头字段回填到明细（字符串/`{from,to}`/`{fromHeader,to}`/数组/`(row,header)=>{}`；早于清 id/树表重生成执行）；
+- `attachmentKeepFields`：附件文件对象保留字段白名单（默认 `name/thumbnail/extension/large/fileSize/domain/source/medium/url`）；`cleanAttachment:false` 关闭精简；
+- `treeSubTables`：**树结构子表**配置，其 `id/parent_id` 需重新生成并把 parent_id 按旧→新映射重指向以保留层级。格式 `[{ name, idField='id', parentField='parent_id' }]`，也可简写字符串数组 `['子表名']`。外部父级的 parent_id 置空作根。**新生成 id 形如 `_row{随机数}`，本表内保证唯一。**
+
+示例（含树表）：
+```js
+let newData = f.sanitizeChangeData(oldData, {
+  defaultFields: ['billType'],
+  subDefaultFields: { 明细A: ['status'] },
+  subSourceFields: { 明细A: (row, header) => { row.f_source_id = row.id; row.f_head_no = header.f_no; } },
+  treeSubTables: [{ name: '分类明细', idField: 'id', parentField: 'parent_id' }],
+});
+```
+
+### 模式 B：已保存变更单「对比」按钮 onClick
+**推荐：一行接入 `enableCompareBySource`** —— 自动按模板多包拉取原单并开启对比：
+```js
+let f = this.getFormRef();
+let sourceId = f.getFormData().sourceId;    // 变更单里存的原单引用
+f.enableCompareBySource(sourceId, { compareRowKey: 'uuid' });
+```
+> 手动版：`f.loadOldData(sourceId).then(old => f.enableCompare(old, { compareRowKey:'uuid' }))`。
+
+### 其它按钮
+- 关闭对比：`this.getFormRef().disableCompare();`
+- 查看删除数据：`this.getFormRef().openCompareDelList('子表字段名');`（要中文列头传第二参 `[{field,title},...]`）
+
+### 全局配置项（可选）
+- `formConfig.compareRowKey`：子表行匹配主键，默认 `uuid`；也可 `enableCompare(old,{compareRowKey})` 覆盖。
+- `formConfig.compareExcludeTypes` / `enableCompare(old,{excludeTypes})`：不参与对比的字段类型（附件/上传类已默认排除）。
+- `formConfig.compareExcludeFields` / `enableCompare(old,{excludeFields})`：按**字段名**不参与对比；`create_by/create_date/modify_by/modify_date/id/head_table_id/alias_id/object_foreign_id` 等系统字段已默认排除。
+- `sanitize.defaultFields`（主表）/ `sanitize.subDefaultFields`（明细表 `{keyName:[列prop]}`）：这些字段**不吃原单值**，保留变更单自身值/默认值。
+- `sanitize.subExtraClearFields`：子表额外清空的外键字段，默认 `head_table_id/headTableId/alias_id/object_foreign_id`。
+- `sanitize.attachmentKeepFields`：附件文件对象保留字段白名单，默认 `name/thumbnail/extension/large/fileSize/domain/source/medium/url`（表头附件、data-table 单元格附件都按此精简；`sanitize.cleanAttachment:false` 可整体关闭）。
+- `sanitize.subSourceFields`：`{ 明细keyName: 配置 }`，把原明细行/原单表头字段回填到明细业务字段。配置支持：
+  - `'目标字段'` → 原明细 `id` → 目标字段
+  - `{ from:'明细字段', to:'目标字段' }`（from 默认 `id`）
+  - `{ fromHeader:'表头字段', to:'目标字段' }` → 原单表头字段回填
+  - `[ {..}, {..} ]` → 多字段
+  - `(row, header) => {...}` → 自定义函数（row 原明细行、header 原单表头；均为原始值，早于清 id/树表重生成执行）
+- `sanitize.treeSubTables`：树表配置 `[{ name, idField, parentField }]`，id/parent_id 会重新生成并保留层级。
+- **保存**：提交时 `getReqFormData` 自动剥除对比快照字段 `hData`，无需业务处理。
+- **行级高亮**：变更行橙色、新增行绿色（各带左侧色条），新增行不逐格显示感叹号；系统字段/`compareExcludeFields`/附件列不参与行级判定。
+
+### 完整接入示例（GlobalConfig）
+把对比相关逻辑收敛到 `getGlobalConfig()` 返回对象里，详情页脚本按需调用。
+
+#### 步骤 1：从「对比组件」拖入 3 个按钮
+
+设计器 → **业务组件**标签页 → **对比组件**分组（默认展开），拖入按钮。分组含 4 个按钮，已预置好 `label`、默认显隐、`onClick` 脚本，拖进去基本即用。
+
+| 按钮 | 面板 type | 放在 | 唯一名称(示例) | 默认显隐 | 预置 onClick |
+|------|-----------|------|----------------|----------|--------------|
+| 变更 | `compare-change-button` | **原单** | — | 显示 | `this.getFormRef().goChangeBill(dataId, '变更单formCode')` |
+| 对比 | `compare-button` | 变更单 | `button67308` | 显示 | `this.getFormRef().getGlobalConfig().enableCompareBySource(this)` |
+| 关闭对比 | `compare-close-button` | 变更单 | `button107799` | **隐藏** | `this.getFormRef().getGlobalConfig().disableCompare(this)` |
+| 查看删除明细 | `compare-del-button` | 变更单 | `button41887` | **隐藏** | `this.getFormRef().openCompareDelList('明细表keyName')` |
+
+拖入后仅需：① **变更**按钮把 `'变更单formCode'` 改成实际变更单编号（放在原单表单）；② 变更单上 3 个按钮设「唯一名称」，与 GlobalConfig 里 `compareBtnName/closeBtnbName/checkDelbTNName` 对应；③ 把「查看删除明细」里的 `'明细表keyName'` 改成实际明细 keyName（如 `test_source_bill_item`）。
+
+> 「关闭对比」「查看删除明细」已预置默认隐藏；开启对比后由 `handleCompareButton` 统一放出、隐藏「对比」。
+
+#### 步骤 2：`getGlobalConfig` 里定义对比逻辑
+
+```js
+//对比功能配置步骤
+//定义GlobalConfig
+let compareRowKey = 'f_uuid';                 // 明细行的对比唯一字段
+let defaultFields = ['f_type', 'f_source_id'];// 字段值不覆盖的字段（保留变更单自身值）
+let excludeFields = ['f_type', 'f_source_id'];// 不对比字段
+let compareBtnName = 'button67308';           // 对比按钮的唯一名称
+let closeBtnbName  = 'button107799';          // 关闭对比按钮的唯一名称
+let checkDelbTNName = ['button41887'];        // 查看删除明细按钮的唯一名称（可多个）
+return {
+  initChangeFromSource(that) {
+    // 新增页面初始化原单数据（模式A：自动开启对比）
+    if (!dataId) {
+      let sourceId = that.getFormParam()?.sourceId
+        ? Number(that.getFormParam()?.sourceId) : null;
+      if (sourceId) {
+        that.formModel.f_source_id = sourceId;
+        that.formModel.f_type = 1;
+        that.getFormRef().initChangeFromSource(sourceId, {
+          compareRowKey: compareRowKey,
+          excludeFields: excludeFields,
+          sanitize: {                          // 传给 sanitizeChangeData
+            defaultFields: defaultFields,
+            subSourceFields: {
+              // test_source_bill_item 原单明细ID回填到 f_source_item_id
+              test_source_bill_item: (row, header) => {
+                row.f_source_item_id = row.id;
+              },
+            },
+          },
+        });
+      }
+      this.handleCompareButton(that, true);    // 处理对比按钮的显隐
+    }
+  },
+  enableCompareBySource(that) {
+    // 点击对比，启用对比（模式B：从后端重新拉原单比对）
+    let formRef = that.getFormRef();
+    let sourceId = that.formModel.f_source_id;
+    formRef.enableCompareBySource(sourceId, {
+      compareRowKey: compareRowKey,
+      excludeFields: excludeFields,
+    });
+    this.handleCompareButton(that, true);      // 处理对比按钮的显隐
+  },
+  disableCompare(that) {
+    // 关闭对比
+    that.getFormRef().disableCompare();
+    this.handleCompareButton(that, false);     // 处理对比按钮的显隐
+  },
+  handleCompareButton(that, isCompare) {
+    // 开启对比后，隐藏对比按钮，放出关闭按钮和查看删除按钮；关闭对比则相反
+    that.getWidgetRef(compareBtnName).setHidden(isCompare);   // 隐藏对比按钮
+    that.getWidgetRef(closeBtnbName).setHidden(!isCompare);   // 放出关闭对比按钮
+    checkDelbTNName.forEach((item) => {
+      that.getWidgetRef(item).setHidden(!isCompare);          // 放出查看删除按钮（用 item）
+    });
+  },
+};
+```
+
+#### 步骤 3：详情页入口脚本 / 按钮 onClick 调用
+
+```js
+// 新增页面初始化原单数据（表单入口脚本 / onMounted）
+if (!dataId) {
+  let globalConfig = this.getGlobalConfig();
+  globalConfig.initChangeFromSource(this);
+}
+
+// 「对比」按钮 onClick
+this.getGlobalConfig().enableCompareBySource(this);
+
+// 「关闭对比」按钮 onClick
+this.getGlobalConfig().disableCompare(this);
+
+// 「查看删除明细」按钮 onClick
+this.getFormRef().openCompareDelList('test_source_bill_item');
+```
+
+> **易错点**：
+> 1. `handleCompareButton` 里遍历删除按钮要用循环变量 `item`，不要误写成 `closeBtnbName`。
+> 2. 模式A（新增自动对比）也要调用 `handleCompareButton(that, true)`，否则按钮状态与模式B不一致。
+> 3. 「关闭对比」「查看删除明细」按钮在设计器里默认隐藏，避免非对比态先闪出。
+> 4. 模式B靠 `f_source_id` 反查原单，确认保存/回显链路带上了该字段。
+> 5. `subSourceFields` 回填在清空/重生成 id 之前执行；`(row, header)` 可同时读原明细行与原单表头。
+
+## 一、背景与目标
+
+外部业务页把「变更前的旧整单数据」传入 form-render，开启对比模式后：
+
+- **主表字段**：值发生变化时，字段旁展示"变更前"提示（hover 弹出旧值）。
+- **子表格单元格**：同上，逐行逐列对比。
+- **被删除的子表行**：可通过"查看删除数据"弹窗查看。
+
+对比逻辑完全参照 agreementChange：`isCompare` 开关 + 旧数据对象 + `compareView` 提示组件 + 子表逐行 `hData` 快照（按主键匹配）+ `getDelData` 删除行比对。
+
+## 二、参考实现的对比机制（梳理）
+
+1. **双份数据**：`agreement`（当前）与 `oldAgreement`（变更前）并存。
+2. **主表字段**：`compareView` 直接吃 `oldAgreement.xxx` 与 `agreement.xxx`。
+3. **子表**：每行携带 `hData` 快照（`item.hData = cloneDeep(旧行)`），按 `uuid` 匹配新旧行；`getHValue(row, column)` 返回 `row.hData[column.property]`。
+4. **compareView 组件**：props `isCompare / oldVal / newVal`；`isCompare && oldVal != newVal` → 显示 `el-icon-warning` + popover「变更前：xxx」，否则原样渲染 slot。
+5. **删除行**：`getDelData(key)` 用 uuid 比对新旧明细数组，找出"旧有但新无"的行，配合 `compareDelList` 弹窗展示。
+
+## 二·五、业务场景与触发时机（重要）
+
+整个对比发生在「变更单」表单上，分两种模式：
+
+### 模式 A：新建变更单（默认开启对比）
+1. 在原单据详情页点击「变更」按钮。
+2. 跳转到变更单列表页，并自动打开对应的变更单**新增**详情页（此时无变更单 id）。
+3. 页面加载时拿到**原单据数据**作为旧数据，`enableCompare(原单据数据)` 自动执行，默认进入对比态。
+
+> 对应参考实现：`created()` 中 `if (!this._dataId) this.isCompare = true;`，旧数据来自 `getOld`。
+
+### 模式 B：已保存的变更单（手动点「对比」触发）
+1. 变更单保存成功后，页面已带变更单 id，**默认不开启对比**。
+2. 用户点击「对比」按钮 → 此时才去拉取原单据数据 → `enableCompare(原单据数据)` 进入对比态。
+
+> 对应参考实现：保存后 `isCompare=false`，点 `compare()` → `getDataH` 拉原单 → `isCompare=true`。
+
+### 职责划分（按钮为 xform 内部 button-widget）
+「变更 / 对比 / 保存」按钮都是**表单内部的 button-widget**，通过配置在 `field.options.onClick` 的自定义脚本触发。脚本运行时：
+- `this` = 按钮组件实例，`this.getFormRef()` 返回 form-render 实例。
+- 注入参数含 `dataId`（当前单据 id）、`formCode`、`event`（表格内按钮另有 `row/rowIndex`）。
+- 可用 `this.getFormRef().$http(...)` 发请求、`this.getFormRef().enableCompare(...)` 开启对比。
+
+因此：
+- **form-render 只负责**：提供 `enableCompare(oldData) / disableCompare() / getDelData() / openCompareDelList()` 与对比渲染；**不主动发请求、不做路由**。
+- **onClick 脚本负责**：拉原单据数据、判断新建/已存、调 `enableCompare`。
+- **无需给 button-widget 新增"对比"动作类型** —— 完全靠 onClick 脚本调用 form-render 的公开方法即可。这一点使内部按钮方案对 xform 核心的改动与外层按钮方案一致。
+
+### 与 form-render 的衔接点
+- 模式 A（新建自动开）：可写在表单的 `onMounted` 脚本或"变更/新增"入口脚本里，判断无 dataId 时 `getFormRef().enableCompare(oldData)`。
+- 模式 B（点对比开）：「对比」按钮 onClick 脚本里拉原单 → `getFormRef().enableCompare(oldData)`。
+
+## 二·六、旧数据的传递与获取（数据流）
+
+> **已封装为通用方法，日常接入看第〇章一行式 `initChangeFromSource`/`enableCompareBySource` 即可。** 本节保留底层原理与手动版，供理解与特殊定制。
+
+xform 的 form-render 通过 `loadFormData` 用 `dataId` + `reportTemplate.formCode` 调后端脚本（`getOne` 或自定义 `formScriptCode`）拉取自己的数据（额外参数来自 `formScriptParam` 脚本），结果经 `setFormData` 注入。`loadOldData` 即复用这套机制，按原单模板对原单 id 自动多包取数。
+
+**核心原则：跨页面传的是「原单 id」，旧数据一律在目标页用 id 向后端拉取，不搬运数据 blob。**（整单+子表数据量大、跨路由易丢失/失真，后端才是快照权威来源。）
+
+### 点「变更」时——传 id，不传数据
+`变更` 打开一张新的变更单（无 dataId），旧数据 = 原单据快照：
+1. `变更` 按钮 onClick：跳转变更单详情页，URL/打开参数带上**原单 id**（如 `?sourceId=xxx`）。
+2. 变更详情页无 dataId，在 `onMounted` / 入口脚本读到 `sourceId`，用 `initChangeFromSource` 一步完成（内部 `loadOldData`→formHttp 取数，一份两用）：
+```js
+if (!dataId) {                       // 新建变更单
+  let formRef = this.getFormRef();
+  let sourceId = formRef.getFormParam() && formRef.getFormParam().sourceId;
+  formRef.initChangeFromSource(sourceId, { sourceFormCode:'原单formCode', compareRowKey:'uuid' });
+}
+```
+> 对应参考：`getOld(原单id)` 既 clone 出新单，又作为 `oldAgreement`。**取数统一走 `loadOldData`（formHttp 按模板脚本发包），不要用 `formRef.$http` 直接打 url。**
+
+### 详情页点「对比」时——用当前单关联 id 反查
+已保存变更单（带 dataId）数据里存有指向原单的引用（如 `sourceId`/`sourceSn`，保存时落库）。`对比` 按钮 onClick：
+```js
+let formRef = this.getFormRef();
+let sourceId = formRef.getFormData().sourceId;   // 当前变更单里存的原单引用
+formRef.enableCompareBySource(sourceId, { sourceFormCode:'原单formCode', compareRowKey:'uuid' });
+```
+
+### 主从表旧数据的获取粒度（多包 vs 单包）
+xform 现状：加载现单时主表 `getOne` 一个包，**每个 data-table 子表各自 `getList`（`taBm=fieldKeyName`）独立发包**（见 `data-table-mixin.loadDefaultViewList`），子表本就是异步/懒加载。旧数据获取与之对称，有两套落地：
+
+**方案一：分表增量（推荐，贴合 xform 异步加载）**
+`loadOldData` 内部即按此思路自动多包（主表 `getOne` + 各 data-table `getList`，均走 `formHttp`）并组装。若要手动控制各包时序，用 `enableCompare(oldMasterData)` 先设主表 + `setOldSubData(name, oldRows)` 增量补子表；子表旧数据同样通过 `formHttp`（按模板脚本）而非 `formRef.$http` 打 url 获取：
+```js
+formRef.enableCompare(master, { compareRowKey: 'uuid' });            // 主表旧数据
+formRef.formHttp({ vue: formRef, scriptCode: 'getList',
+  data: { formCode, formVersion, taBm: '子表A', data: { id } },
+  success: r => formRef.setOldSubData('子表A', (r.objx && r.objx.records) || r.objx || []) });
+```
+优点：与子表懒加载/分 tab 加载天然契合；某子表未加载不阻塞主表对比。
+
+**方案二：一个大包**
+后端提供 `getOldFull(id)` 一次返回主表+所有子表数组，前端 `enableCompare(fullOldData)` 内部遍历所有子表做快照（即"设主表 + 循环 setOldSubData"）。
+- 优点：前端简单、时序可控；缺点：需后端聚合接口，大单据传输量大，且若新子表懒加载未就绪，`getDelData` 需等新子表加载完再算。
+
+> **两种方式都要支持，且共用同一套底层 API，无需两套实现。** 由调用方（按钮 onClick 脚本）自行选择：
+> - 走**多包**就多次调用 `setOldSubData`；
+> - 走**单包**就用聚合数据调一次 `enableCompare(fullOldData)`（其内部即"设主表 + 循环 setOldSubData"）。
+> - 甚至可混用：主表 + 部分子表随主包一次给（`enableCompare` 内处理已带的子表数组），其余子表后续 `setOldSubData` 增量补入。
+>
+> 因此 form-render 的实现要点是：`enableCompare` 能吃"仅主表"或"主表+任意数量子表数组"的 oldData，`setOldSubData` 可被任意次增量调用，两者对同一子表重复设置时以最后一次为准（幂等）。
+
+### 取旧数据的后端约定（二选一）
+- **A（推荐）**：后端提供 `getOld(变更单 dataId)`，直接返回该变更单对应的"变更前快照"（参考实现即此，`agreementChange/getOld`）。前端不必关心原单 id。
+- **B**：变更单里存 `sourceId`，前端读出后调通用 `get(原单id)`。
+
+### 依赖前提
+两种模式都需**后端提供返回"变更前快照"的接口**。这是外部依赖，不在 xform 前端范围内。
+
+## 三、xform 现有架构关键点
+
+- **form-render**（`form-render/indexMixin.js`）持有 `formDataModel`（当前整单数据），暴露 `getFormData/setFormData`，通过 `provide()` 的 `globalModel.formModel` 下发给所有字段。
+- **字段**（`field-widget/fieldMixin.js`）从 `formModel[fieldKeyName]`（或表格内 `tableParam.row[fieldKeyName]`）计算 `fieldModel`。
+- **form-item-wrapper.vue**：渲染字段编辑控件 slot 与只读文本（`getShowValue`），是注入对比图标的统一入口。
+- **三类表格容器**：`sub-form-item`、`table2-item`、`data-table-item`（vxe），单元格都经 `field-widget + tableParam.row` 渲染，旧行快照挂 `tableParam.row.hData`。
+- 现状：xform 中**无任何** `isCompare / hData / compareView` 基础设施，需从零搭建。
+
+## 四、主键约定
+
+- 子表行匹配默认字段 `uuid`，可通过 `enableCompare` 的 options 或 `formConfig.compareRowKey` 覆盖（如 `id`）。
+- 统一匹配 helper：`matchRowKey(rowA, rowB, key = 'uuid')`。
+
+## 五、新增文件
+
+### 1. `form-render/compareView.vue`
+基于参考实现，接口调整以支持字段差异化（见 七·五）：
+- props：`isCompare` / `isDiff` / `oldVal`（展示文本）/ `newVal`（展示文本）。
+- `isCompare && isDiff` → 渲染 `<slot>` + hover popover「变更前：{{ oldVal }}」的 `el-icon-warning` 图标；否则仅渲染 `<slot>`。
+- 差异判定由字段侧（wrapper + fieldMixin.compareEquals）算好通过 `isDiff` 传入，组件本身不再做 `oldVal!=newVal` 裸比。
+- 注册进 form-render 的 components，供 form-item-wrapper 使用。
+
+### 2. `form-render/compareDelList.vue`
+- `el-dialog` + `vxe-grid`，props：`visiable` / `option`（`{ columns, data }`）。
+- 展示某子表被删除的行；列配置由 form-render 依据子表 widget 列自动生成。
+
+## 六、form-render 改造（`indexMixin.js`）
+
+### data 新增（实际实现）
+```js
+isCompare: false,          // 对比开关
+oldFormData: {},           // 旧整单数据（主表字段 + 各子表数组）
+compareRowKey: 'uuid',     // 子表行匹配主键，可被 enableCompare(options)/formConfig 覆盖
+compareExcludeTypes: [     // 不参与对比的字段类型（附件/上传类）
+  'file-upload','picture-upload','baseAttachment','vabUpload','vabUpload2','singleUpload',
+],
+showCompareDelList: false,
+compareDelListOption: {},
+```
+
+### 公开方法（实际实现）
+**对比开关**
+- **`enableCompare(oldData, options)`**：`oldFormData=deepClone(oldData)` → 解析 `compareRowKey`（options / formConfig / 默认）→ `isCompare=true` → 对 `oldData` 中已带的数组子表逐个 `applyCompareSubSnapshot`。
+- **`setOldSubData(subFormName, oldRows)`**：多包/增量设置某子表旧数据（幂等），写 `oldFormData[name]` 并 `applyCompareSubSnapshot(name)`。
+- **`applyCompareSubSnapshot(subFormName)`**（内部）：按 `compareRowKey` 把旧行匹配到当前行，写每行 `hData`；当前子表未加载时仅保留旧数据，加载后可再次调用补做。
+- **`matchCompareRowKey(a, b, rowKey)`**（内部）：按主键匹配两行。
+- **`disableCompare()`**：复位状态、移除各行 `hData`。
+
+**删除行 / 弹窗**
+- **`getDelData(subFormName)`**：**实时计算**（旧数组中当前按主键找不到的行），不缓存。
+- **`openCompareDelList(subFormName, columns)`**：组装 `compareDelListOption` 并弹窗。
+
+**变更跳转（原单侧）**
+- **`goChangeBill(sourceId, formCode, options)`**：跳变更单列表并携带 `sourceId` 打开新增。默认把当前路由最后一段替换为 `formCode`（`options.listPath` 可覆盖），`query.param`=JSON`{sourceId,autoAdd:1}`；先 `tagsView/delCachedView` 清缓存视图再 `router.replace`。
+
+**通用取数（自动多包）**
+- **`loadOldData(sourceId, options)`** → `Promise<oldData>`：先解析模板（`sourceFormCode` 拉原单模板 / 否则复用当前模板）→ 主表 `getOne` 包 + 各 data-table 子表 `getList` 包 → 组装整单返回。
+- **`getCompareSubTables()` / `getCompareSubTablesFrom(widgetList)`**：枚举需独立发包的 data-table 子表。
+- **`fetchTemplateByFormCode(formCode)`** → `Promise<{reportTemplate, formConfig, widgetList}>`：按 formCode 拉模板（`/formTemplate/getByFormCode`）。
+- **`enableCompareBySource(sourceId, options)`**（模式B 一行）：`loadOldData` → `enableCompare`。
+- **`initChangeFromSource(sourceId, options)`**（模式A 一行）：`loadOldData` → `sanitizeChangeData(old, options.sanitize)` → `setFormData(新单)` → `enableCompare(原始旧数据)`。
+
+**数据清洗（变更初始化）**
+- **`sanitizeChangeData(oldData, options)`** → 清洗后克隆：清主/子表系统字段（id/createBy/createDate/modifyBy/modifyDate/_createBy/_modifyBy + snake_case）、子表外键（head_table_id/alias_id/object_foreign_id）、附件白名单精简（attachmentKeepFields）、不覆盖取默认（defaultFields/subDefaultFields）、原单字段回填（subSourceFields）、树表 id/parent_id 重生成（treeSubTables）。
+- **`regenerateTreeIds(rows, idField, parentField)`**（内部）：树表新 id 形如 `_row{随机}`（本表唯一），parent_id 旧→新重映射，外部父级置空作根。
+
+### provide 新增下发（实际实现）
+```js
+getIsCompare: () => e.isCompare,
+getOldFormData: () => e.oldFormData,
+getCompareRowKey: () => e.compareRowKey,
+getCompareExcludeTypes: () => e.compareExcludeTypes,
+```
+
+### 模板
+index.vue 末尾挂：
+```html
+<compareDelList v-if="showCompareDelList" :visiable.sync="showCompareDelList" :option="compareDelListOption" />
+```
+
+## 七、字段展示改造（`form-item-wrapper.vue`）
+
+### inject 新增
+`getIsCompare` / `getOldFormData` / `getCompareRowKey`（均给默认工厂：非对比场景返回 `false` / `{}`，保证旧调用不受影响）。
+
+### computed
+- `isCompareOn = getIsCompare()`（设计态 `this.designer` 存在、或命中排除类型时强制 false）。
+- `oldRawValue`（原始旧值，用于相等判定）：
+  - 表格列字段（`this.tableParam && this.tableParam.row`）：`this.tableParam.row.hData?.[property]`，`property` 复用 `getPropName` 里已有的取列名逻辑（`getFieldKeyName(field)` / vabSearch 特例）。
+  - 主表字段：`getOldFormData()[fieldKeyName]`。
+- `newRawValue`：取 `$parent.fieldModel`。
+- `oldDisplay = $parent.resolveDisplayValue(oldRawValue)`（见 七·五，解析成展示文本）。
+- `newDisplay = getShowValue()`（复用现有展示逻辑）。
+- `isDiff = !$parent.compareEquals(oldRawValue, newRawValue)`（类型化相等判定，见 七·五）。
+
+### 模板包裹
+`isShowWidget()` 编辑分支的 `<slot>` 与只读分支的 `getShowValue()` 外层各包一层：
+```html
+<compareView :isCompare="isCompareOn" :isDiff="isDiff" :oldVal="oldDisplay" :newVal="newDisplay">
+  ...原内容...
+</compareView>
+```
+> compareView 内部按 `isCompare && isDiff` 决定是否显示"变更前"图标+popover（把差异判定从组件内上移到字段侧，以支持差异化比较）。
+
+### 不参与对比的字段类型（重要）
+附件/上传类字段值为文件数组，弹出"变更前"旧值无意义（参考实现的附件 tab 也未包 compareView），需排除。判定：
+```js
+compareExcludeTypes = [
+  'file-upload', 'picture-upload', 'baseAttachment',
+  'vabUpload', 'vabUpload2', 'singleUpload',
+];
+// isCompareOn 计算时叠加：!compareExcludeTypes.includes(this.field.type)
+```
+- 命中排除类型时 `isCompareOn=false`，字段原样渲染，不显示对比图标。
+- 富文本（`rich-editor`）、按钮（`button` 等 static 类）等无值或非数据字段天然不进对比（`newFieldValue` 为空 / 无 fieldModel），可视情况一并纳入排除列表。
+- 排除列表建议做成 form-render 可配置项（`formConfig.compareExcludeTypes`）以便按单据调整。
+
+## 七·五、字段差异化对比规则（核心难点）
+
+不同字段类型的「存储值」与「展示值」不一致，`compareView` 不能简单地 `oldVal != newVal` 裸比、也不能直接把裸值弹出来。现有 `getOptionLabel()` 只解析当前 `this.fieldModel`，无法解析任意旧值，需扩展。
+
+### 各类型的值模型
+| 字段类型 | 存储值 | 展示值 | 相等判定 | 旧值展示 |
+|----------|--------|--------|----------|----------|
+| input / textarea | 字符串 | 同值 | 归一空值后字符串比 | 原值 |
+| number | 数值 | 格式化 | 数值比（`Number()` 归一） | 格式化旧值 |
+| select / radio | code | options.label | code 比 | 用 options 解析旧 code→label |
+| checkbox / 多选 select | code 数组 | 多 label 拼接 | **数组无序比** | 解析旧数组→多 label |
+| switch | 布尔 | 是/否文案 | 布尔比 | 旧布尔→文案 |
+| date / time / date-range | 时间串/数组 | 按 format | 归一后比 | 按 format 展示旧值 |
+| cascader / area | 数组路径 | 路径名拼接 | 数组深比 | 解析旧路径→名称 |
+| 关联搜索 vabsearch/singerSearch/multiSearch | id（另存 `xxxName`） | 关联 name | id 比 | 展示旧 `xxxName` 字段 |
+
+### 判定与展示的分离原则（重要）
+**差异判定一律用「原始存储值」，弹出的「变更前」一律用「展示文本(label)」。** 二者解耦：
+- 下拉/单选/多选：`isDiff` 按 code（数组按 code 集合）比；popover 展示旧 code 解析出的 **label**。
+- 关联搜索（vabsearch 等）：`isDiff` 按 id 比；popover 展示旧记录的 **name（label）**。
+- 即：`isDiff = !compareEquals(oldRaw, newRaw)`（code/id），`oldVal = resolveDisplayValue(oldRaw)`（label）。
+- 好处：code 相同 label 偶然相同/不同都不误判；用户看到的是可读的中文旧值而非编码。
+
+### 设计
+1. **相等判定 `compareEquals(oldRaw, newRaw)`**（放 fieldMixin，可被具体 widget override）：
+   - `null / undefined / '' / []` 之间视为"都为空"→相等；
+   - 数组：长度+元素无序比（多选/cascader/area）；
+   - 对象：按 key 深比；
+   - 标量：`String(a) === String(b)`（吸收 number/string 差异，或按类型精确比）。
+2. **旧值展示 `resolveDisplayValue(rawValue)`**（放 fieldMixin，可 override）：把 `getOptionLabel/getShowValue` 里依赖 `this.fieldModel` 的逻辑改造成"接收任意入参"，对 select/radio/checkbox 用 `optionItems` 解析入参→label；date/number 按格式；其它返回原值。
+3. **compareView 接口调整**：由 wrapper 计算好后传入
+   - `:isCompare`、`:oldVal="oldDisplay"`（已解析文本，用于弹窗展示）、`:newVal="newDisplay"`、`:isDiff="!compareEquals(oldRaw,newRaw)"`（相等判定用原始值，展示用文本）。
+   - compareView 内部：`isCompare && isDiff` 时显示图标 + popover「变更前：{{ oldVal }}」。（相比参考版把"是否差异"的判定从组件内 `oldVal!=newVal` 上移到字段侧，以支持类型化比较。）
+
+### 关联字段的特殊说明
+关联搜索类字段值为 id、展示靠同表的 `xxxName` 字段。由于对比是**逐字段**进行的，`xxxName` 字段本身也会被对比与展示，故：
+- id 字段：`compareEquals` 用 id 比即可；其展示可直接复用 `xxxName`（或在排除列表里让 id 字段不单独弹提示，只让 name 字段弹）。
+- 建议：**对关联字段，只在其 name 展示字段上挂对比提示**，id 字段纳入"不弹提示"集合，避免同一处两个图标。
+
+## 八、"查看删除数据"入口（实际实现）
+未在容器工具栏内置按钮，改由**业务按钮 onClick 脚本**触发（更灵活，不侵入容器）：
+```js
+// 「查看删除数据」按钮 onClick
+this.getFormRef().openCompareDelList('子表字段名');
+// 需中文表头时传列配置：openCompareDelList('子表字段名', [{ field:'xxx', title:'名称' }, ...])
+```
+- `getDelData(name)` 实时算出旧有、当前按主键找不到的行；`compareDelList.vue`（el-dialog + el-table）展示，列未传时按数据 key 自动生成。
+- 按钮可加显示条件（脚本里先判断 `getFormRef().getDelData(name).length`）。
+
+## 九、内部按钮 onClick 脚本调用方式（API 速查）
+
+`this` 为按钮组件，`this.getFormRef()` 取 form-render 实例，注入参数含 `dataId`。**推荐用一行式方法（见第〇章）**，下面是完整 API：
+
+```js
+let f = this.getFormRef();
+
+// 模式A 新建（onMounted）：自动多包取原单 + 清洗 + 填充 + 对比
+f.initChangeFromSource(sourceId, { sourceFormCode:'原单formCode', compareRowKey:'uuid', excludeFields:['status'],
+  sanitize:{ defaultFields:['billType'], subSourceFields:{ 明细A:'f_source_id' }, treeSubTables:['分类明细'] } });
+
+// 模式B 已存（对比按钮）：自动多包取原单 + 对比
+f.enableCompareBySource(sourceId, { sourceFormCode:'原单formCode', compareRowKey:'uuid' });
+
+// 关闭对比
+f.disableCompare();
+
+// 查看某子表删除数据（可传列配置作中文表头）
+f.openCompareDelList('子表字段名');
+
+// —— 底层/手动版（需自定义取数时）——
+f.loadOldData(sourceId, opts).then(old => {          // 仅取数
+  f.setFormData(f.sanitizeChangeData(old, {...}));   // 手动清洗填充
+  f.enableCompare(old, { compareRowKey:'uuid' });    // 手动开启
+});
+f.setOldSubData('子表字段名', 子表旧行);              // 子表旧数据增量补入
+```
+
+## 十、实施进度（已完成）
+1. ✅ `compareView.vue` + form-item-wrapper 注入（主表字段对比）。
+2. ✅ `enableCompare` / `setOldSubData` 子表 `hData` 快照 + 表格单元格对比。
+3. ✅ `getDelData`（实时）+ `compareDelList.vue` + `openCompareDelList`。
+4. ✅ `sanitizeChangeData`（系统字段/外键/自定义/默认值/树表 id 重生成）。
+5. ✅ 通用多包 `loadOldData`（读原单模板自动发包）+ 一行式 `initChangeFromSource` / `enableCompareBySource`。
+
+## 十一、说明 / 注意事项
+- **对比图标注入点**：统一在 `form-item-wrapper.vue`，覆盖主表字段与三类表格容器的单元格（均经 field-widget + tableParam.row 渲染）；仅对比态包裹 compareView，非对比态零改动。
+- **「查看删除数据」按钮**：未在容器工具栏内置，由业务按钮 onClick 调 `openCompareDelList('子表名')` 触发（更灵活）。
+- **子表快照时序**：`enableCompare`/`setOldSubData` 对当前已加载行打 `hData` 快照；若子表在开启对比后才异步加载，需在其加载完成后再调一次 `setOldSubData` 补快照（多包流程天然满足）。
+- **vxe data-table 行引用**：依赖 `formDataModel[子表名]` 与表格行同引用，`hData` 才能被单元格读到——建议用真实带子表的变更单验证。
+- **性能**：大子表逐行 deepClone `hData`，行数极大时需评估（可改为只存差异或懒计算）。